Consultar bancos de dados externos usando a função `remote_query`

info

Visualização

Este recurso está em Visualização Pública.

A função de valor de tabela remote_query (TVF) permite que você execute consultas SQL diretamente em bancos de dados externos e data warehouse de dentro Databricks, usando a sintaxe SQL nativa do sistema remoto. Esta função fornece uma alternativa flexível à federação de consultas, permitindo que você execute consultas escritas no dialeto do banco de dados remoto sem precisar traduzi-las para o Databricks SQL.

`remote_query` comparado à federação de consultas

A tabela a seguir resume as key diferenças entre a função remote_query e a federação de consultas:

Atributo	`remote_query` função	Federação de consultas
Sintaxe de consulta	Escreva consultas usando o dialeto SQL nativo do banco de dados remoto (por exemplo, Oracle PL/SQL, BigQuery SQL).	Escreva consultas usando a sintaxe Databricks SQL . O Databricks traduz e envia operações compatíveis para o banco de dados remoto.
Caso de uso	Você tem consultas SQL existentes escritas no dialeto do banco de dados remoto que deseja executar sem modificação. Você precisa usar funções ou sintaxe específicas do banco de dados que podem não estar disponíveis no Databricks SQL. Você deseja acesso ad hoc a dados remotos sem criar catálogos externos.	Você deseja consultar a sintaxe Databricks SQL externo. Você precisa de um padrão de acesso a dados de longo prazo com acesso governado por meio de catálogos estrangeiros do Unity Catalog. Você deseja combinar dados de várias fontes em uma única consulta usando uma sintaxe consistente. Você quer usar o assistente Genie para escrever consultas.
Controle de acesso	Os usuários precisam do privilégio `USE CONNECTION` na conexão. A permissão pode ser delegada por meio da visualização.	Os usuários precisam de privilégios de nível de tabela em objetos de catálogo externo. Controle refinado.

Antes de começar

Requisitos do workspace:

Espaço de trabalho preparado para o Catálogo do Unity.

Requisitos de computação:

Conectividade de rede do seu cluster do Databricks Runtime ou SQL warehouse para os sistemas de banco de dados de destino. Veja recomendações de rede para a Federação Lakehouse.
clusters Databricks devem usar Databricks Runtime 17.3 ou superior.
SQL Warehouse deve ser Pro ou serverless e usar a versão 2025.35 ou superior.

Permissões necessárias:

Para criar uma conexão, você deve ser um administrador do metastore ou um usuário com o privilégio CREATE CONNECTION no metastore do Unity Catalog.
Para usar a função remote_query , você deve ter o privilégio USE CONNECTION na conexão ou o privilégio SELECT em uma view que encapsula a função. Os clusters de usuário único também exigem a permissão MANAGE na conexão.

Crie uma conexão

Para usar a função remote_query , primeiro você precisa criar uma conexão do Unity Catalog com seu banco de dados externo. Se você já tiver uma conexão criada para federação de consultas, poderá reutilizá-la.

A função remote_query suporta conexões com os seguintes tipos de conexão:

Para obter informações sobre como gerenciar conexões existentes, consulte gerenciar conexões para a Lakehouse Federation.

Conceder acesso à conexão

Para usar a função remote_query , você deve ter o privilégio USE CONNECTION na conexão (ou o privilégio MANAGE em clusters de usuário único).

SQL
GRANT USE CONNECTION ON CONNECTION <connection-name> TO <user-or-group>;

Use a função `remote_query`

A função remote_query executa uma consulta no banco de dados remoto e retorna os resultados como uma tabela que você pode usar em consultas Databricks SQL .

Sintaxe

SQL
SELECT * FROM remote_query(
  '<connection-name>',
  <option-key> => '<option-value>'
  [, <option-key> => '<option-value>' ...]
)

Parâmetros obrigatórios

connection-name: O nome da conexão do Unity Catalog a ser usada.

