Consulta de bases de datos externas mediante la `remote_query` función

Importante

Esta característica está en versión preliminar pública.

La remote_query función con valores de tabla (TVF) permite ejecutar consultas SQL directamente en bases de datos externas y almacenes de datos desde Azure Databricks mediante la sintaxis SQL nativa del sistema remoto. Esta función proporciona una alternativa flexible a la federación de consultas, lo que le permite ejecutar consultas escritas en el dialecto de la base de datos remota sin necesidad de traducirlas a Databricks SQL.

`remote_query` en comparación con la federación de consultas

En la tabla siguiente se resumen las diferencias clave entre la remote_query función y la federación de consultas.

Atributo	`remote_query` Función	Federación de consultas
Sintaxis de consulta	Escriba consultas mediante el dialecto SQL nativo de la base de datos remota (por ejemplo, Oracle PL/SQL, BigQuery SQL).	Escriba consultas mediante la sintaxis SQL de Databricks. Databricks traduce y delega operaciones compatibles a la base de datos remota.
Caso de uso	Tiene consultas SQL existentes escritas en el dialecto de la base de datos remota que desea ejecutar sin modificaciones. Debe usar funciones o sintaxis específicas de la base de datos que podrían no estar disponibles en Databricks SQL. Quieres acceso ad hoc a datos remotos sin crear catálogos foráneos.	Quiere consultar datos externos mediante la sintaxis SQL de Databricks. Necesita un patrón de acceso a datos a largo plazo con acceso regulado a través de catálogos externos de Unity Catalog. Quiere combinar datos de varios orígenes en una sola consulta mediante una sintaxis coherente. Quieres usar el asistente de Genie para redactar consultas.
Control de acceso	Los usuarios necesitan `USE CONNECTION` privilegios en la conexión. El permiso se puede delegar a través de vistas.	Los usuarios necesitan privilegios de nivel de tabla en objetos de catálogo externos. Control detallado.

Antes de empezar

Requisitos del área de trabajo:

Área de trabajo habilitada para Unity Catalog.

Requisitos de proceso:

Conectividad de red desde el clúster de Databricks Runtime o el almacén de SQL a los sistemas de base de datos de destino. Consulte Recomendaciones de redes para Lakehouse Federation.
Los clústeres de Azure Databricks deben usar Databricks Runtime 17.3 o superior.
Los almacenes de SQL deben ser Pro o Sin servidor y usar la versión 2025.35 o superior.

Permisos necesarios:

Para crear una conexión, debe tener el CREATE CONNECTION privilegio en el metastore del Unity Catalog.
Para usar la función remote_query, debe tener el privilegio USE CONNECTION en la conexión o el privilegio SELECT en una vista que envuelve la función. Los clústeres de usuario único también requieren permiso MANAGE para la conexión.

Crear una conexión

Para usar la función remote_query, primero debe crear una conexión de Unity Catalog a la base de datos externa. Si ya tiene una conexión creada para la federación de consultas, puede reutilizarla.

La remote_query función admite conexiones a los siguientes tipos de conexión:

Para obtener información sobre cómo administrar las conexiones existentes, consulte Administración de conexiones para la federación de Lakehouse.

Concesión de acceso a la conexión

Para usar laremote_query función, debe tener elUSE CONNECTION privilegio en la conexión (o elMANAGE privilegio en clústeres monousuario).

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

Use la función `remote_query`

La remote_query función ejecuta una consulta en la base de datos remota y devuelve los resultados como una tabla que puede usar en las consultas SQL de Databricks.

Syntax

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

Parámetros necesarios

connection-name: el nombre de la conexión del catálogo de Unity que se va a usar.

Todos los demás parámetros necesarios varían según el tipo de conexión. Consulte Opciones específicas del conector para obtener más información.

Opciones específicas del conector

Las opciones disponibles varían según el tipo de conexión. En las tablas siguientes se describen las opciones de cada conector.

MySQL, PostgreSQL, SQL Server, Redshift y Teradata

