Interroger des bases de données externes à l’aide de la `remote_query` fonction

Important

Cette fonctionnalité est disponible en préversion publique.

La remote_query fonction valorisée par table (TVF) vous permet d'exécuter des requêtes SQL directement contre des bases de données externes et des entrepôts de données depuis Azure Databricks, en utilisant la syntaxe SQL native du système distant. Cette fonction offre une alternative flexible à la fédération des requêtes, ce qui vous permet d’exécuter des requêtes écrites dans le dialecte de la base de données distante sans avoir à les traduire en Databricks SQL.

`remote_query` en comparaison avec la fédération de requêtes

Le tableau suivant résume les principales différences entre la fonction et la remote_query fédération de requête :

Caractéristique	`remote_query` Fonction	Fédération des requêtes
Syntaxe de requête	Écrivez des requêtes à l’aide du dialecte SQL natif de la base de données distante (par exemple, Oracle PL/SQL, BigQuery SQL).	Écrire des requêtes à l’aide de la syntaxe SQL Databricks. Databricks traduit et envoie des opérations compatibles vers la base de données distante.
Cas d’utilisation	Vous disposez de requêtes SQL existantes écrites dans le dialecte de la base de données distante que vous souhaitez exécuter sans modification. Vous devez utiliser des fonctions ou une syntaxe spécifiques à la base de données qui peuvent ne pas être disponibles dans Databricks SQL. Vous souhaitez accéder ad hoc aux données distantes sans créer de catalogues étrangers.	Vous souhaitez interroger des données externes à l’aide de la syntaxe SQL Databricks. Vous avez besoin d’un modèle d’accès aux données à long terme avec un accès régi via des catalogues étrangers du catalogue Unity. Vous souhaitez combiner des données de plusieurs sources dans une requête unique à l’aide d’une syntaxe cohérente. Vous souhaitez utiliser l’assistant Génie pour écrire des requêtes.
Contrôle d’accès	Les utilisateurs ont besoin de `USE CONNECTION` privilèges sur la connexion. L’autorisation peut être déléguée via des vues.	Les utilisateurs ont besoin de privilèges de niveau table sur des objets catalogue étrangers. Contrôle affiné.

Avant de commencer

Conditions requises pour l’espace de travail :

Espace de travail activé pour Unity Catalog.

Voici les exigences de calcul à respecter :

Connectivité réseau de votre cluster Databricks Runtime ou de votre entrepôt SQL aux systèmes de base de données cibles. Consultez l’article Recommandations de mise en réseau pour Lakehouse Federation.
Les clusters Azure Databricks doivent utiliser Databricks Runtime 17.3 ou version ultérieure.
Les entrepôts SQL doivent être Pro ou Serverless et utiliser la version 2025.35 ou ultérieure.

Autorisations requises :

Pour créer une connexion, vous devez disposer du privilège CREATE CONNECTION sur le metastore du catalogue Unity.
Pour utiliser la remote_query fonction, vous devez disposer du USE CONNECTION privilège sur la connexion ou du SELECT privilège sur une vue qui englobe la fonction. Les clusters mono-utilisateurs nécessitent également l’autorisation MANAGE sur la connexion.

Créer une connexion

Pour utiliser la remote_query fonction, vous devez d’abord créer une connexion de catalogue Unity à votre base de données externe. Si vous disposez déjà d’une connexion créée pour la fédération de requêtes, vous pouvez la réutiliser.

La remote_query fonction prend en charge les connexions aux types de connexion suivants :

Pour en savoir plus sur la gestion des connexions existantes, consultez Gérer les connexions pour Lakehouse Federation.

Accorder l’accès à la connexion

Pour utiliser la fonction remote_query, vous devez disposer du privilège USE CONNECTION sur la connexion (ou du privilège MANAGE sur les clusters mono-utilisateur).

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

Utiliser la fonction `remote_query`

La remote_query fonction exécute une requête sur la base de données distante et retourne les résultats sous forme de table que vous pouvez utiliser dans les requêtes Databricks SQL.

Syntaxe

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

Paramètres obligatoires

connection-name: nom de la connexion du catalogue Unity à utiliser.

Tous les autres paramètres requis varient selon le type de connexion. Pour plus d’informations, consultez les options spécifiques au connecteur .

Options spécifiques au connecteur