Todos os outros parâmetros necessários variam de acordo com o tipo de conexão. Consulte Opções específicas do conector para obter detalhes.

Opções específicas do conector

As opções disponíveis variam de acordo com o tipo de conexão. As tabelas a seguir descrevem as opções para cada conector.

MySQL, PostgreSQL, SQL Server, Redshift e Teradata

Parâmetro	Obrigatório	Descrição
`database`	Sim	O nome do banco de dados no sistema remoto.
`query`	Sim (ou `dbtable`)	Uma sequência de consulta SQL para execução no banco de dados remoto. Não pode ser usado com `dbtable`.
`dbtable`	Sim (ou `query`)	O nome da tabela a ser consultada. Não pode ser usado com `query`.
`fetchsize`	Não	O número de linhas a serem buscadas por viagem de ida e volta. Valores maiores podem melhorar o desempenho, mas usam mais memória. padrão: 0 (usar driver default).
`partitionColumn`	Não	Uma coluna com valores distribuídos uniformemente para uso na busca de dados paralela. Deve ser usado com `lowerBound`, `upperBound` e `numPartitions`. Não pode ser usado com a opção `query` .
`lowerBound`	Não	O valor mínimo da coluna de partição. Deve ser usado com `partitionColumn`, `upperBound` e `numPartitions`.
`upperBound`	Não	O valor máximo da coluna de partição. Deve ser usado com `partitionColumn`, `lowerBound` e `numPartitions`.
`numPartitions`	Não	O número de conexões paralelas a serem usadas para buscar dados. Não defina um valor muito alto (centenas). Deve ser usado com `partitionColumn`, `lowerBound` e `upperBound`.

nota

Ao usar parâmetros de partição, todos os quatro parâmetros (partitionColumn, lowerBound, upperBound, numPartitions) devem ser especificados juntos, e você deve usar a opção dbtable em vez de query.

Oráculo

Parâmetro	Obrigatório	Descrição
`serviceName`	Sim	O nome do serviço Oracle (usado em vez de `database`).
`query`	Sim (ou `dbtable`)	Uma sequência de consulta SQL para execução no banco de dados remoto. Não pode ser usado com `dbtable`.
`dbtable`	Sim (ou `query`)	O nome da tabela a ser consultada. Não pode ser usado com `query`.
`fetchsize`	Não	O número de linhas a serem buscadas por viagem de ida e volta. Valores maiores podem melhorar o desempenho, mas usam mais memória. padrão: 0 (usar driver default).
`partitionColumn`	Não	Uma coluna com valores distribuídos uniformemente para uso na busca de dados paralela. Deve ser usado com `lowerBound`, `upperBound` e `numPartitions`. Não pode ser usado com a opção `query` .
`lowerBound`	Não	O valor mínimo da coluna de partição. Deve ser usado com `partitionColumn`, `upperBound` e `numPartitions`.
`upperBound`	Não	O valor máximo da coluna de partição. Deve ser usado com `partitionColumn`, `lowerBound` e `numPartitions`.
`numPartitions`	Não	O número de conexões paralelas a serem usadas para buscar dados. Não defina um valor muito alto (centenas). Deve ser usado com `partitionColumn`, `lowerBound` e `upperBound`.

nota

Snowflake

Parâmetro	Obrigatório	Descrição
`database`	Sim	O nome do banco de dados no Snowflake.
`query`	Sim (ou `dbtable`)	Uma sequência de consulta SQL para execução no banco de dados remoto. Não pode ser usado com `dbtable`.
`dbtable`	Sim (ou `query`)	O nome da tabela a ser consultada (nome de parte única ou nome de várias partes). Não pode ser usado com `query`.
`schema`	Não	O nome do esquema no Snowflake. padrão: `public`.
`query_timeout`	Não	Tempo limite da consulta em segundos. padrão: 0 (sem tempo limite).
`partition_size_in_mb`	Não	O tamanho esperado da partição em megabytes para busca paralela de dados. padrão: 100 MB.