Parámetro	Obligatorio	Description
`database`	Sí	Nombre de la base de datos en el sistema remoto.
`query`	Sí (o `dbtable`)	Cadena de consulta SQL que se va a ejecutar en la base de datos remota. No se puede usar con `dbtable`.
`dbtable`	Sí (o `query`)	El nombre de la tabla a consultar. No se puede usar con `query`.
`fetchsize`	No	Número de filas que se van a capturar por recorrido de ida y vuelta. Los valores más grandes pueden mejorar el rendimiento, pero usar más memoria. Valor por defecto: 0 (usa el del controlador).
`partitionColumn`	No	Columna con valores distribuidos uniformemente que se van a usar para la captura de datos en paralelo. Debe usarse con `lowerBound`, `upperBound`y `numPartitions`. No se puede usar con la `query` opción .
`lowerBound`	No	Valor mínimo de la columna de partición. Debe usarse con `partitionColumn`, `upperBound`y `numPartitions`.
`upperBound`	No	Valor máximo de la columna de partición. Debe usarse con `partitionColumn`, `lowerBound`y `numPartitions`.
`numPartitions`	No	Número de conexiones paralelas que se van a usar para capturar datos. No establezca esto demasiado alto (cientos). Debe usarse con `partitionColumn`, `lowerBound`y `upperBound`.

Nota:

Cuando se utilizan parámetros de partición, los cuatro parámetros (partitionColumn, lowerBound, upperBound, numPartitions) deben especificarse juntos, y debe utilizar la opción dbtable en lugar de query.

Oracle

Parámetro	Obligatorio	Description
`service_name`	Sí	Nombre del servicio oracle (usado en lugar de `database`).
`query`	Sí (o `dbtable`)	Cadena de consulta SQL que se va a ejecutar en la base de datos remota. No se puede usar con `dbtable`.
`dbtable`	Sí (o `query`)	El nombre de la tabla a consultar. No se puede usar con `query`.
`fetchsize`	No	Número de filas que se van a capturar por recorrido de ida y vuelta. Los valores más grandes pueden mejorar el rendimiento, pero usar más memoria. Valor por defecto: 0 (usa el del controlador).
`partitionColumn`	No	Columna con valores distribuidos uniformemente que se van a usar para la captura de datos en paralelo. Debe usarse con `lowerBound`, `upperBound`y `numPartitions`. No se puede usar con la `query` opción .
`lowerBound`	No	Valor mínimo de la columna de partición. Debe usarse con `partitionColumn`, `upperBound`y `numPartitions`.
`upperBound`	No	Valor máximo de la columna de partición. Debe usarse con `partitionColumn`, `lowerBound`y `numPartitions`.
`numPartitions`	No	Número de conexiones paralelas que se van a usar para capturar datos. No establezca esto demasiado alto (cientos). Debe usarse con `partitionColumn`, `lowerBound`y `upperBound`.

Nota:

Snowflake

Parámetro	Obligatorio	Description
`database`	Sí	Nombre de la base de datos en Snowflake.
`query`	Sí (o `dbtable`)	Cadena de consulta SQL que se va a ejecutar en la base de datos remota. No se puede usar con `dbtable`.
`dbtable`	Sí (o `query`)	Nombre de tabla que se va a consultar (nombre de una sola parte o nombre de varias partes). No se puede usar con `query`.
`schema`	No	Nombre del esquema en Snowflake. Predeterminado: `public`.
`query_timeout`	No	Tiempo de espera de la consulta en segundos. Valor predeterminado: 0 (sin tiempo de espera).
`partition_size_in_mb`	No	Tamaño de partición esperado en megabytes para la captura de datos en paralelo. Valor predeterminado: 100 MB.

BigQuery