Les options disponibles varient selon le type de connexion. Les tableaux suivants décrivent les options de chaque connecteur.

MySQL, PostgreSQL, SQL Server, Redshift et Teradata

Paramètre	Obligatoire	Descriptif
`database`	Oui	Nom de la base de données sur le système distant.
`query`	Oui (ou `dbtable`)	Chaîne de requête SQL à exécuter sur la base de données distante. Impossible d’utiliser avec `dbtable`.
`dbtable`	Oui (ou `query`)	Nom de la table à interroger. Impossible d’utiliser avec `query`.
`fetchsize`	Non	Nombre de lignes à récupérer par aller-retour. Les valeurs plus volumineuses peuvent améliorer les performances, mais utiliser plus de mémoire. Valeur par défaut : 0 (utiliser le pilote par défaut).
`partitionColumn`	Non	Colonne avec des valeurs distribuées uniformément à utiliser pour la récupération de données parallèles. Doit être utilisé avec `lowerBound`, `upperBound`et `numPartitions`. Impossible d’utiliser l’option `query` .
`lowerBound`	Non	Valeur minimale de la colonne de partition. Doit être utilisé avec `partitionColumn`, `upperBound`et `numPartitions`.
`upperBound`	Non	Valeur maximale de la colonne de partition. Doit être utilisé avec `partitionColumn`, `lowerBound`et `numPartitions`.
`numPartitions`	Non	Nombre de connexions parallèles à utiliser pour extraire des données. Ne définissez pas cette valeur trop élevée (centaines). Doit être utilisé avec `partitionColumn`, `lowerBound`et `upperBound`.

Note

Lorsque vous utilisez des paramètres de partition, les quatre paramètres (partitionColumn, , , lowerBoundupperBound) doivent être spécifiés ensemble, et vous devez utiliser l’option numPartitions au lieu de dbtablequery.

Oracle

Paramètre	Obligatoire	Descriptif
`service_name`	Oui	Nom du service Oracle (utilisé au lieu de `database`).
`query`	Oui (ou `dbtable`)	Chaîne de requête SQL à exécuter sur la base de données distante. Impossible d’utiliser avec `dbtable`.
`dbtable`	Oui (ou `query`)	Nom de la table à interroger. Impossible d’utiliser avec `query`.
`fetchsize`	Non	Nombre de lignes à récupérer par aller-retour. Les valeurs plus volumineuses peuvent améliorer les performances, mais utiliser plus de mémoire. Valeur par défaut : 0 (utiliser le pilote par défaut).
`partitionColumn`	Non	Colonne avec des valeurs distribuées uniformément à utiliser pour la récupération de données parallèles. Doit être utilisé avec `lowerBound`, `upperBound`et `numPartitions`. Impossible d’utiliser l’option `query` .
`lowerBound`	Non	Valeur minimale de la colonne de partition. Doit être utilisé avec `partitionColumn`, `upperBound`et `numPartitions`.
`upperBound`	Non	Valeur maximale de la colonne de partition. Doit être utilisé avec `partitionColumn`, `lowerBound`et `numPartitions`.
`numPartitions`	Non	Nombre de connexions parallèles à utiliser pour extraire des données. Ne définissez pas cette valeur trop élevée (centaines). Doit être utilisé avec `partitionColumn`, `lowerBound`et `upperBound`.

Note

Snowflake

Paramètre	Obligatoire	Descriptif
`database`	Oui	Nom de la base de données dans Snowflake.
`query`	Oui (ou `dbtable`)	Chaîne de requête SQL à exécuter sur la base de données distante. Impossible d’utiliser avec `dbtable`.
`dbtable`	Oui (ou `query`)	Nom de table à interroger (nom à composant unique ou nom en plusieurs parties). Impossible d’utiliser avec `query`.
`schema`	Non	Nom du schéma dans Snowflake. Par défaut : `public`.
`query_timeout`	Non	Délai d’expiration de la requête en secondes. Valeur par défaut : 0 (sans délai d’expiration).
`partition_size_in_mb`	Non	Taille de partition attendue en mégaoctets pour la récupération de données parallèles. Valeur par défaut : 100 Mo.

BigQuery