BigQuery

Parâmetro	Obrigatório	Descrição
`query`	Sim (ou `dbtable`)	Uma sequência de consulta SQL para execução no banco de dados remoto. Não pode ser usado com `dbtable`.
`dbtable`	Sim (ou `query`)	O nome da tabela a ser consultada. Não pode ser usado com `query`.
`materializationDataset`	Sim, se for necessária a materialização de resultados. A materialização é necessária se `query` for especificado e se `dbtable` apontar para uma view.	O nome dataset BigQuery onde as tabelas temporárias são materializadas. O tempo de vida (TTL) default das tabelas temporárias é de 24 horas.
`materializationProject`	Não	O ID do projeto do BigQuery para materialização. padrão para o projeto especificado na conexão.
`materializationEnabled`	Não	Se deve habilitar a materialização para consultas. Defina como `true` para consultar a visualização. padrão: `false` se `dbtable` for especificado, `true` se `query` for especificado.
`parentProject`	Não	O ID do projeto pai para fins de cobrança.

importante

Todos os parâmetros do BigQuery diferenciam maiúsculas de minúsculas.

Opções adicionais de controle de pushdown

Você pode combinar a função remote_query com as operações Databricks SQL , e a maioria dessas operações também pode ser aplicada. Você também pode controlar quais operações Databricks SQL podem ser enviadas. Essas opções se aplicam a todos os tipos de conexão e não diferenciam maiúsculas de minúsculas.

Parâmetro	Padrão	Descrição
`pushdown.limit.enabled`	`true`	Habilitar ou desabilitar o envio de cláusulas `LIMIT` para o banco de dados remoto.
`pushdown.offset.enabled`	`true`	Habilitar ou desabilitar o envio de cláusulas `OFFSET` para o banco de dados remoto.
`pushdown.filters.enabled`	`true`	Habilitar ou desabilitar o envio de filtros `WHERE` para o banco de dados remoto.
`pushdown.aggregates.enabled`	`true`	Habilita ou desabilita o envio de funções agregadas (`COUNT`, `SUM`, `AVG`, `MAX`, `MIN`) para o banco de dados remoto.
`pushdown.sortLimit.enabled`	`true`	Habilita ou desabilita o envio de consultas top-N (combinação de `ORDER BY` e `LIMIT`) para o banco de dados remoto.

Por default, todos os pushdowns estão habilitados. Você pode desabilitar pushdowns específicos, se necessário, para solucionar problemas ou contornar problemas de compatibilidade com bancos de dados remotos específicos.

Delegar acesso por meio da visualização

Você pode delegar acesso a dados remotos sem conceder aos usuários privilégios USE CONNECTION diretos, encapsulando a função remote_query em uma view. Essa abordagem tem os seguintes benefícios:

Controle de acesso simplificado : conceda privilégio SELECT na view em vez de gerenciar privilégios USE CONNECTION .
Segurança de dados : controle quais colunas e linhas os usuários podem acessar definindo a consulta view .
Rastrear linhagem : rastreie o acesso aos dados por meio da view da linhagem em vez do uso direto da conexão.

Para delegar acesso por meio de uma view:

Crie uma view que chame a função remote_query :

SQL
CREATE VIEW sales_data_view AS
SELECT * FROM remote_query(
  'my_connection',
  database => 'sales_db',
  query => 'SELECT region, product, revenue FROM sales'
);

Conceder privilégio SELECT na view para usuários ou grupos:

SQL
GRANT SELECT ON VIEW sales_data_view TO <user-or-group>;

Os usuários agora podem consultar a view sem precisar do privilégio USE CONNECTION :
SQL
```
SELECT * FROM sales_data_view WHERE region = 'US';
```

importante

O proprietário view deve ter privilégio USE CONNECTION na conexão. Quando os usuários consultam a view, a verificação de acesso à conexão é realizada usando os privilégios do proprietário view , não os privilégios do usuário que faz a consulta.