Parámetro	Obligatorio	Description
`query`	Sí (o `dbtable`)	Cadena de consulta SQL que se va a ejecutar en la base de datos remota. No se puede usar con `dbtable`.
`dbtable`	Sí (o `query`)	El nombre de la tabla a consultar. No se puede usar con `query`.
`materializationDataset`	Sí, si se necesita materialización de resultados. La materialización es necesaria si `query` se especifica y si `dbtable` apunta a una vista.	Nombre del conjunto de datos de BigQuery donde se materializan las tablas temporales. El período de vida predeterminado (TTL) de las tablas temporales es de 24 horas.
`materializationProject`	No	Identificador de proyecto de BigQuery para la materialización. Se establece por defecto el proyecto especificado en la conexión.
`materializationEnabled`	No	Si se va a habilitar la materialización de las consultas. Establézcalo en `true` para consultar vistas. Valor predeterminado: `false` si `dbtable` se especifica, `true` si `query` se especifica.
`parentProject`	No	Identificador del proyecto principal con fines de facturación.

Importante

Todos los parámetros de BigQuery distinguen mayúsculas de minúsculas.

Opciones adicionales de control de reducción

También puede combinar la función remote_query con operaciones SQL de Databricks, y la mayoría de esas operaciones también se pueden desplazar hacia abajo. También puede controlar qué operaciones SQL de Databricks se pueden delegar. Estas opciones se aplican a todos los tipos de conexión y no distinguen mayúsculas de minúsculas.

Parámetro	Predeterminado	Description
`pushdown.limit.enabled`	`true`	Habilite o deshabilite la propagación de cláusulas `LIMIT` a la base de datos remota.
`pushdown.offset.enabled`	`true`	Habilite o deshabilite la propagación de cláusulas `OFFSET` a la base de datos remota.
`pushdown.filters.enabled`	`true`	Habilite o deshabilite la inserción de `WHERE` filtros en la base de datos remota.
`pushdown.aggregates.enabled`	`true`	Habilite o deshabilite el traslado de funciones de agregado (`COUNT`, `SUM`, `AVG`, `MAX`, `MIN`) a la base de datos remota.
`pushdown.sortLimit.enabled`	`true`	Habilite o deshabilite el envío de consultas top-N (combinación de `ORDER BY` y `LIMIT`) a la base de datos remota.

De forma predeterminada, todas las optimizaciones pushdown están habilitadas. Puede deshabilitar instrucciones push específicas si es necesario para solucionar problemas de compatibilidad o solucionar problemas de compatibilidad con bases de datos remotas específicas.

Delegar el acceso a través de vistas

Puede delegar el acceso a datos remotos sin conceder privilegios directos USE CONNECTION a los usuarios envolviendo la función remote_query en una vista. Este procedimiento tiene las siguientes ventajas:

Control de acceso simplificado: conceda SELECT privilegios en la vista en lugar de administrar USE CONNECTION privilegios.
Seguridad de datos: controle a qué columnas y filas pueden acceder los usuarios mediante la definición de la consulta de vista.
Seguimiento del linaje: seguir el acceso a los datos a través del linaje de vistas en lugar de usar conexiones directas.

Para delegar el acceso a través de una vista:

Cree una vista que llame a la función remote_query.

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

Conceda SELECT privilegios en la vista a usuarios o grupos:

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

Los usuarios ahora pueden consultar la vista sin necesidad de privilegios USE CONNECTION :
```
SELECT * FROM sales_data_view WHERE region = 'US';
```

Importante

El propietario de la vista debe tener USE CONNECTION privilegio en la conexión. Cuando los usuarios consultan la vista, la comprobación de acceso a la conexión se realiza mediante los privilegios del propietario de la vista, no con los privilegios del usuario que realiza la consulta.

Examples

Ejecución básica de consultas

Ejecute una consulta en una base de datos postgreSQL:

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

Consulta de una tabla específica

Consulte directamente una tabla mySQL:

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

Oracle con el nombre del servicio

Consulta de una base de datos de Oracle:

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

Consulta de BigQuery

Consulta de Google BigQuery:

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 de Snowflake

Consulta Snowflake

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

Optimización del rendimiento con creación de particiones