Paramètre	Obligatoire	Descriptif
`query`	Oui (ou `dbtable`)	Chaîne de requête SQL à exécuter sur la base de données distante. Impossible d’utiliser avec `dbtable`.
`dbtable`	Oui (ou `query`)	Nom de la table à interroger. Impossible d’utiliser avec `query`.
`materializationDataset`	Oui si la matérialisation des résultats est nécessaire. La matérialisation est nécessaire si `query` est spécifié et si `dbtable` pointe vers une vue.	Nom du jeu de données BigQuery où les tables temporaires sont matérialisées. La durée de vie par défaut des tables temporaires est de 24 heures.
`materializationProject`	Non	ID de projet BigQuery pour la matérialisation. Valeur par défaut du projet spécifié dans la connexion.
`materializationEnabled`	Non	Indique s'il faut activer la matérialisation des requêtes. Définissez à `true` pour interroger les vues. Valeur par défaut : `false` si `dbtable` elle est spécifiée, `true` si `query` elle est spécifiée.
`parentProject`	Non	ID du projet parent pour la facturation.

Important

Tous les paramètres de BigQuery sont sensibles à la casse.

Options de contrôle pushdown supplémentaires

Vous pouvez combiner la remote_query fonction avec les opérations Databricks SQL, et la plupart de ces opérations peuvent également être poussées vers le bas. Vous pouvez également contrôler les opérations Databricks SQL qui peuvent être poussées vers le bas. Ces options s’appliquent à tous les types de connexion et sont insensibles à la casse.

Paramètre	Par défaut	Descriptif
`pushdown.limit.enabled`	`true`	Activez ou désactivez les clauses push vers `LIMIT` la base de données distante.
`pushdown.offset.enabled`	`true`	Activez ou désactivez les clauses push vers `OFFSET` la base de données distante.
`pushdown.filters.enabled`	`true`	Activez ou désactivez l’envoi de `WHERE` filtres vers la base de données distante.
`pushdown.aggregates.enabled`	`true`	Activez ou désactivez l’envoi de fonctions d’agrégation (`COUNT`, , `SUMAVG`, `MAX`, `MIN`) à la base de données distante.
`pushdown.sortLimit.enabled`	`true`	Activez ou désactivez l’application de requêtes top-N (combinaison de `ORDER BY` et `LIMIT`) vers la base de données distante.

Par défaut, tous les abaissements sont activés. Vous pouvez désactiver des pushdowns spécifiques si nécessaire pour la résolution des problèmes ou pour contourner les problèmes de compatibilité avec des bases de données distantes spécifiques.

Déléguer l’accès par le biais des vues

Vous pouvez déléguer l’accès aux données distantes sans accorder aux utilisateurs des privilèges directs USE CONNECTION en encapsulant la remote_query fonction dans une vue. Cette approche offre les avantages suivants :

Contrôle d’accès simplifié : accordez SELECT des privilèges sur la vue au lieu de gérer les USE CONNECTION privilèges.
Sécurité des données : contrôlez les colonnes et lignes auxquelles les utilisateurs peuvent accéder en définissant la requête d’affichage.
Suivre le lignage : Suivez l'accès aux données via le lignage d'affichage plutôt que l'utilisation directe de la connexion.

Pour déléguer l’accès via une vue :

Créez une vue qui appelle la remote_query fonction :

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

Accordez SELECT des privilèges sur la vue aux utilisateurs ou aux groupes :
```
GRANT SELECT ON VIEW sales_data_view TO <user-or-group>;
```
Les utilisateurs peuvent désormais interroger la vue sans avoir besoin du USE CONNECTION privilège :
```
SELECT * FROM sales_data_view WHERE region = 'US';
```

Important

Le propriétaire de la vue doit avoir un privilège USE CONNECTION sur la connexion. Lorsque les utilisateurs interrogent la vue, la vérification de l’accès aux connexions est effectuée à l’aide des privilèges du propriétaire de la vue, et non des privilèges de l’utilisateur interrogeant.

Examples

Exécution de requête de base

Exécutez une requête sur une base de données PostgreSQL :

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

Interroger une table spécifique

Interrogez une table MySQL directement :

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

Oracle avec le nom du service

Interroger une base de données Oracle :

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

Requête BigQuery

Interroger 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)'
);

Requête Snowflake

Interroger Snowflake :

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

Optimisation des performances avec le partitionnement

Récupérez des données en parallèle à partir d’une table SQL Server :

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

Combinez avec les opérations de Databricks SQL