Exemplos

Execução básica de consulta

Execute uma consulta em um banco de dados PostgreSQL:

SQL
SELECT * FROM remote_query(
  'my_postgres_connection',
  database => 'sales_db',
  query => 'SELECT * FROM orders WHERE order_date > CURRENT_DATE - INTERVAL \'30 days\''
);

Consultar uma tabela específica

Consultar uma tabela MySQL diretamente:

SQL
SELECT * FROM remote_query(
  'my_mysql_connection',
  database => 'inventory',
  dbtable => 'my_schema.products'
);

Oracle com nome de serviço

Consultar um banco de dados Oracle:

SQL
SELECT * FROM remote_query(
  'my_oracle_connection',
  serviceName => 'ORCL',
  query => 'SELECT * FROM customers WHERE ROWNUM <= 1000'
);

Consulta do BigQuery

Consultar Google BigQuery:

SQL
SELECT * FROM remote_query(
  'my_bigquery_connection',
  materializationDataset => 'analytics',
  query => 'SELECT * FROM `project.dataset.table` WHERE created_date > DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)'
);

Consulta deSnowflake

Consulta Snowflake:

SQL
SELECT * FROM remote_query(
  'my_snowflake_connection',
  database => 'ANALYTICS_DB',
  query => 'SELECT * FROM SALES WHERE SALE_DATE >= DATEADD(day, -30, CURRENT_DATE())'
);

Ajuste de desempenho com particionamento

Buscar dados em paralelo de uma tabela do SQL Server:

SQL
SELECT * FROM remote_query(
  'my_sqlserver_connection',
  database => 'sales',
  dbtable => 'transactions',
  partitionColumn => 'transaction_id',
  lowerBound => '0',
  upperBound => '1000000',
  numPartitions => '10',
  fetchsize => '1000'
);

Combine com operações Databricks SQL

Aplique filtros e transformações adicionais:

SQL
SELECT customer_id, SUM(amount) as total_amount
FROM remote_query(
  'my_postgres_connection',
  database => 'orders_db',
  query => 'SELECT customer_id, amount, order_date FROM orders'
)
WHERE order_date >= '2025-01-01'
GROUP BY customer_id
HAVING total_amount > 1000
ORDER BY total_amount DESC
LIMIT 100;

Crie uma view para acesso delegado

Crie uma view que envolva a função remote_query . Usuários com privilégio SELECT na view podem consultar os dados sem precisar de privilégio USE CONNECTION na conexão subjacente:

SQL
CREATE VIEW sales_summary AS
SELECT * FROM remote_query(
  'my_mysql_connection',
  database => 'sales',
  query => 'SELECT region, product, SUM(revenue) as total_revenue FROM sales_data GROUP BY region, product'
);

GRANT SELECT ON VIEW sales_summary TO <user-or-group>;

Comportamento de pushdown de controle

Quando você usa a função remote_query , o Databricks pode enviar operações adicionais para o banco de dados remoto além da consulta especificada. Este recurso é útil quando você consulta uma view que usa a função remote_query .

As seguintes operações podem ser empurradas para baixo:

Filtros : WHERE cláusulas aplicadas ao resultado da consulta remota
Projeções : Seleção de colunas (SELECT colunas específicas)
Limite : LIMIT cláusulas para restringir o número de linhas retornadas
Offset : OFFSET cláusulas para pular linhas
Agregados : Funções de agregação como COUNT, SUM, AVG, MAX, MIN
Top-N : Combinação de ORDER BY e LIMIT para consultas top/bottom N

O suporte a pushdown varia de acordo com a fonte de dados. Consulte a documentação do seu tipo de conexão específico para obter detalhes.

Desabilite pushdowns específicos para solução de problemas ou compatibilidade:

SQL
SELECT * FROM remote_query(
  'my_postgres_connection',
  database => 'analytics',
  query => 'SELECT * FROM complex_view',
  `pushdown.aggregates.enabled` => 'false',
  `pushdown.filters.enabled` => 'false'
);