Capturar datos en paralelo desde una tabla de SQL Server:

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

Combinar con operaciones SQL de Databricks

Aplique filtros y transformaciones adicionales:

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;

Creación de una vista para el acceso delegado

Cree una vista que encapsula la remote_query función. Los usuarios con SELECT privilegio en la vista pueden consultar los datos sin necesidad de privilegio USE CONNECTION en la conexión subyacente.

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>;

Control del comportamiento de apilamiento

Cuando se usa la remote_query función, Databricks puede insertar operaciones adicionales en la base de datos remota más allá de la consulta que especifique. Esta característica es útil cuando se consulta una vista que usa la remote_query función .

Las siguientes operaciones se pueden insertar:

Filtros: WHERE aplicadas al resultado de la consulta remota
Proyecciones: selección de columnas (SELECT columnas específicas)
Límite: LIMIT cláusulas para restringir el número de filas devueltas
Desplazamiento: OFFSET cláusulas para omitir filas
Agregados: funciones de agregación como COUNT, SUM, AVG, , MAX, MIN
Top-N: combinación de ORDER BY y LIMIT para consultas N superior/inferior

La compatibilidad de procesamiento varía según la fuente de datos. Consulte la documentación del tipo de conexión específico para obtener más información.

Deshabilite empujes específicos para la solución de problemas o para compatibilidad.

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

Limitaciones

Operaciones de solo lectura: la remote_query función solo admite SELECT consultas. No se admiten las operaciones de modificación de datos (INSERT, , UPDATEDELETE, MERGE), las operaciones DDL (CREATE, DROP, ALTER) y los procedimientos almacenados.
Validación de consultas: la consulta que proporcione se ejecuta directamente en la base de datos remota. Databricks valida que la consulta es de solo lectura mediante la inspección del esquema, pero la sintaxis y la validación semántica las realiza la base de datos remota.

Solución de problemas

Errores de permisos

Si recibe un error de permiso, compruebe que:

Tiene el USE CONNECTION privilegio en la conexión o el SELECT privilegio en una vista que envuelve la función.
Las credenciales de la conexión tienen los permisos adecuados en la base de datos remota.

Error de ejemplo:

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

Resolución:

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

Parámetros no admitidos

Si recibe un error sobre los parámetros no admitidos, compruebe que usa los parámetros correctos para el tipo de conexión. El mensaje de error muestra los parámetros permitidos.

Error de ejemplo:

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'.

Solución: quite el parámetro no admitido y use los parámetros correctos para el tipo de conexión.

No se admiten operaciones DML

La remote_query función solo admite consultas de solo SELECT lectura.

Error de ejemplo:

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

Resolución: elimine las INSERT, UPDATE, DELETE o DDL de la consulta. Solo utilice instrucciones SELECT.

Recursos adicionales

Oharrak

Lagungarria al da orri hau?

Last updated on 2026-01-30

Partekatu honen bidez:

Consulta de bases de datos externas mediante la remote_query función

remote_query en comparación con la federación de consultas

Antes de empezar

Crear una conexión

Concesión de acceso a la conexión

Use la función remote_query

Syntax

Parámetros necesarios

Opciones específicas del conector

MySQL, PostgreSQL, SQL Server, Redshift y Teradata

Oracle

Snowflake

BigQuery

Opciones adicionales de control de reducción

Delegar el acceso a través de vistas

Examples

Ejecución básica de consultas

Consulta de una tabla específica

Oracle con el nombre del servicio

Consulta de BigQuery

Consulta de Snowflake

Optimización del rendimiento con creación de particiones

Combinar con operaciones SQL de Databricks

Creación de una vista para el acceso delegado

Control del comportamiento de apilamiento

Limitaciones

Solución de problemas

Errores de permisos

Parámetros no admitidos

No se admiten operaciones DML

Recursos adicionales

Oharrak

Baliabide gehigarriak

Consulta de bases de datos externas mediante la `remote_query` función

`remote_query` en comparación con la federación de consultas

Use la función `remote_query`