Appliquez des filtres et transformations supplémentaires :

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;

Créer un affichage pour l’accès délégué

Créez une vue qui encapsule la remote_query fonction. Les utilisateurs disposant SELECT de privilèges sur la vue peuvent interroger les données sans avoir besoin de USE CONNECTION privilèges sur la connexion sous-jacente :

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

Contrôler le comportement de filtrage (pushdown)

Lorsque vous utilisez la remote_query fonction, Databricks peut pousser des opérations supplémentaires vers la base de données distante au-delà de la requête que vous spécifiez. Cette fonctionnalité est utile lorsque vous interrogez une vue qui utilise la remote_query fonction.

Les opérations suivantes peuvent être poussées vers le bas :

Filtres : WHERE clauses appliquées au résultat de la requête distante
Projections : sélection de colonnes (SELECT colonnes spécifiques)
Limit : LIMIT clauses pour restreindre le nombre de lignes retournées
Offset : OFFSET clauses pour ignorer les lignes
Agrégats : fonctions d’agrégation telles que COUNT, , SUMAVG, MAX,MIN
Top-N : Combinaison de ORDER BY et LIMIT pour les requêtes N les plus élevées/les plus basses

La prise en charge de la fonctionnalité de pushdown varie selon la source de données. Pour plus d’informations, consultez la documentation relative à votre type de connexion spécifique.

Désactivez des pushdowns spécifiques pour la résolution des problèmes ou la compatibilité :

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

Limites

Opérations en lecture seule : la remote_query fonction prend uniquement en charge les SELECT requêtes. Les opérations de modification des données (INSERT, , UPDATEDELETE, MERGE), les opérations DDL (CREATE, DROP, ALTER) et les procédures stockées ne sont pas prises en charge.
Validation de la requête : la requête que vous fournissez est exécutée directement sur la base de données distante. Databricks valide que la requête est en lecture seule en effectuant une inspection de schéma, mais la syntaxe et la validation sémantique sont effectuées par la base de données distante.

Résolution des problèmes

Erreurs d’autorisation

Si vous recevez une erreur d’autorisation, vérifiez que :

Vous disposez du USE CONNECTION privilège sur la connexion ou du SELECT privilège sur une vue qui englobe la fonction.
Les identifiants de la connexion disposent des autorisations appropriées sur la base de données distante.

Exemple d’erreur :

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

Résolution :

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

Paramètres non pris en charge

Si vous recevez une erreur concernant les paramètres non pris en charge, vérifiez que vous utilisez les paramètres appropriés pour votre type de connexion. Le message d’erreur répertorie les paramètres autorisés.

Exemple d’erreur :

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

Résolution : supprimez le paramètre non pris en charge et utilisez les paramètres appropriés pour votre type de connexion.

Opérations DML non prises en charge

La remote_query fonction prend uniquement en charge les requêtes en lecture seule SELECT .

Exemple d’erreur :

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

Résolution : supprimez les instructions INSERT, UPDATEDELETE ou DDL de votre requête. Utilisez uniquement des SELECT instructions.

Ressources supplémentaires

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2026-01-30

Partage via

Interroger des bases de données externes à l’aide de la remote_query fonction

remote_query en comparaison avec la fédération de requêtes

Avant de commencer

Créer une connexion

Accorder l’accès à la connexion

Utiliser la fonction remote_query

Syntaxe

Paramètres obligatoires

Options spécifiques au connecteur

MySQL, PostgreSQL, SQL Server, Redshift et Teradata

Oracle

Snowflake

BigQuery

Options de contrôle pushdown supplémentaires

Déléguer l’accès par le biais des vues

Examples

Exécution de requête de base

Interroger une table spécifique

Oracle avec le nom du service

Requête BigQuery

Requête Snowflake

Optimisation des performances avec le partitionnement

Combinez avec les opérations de Databricks SQL

Créer un affichage pour l’accès délégué

Contrôler le comportement de filtrage (pushdown)

Limites

Résolution des problèmes

Erreurs d’autorisation

Paramètres non pris en charge

Opérations DML non prises en charge

Ressources supplémentaires

Commentaires

Ressources supplémentaires

Interroger des bases de données externes à l’aide de la `remote_query` fonction

`remote_query` en comparaison avec la fédération de requêtes

Utiliser la fonction `remote_query`