Limitações

Operações somente leitura : A função remote_query suporta apenas consultas SELECT . Operações de modificação de dados (INSERT, UPDATE, DELETE, merge), operações DDL (CREATE, DROP, ALTER) e procedimentos armazenados não são suportados.
Validação de consulta : a consulta fornecida é executada diretamente no banco de dados remoto. O Databricks valida se a consulta é somente leitura executando a inspeção do esquema, mas a validação de sintaxe e semântica é realizada pelo banco de dados remoto.

Solução de problemas

Erros de permissão

Se você receber um erro de permissão, verifique se:

Você tem o privilégio USE CONNECTION na conexão ou o privilégio SELECT em uma view que encapsula a função.
As credenciais na conexão têm permissões apropriadas no banco de dados remoto.

Exemplo de erro:

PERMISSION_DENIED: User does not have USE CONNECTION on Connection 'my_connection'

Resolução:

SQL
GRANT USE CONNECTION ON CONNECTION my_connection TO <user-or-group>;

Parâmetros não suportados

Se você receber um erro sobre parâmetros não suportados, verifique se está usando os parâmetros corretos para seu tipo de conexão. A mensagem de erro lista os parâmetros permitidos.

Exemplo de erro:

REMOTE_QUERY_FUNCTION_UNSUPPORTED_CONNECTOR_PARAMETERS: The following parameters are not supported for connection type 'postgresql': 'materializationDataset'. Allowed parameters for this connection type are: 'database', 'query', 'dbtable', 'fetchsize', 'partitionColumn', 'lowerBound', 'upperBound', 'numPartitions'.

Resolução: Remova o parâmetro não suportado e use os parâmetros corretos para seu tipo de conexão.

Operações DML não suportadas

A função remote_query suporta apenas consultas somente leitura SELECT .

Exemplo de erro:

DML_OPERATIONS_NOT_SUPPORTED_FOR_REMOTE_QUERY_FUNCTION: Data modification operations are not supported in remote_query function.

Resolução: Remova quaisquer instruções INSERT, UPDATE, DELETE ou DDL da sua consulta. Use somente instruções SELECT.

remote_query comparado à federação de consultas​

Antes de começar​

Crie uma conexão​

Conceder acesso à conexão​

Use a função remote_query​

Sintaxe​

Parâmetros obrigatórios​

Opções específicas do conector​

MySQL, PostgreSQL, SQL Server, Redshift e Teradata​

Oráculo​

Snowflake​

BigQuery​

Opções adicionais de controle de pushdown​

Delegar acesso por meio da visualização​

Exemplos​

Execução básica de consulta​

Consultar uma tabela específica​

Oracle com nome de serviço​

Consulta do BigQuery​

Consulta deSnowflake​

Ajuste de desempenho com particionamento​

Combine com operações Databricks SQL​

Crie uma view para acesso delegado​

Comportamento de pushdown de controle​

Limitações​

Solução de problemas​

Erros de permissão​

Parâmetros não suportados​

Operações DML não suportadas​

Recurso adicional​

`remote_query` comparado à federação de consultas

Antes de começar

Crie uma conexão

Conceder acesso à conexão

Use a função `remote_query`

Sintaxe

Parâmetros obrigatórios

Opções específicas do conector

MySQL, PostgreSQL, SQL Server, Redshift e Teradata

Oráculo

Snowflake

BigQuery

Opções adicionais de controle de pushdown

Delegar acesso por meio da visualização

Exemplos

Execução básica de consulta

Consultar uma tabela específica

Oracle com nome de serviço

Consulta do BigQuery

Consulta deSnowflake

Ajuste de desempenho com particionamento

Combine com operações Databricks SQL

Crie uma view para acesso delegado

Comportamento de pushdown de controle

Limitações

Solução de problemas

Erros de permissão

Parâmetros não suportados

Operações DML não suportadas

Recurso adicional