Exécuter des requêtes fédérées sur Oracle

Cette page décrit comment configurer Lakehouse Federation pour exécuter des query fédérées sur des données Oracle qui ne sont pas gérées par Databricks. Pour en savoir plus sur Lakehouse Federation, consultez Connecter aux bases de données et catalogues externes

Pour vous connecter à votre base de données Oracle à l'aide de Lakehouse Federation, vous devez créer les éléments suivants dans votre métastore Databricks Unity Catalog (les workspaces créés après le 6 mars 2024 disposent déjà d'un métastore Unity Catalog provisionné automatiquement) :

• Une connexion à votre base de données Oracle.
• Un catalogue étranger qui reflète votre base de données Oracle dans Unity Catalog afin que vous puissiez utiliser la syntaxe de query Unity Catalog et les outils de gouvernance des données pour gérer l’accès des utilisateurs Databricks à la base de données.

Avant de commencer

Avant de commencer, confirmez que vous remplissez les exigences de cette section.

Exigences Databricks

Exigences du Workspace :

• Workspace activé pour Unity Catalog. Les workspaces créés après le 6 mars 2024 sont automatiquement activés pour Unity Catalog, y compris le provisionnement automatique du métastore. Vous n'avez pas besoin de créer manuellement un métastore, à moins que votre workspace ne soit antérieur à l'activation automatique et n'ait pas été activé pour Unity Catalog. Voir Se familiariser avec Unity Catalog.

Compute requis :

• Connectivité réseau de votre ressource de compute vers les systèmes de bases de données cibles. Consultez les recommandations de mise en réseau pour Lakehouse Federation.
• Le compute Databricks doit utiliser Databricks Runtime 16.1 ou une version ultérieure et le mode d'accès Standard ou Dédié .
• Les SQL Warehouse doivent être pro ou Serverless et utiliser la version 2024.50 ou ultérieure.

Autorisations requises :

• Pour créer une connexion, vous devez être administrateur de métastore ou un utilisateur disposant du privilège CREATE CONNECTION sur le métastore Unity Catalog attaché à l'espace de travail. Dans les espaces de travail qui ont été activés automatiquement pour Unity Catalog, les administrateurs d'espace de travail disposent du privilège CREATE CONNECTION par default.
• Pour créer un catalogue externe, vous devez disposer de l'autorisation CREATE CATALOG sur le metastore et être le propriétaire de la connexion ou disposer du privilège CREATE FOREIGN CATALOG sur la connexion. Dans les workspaces activés automatiquement pour Unity Catalog, les administrateurs du workspace disposent du privilège CREATE CATALOG par default.

Des exigences d'autorisation supplémentaires sont spécifiées dans chaque section basée sur les tâches qui suit.

Exigences Oracle

Pour les connexions qui utilisent le chiffrement réseau natif (NNE), vous devez activer le NNE côté serveur (niveau ACCEPTED au minimum). Consultez la section Configuring Network Data Encryption dans la documentation d’Oracle. Cela ne s’applique pas aux connexions qui utilisent TLS.

Créer une connexion Databricks

Une connexion spécifie un chemin d'accès et des identifiants pour accéder à un système de base de données externe. Pour créer une connexion, vous pouvez utiliser Catalog Explorer ou la commande SQL CREATE CONNECTION dans un Notebook Databricks ou l'éditeur de query Databricks SQL.

remarque

Vous pouvez également utiliser l'API REST Databricks ou la CLI Databricks pour créer une connexion. Voir POST /api/2.1/unity-catalog/connections et les commandes Unity Catalog.

Autorisations requises : administrateur du Metastore ou utilisateur disposant du privilège CREATE CONNECTION.

Catalog Explorer

1. Dans le Workspace Databricks, cliquez sur Catalogue .

2. Cliquez sur Connexion , puis cliquez sur Connexions .

3. Veuillez cliquer sur le bouton Créer une connexion .

4. Sur la page **Principes de base de la connexion** de l’assistant **Configurer la connexion**, saisissez un **Nom de connexion** convivial.

5. Sélectionnez un type de connexion Oracle .

6. Ajouter un commentaire (facultatif).

7. Cliquez sur Suivant .

8. Sur la page **Authentification**, saisissez les informations suivantes pour l'instance Oracle :

   • Hôte : Par exemple, oracle-demo.123456.rds.amazonaws.com
   • Port : par exemple, 1521
   • Utilisateur : Par exemple, oracle_user
   • Mot de passe : Par exemple, password123
   • Protocole de chiffrement : Native Network Encryption (default) ou Transport Layer Security
   • Certificat de serveur fourni par l’utilisateur : facultatif. Le certificat public encodé au format PEM de votre instance Oracle, utilisé pour vérifier l’identité du serveur lors du handshake TLS. Fournissez-le lorsque votre serveur présente un certificat provenant d’une autorité de certification privée ou interne qui ne se trouve pas dans le magasin de confiance default. Un certificat de serveur fourni par l’utilisateur requiert un protocole de chiffrement de Transport Layer Security. La vérification du hostname est effectuée dans le cadre du handshake TLS. La connexion échoue si le hostname figurant sur le certificat ne correspond pas au hostname demandé.
   • Timezone as region : facultatif. Activé par default. Permet de déterminer si la connexion indique son fuseau horaire de session à Oracle en tant que région nommée (activé) ou en tant que décalage UTC fixe (désactivé). Désactivez-la uniquement pour contourner l’erreur timezone region not found. Consultez ORA-01882 : timezone region not found.

9. Cliquez sur Créer une connexion .

10. Sur la page **Bases du catalogue**, veuillez saisir un nom pour le catalogue étranger. Un catalogue étranger reflète une base de données dans un système de données externe afin que vous puissiez query et gérer l'accès aux données de cette base de données à l'aide de Databricks et de Unity Catalog.

11. (Facultatif) Cliquez sur **Tester la connexion** pour confirmer que cela fonctionne.

12. Cliquez sur **Créer un catalogue**.

13. Sur la page Accès , sélectionnez les workspaces dans lesquels les utilisateurs peuvent accéder au catalogue que vous avez créé. Vous pouvez sélectionner Tous les workspaces ont accès , ou cliquer sur Attribuer aux workspaces , sélectionner les workspaces, puis cliquer sur Attribuer .

14. Modifiez le propriétaire qui pourra gérer l'accès à tous les objets du catalogue. start à taper un principal dans la zone de texte, puis cliquez sur le principal dans les résultats renvoyés.

15. Accordez les **Privilèges** sur le catalogue. Cliquez sur Accorder :

    1. Spécifiez les **principals** qui auront accès aux objets dans le catalogue. start à taper un principal dans la zone de texte, puis cliquez sur le principal dans les résultats renvoyés.

    2. Sélectionnez les **Préréglages de privilèges** à accorder à chaque principal. Tous les utilisateurs du compte se voient accorder BROWSE par default.

       • Sélectionnez Data Reader dans le menu déroulant pour accorder read privilèges sur les objets du catalogue.
       • Sélectionnez **Data Editor** dans le menu déroulant pour accorder read les modify privilèges et sur les objets du catalogue.
       • Sélectionnez manuellement les privilèges à accorder.

    3. Cliquez sur Accorder .

16. Cliquez sur Suivant .

17. Sur la page Métadonnées , spécifiez les paires clé-valeur de balises. Pour plus d'informations, consultez Appliquer des balises aux objets sécurisables d'Unity Catalog.

18. Ajouter un commentaire (facultatif).

19. Cliquez sur Enregistrer .

SQL

Exécutez la commande suivante dans un Notebook ou l’éditeur de query Databricks SQL :

SQL

CREATE CONNECTION <connection-name> TYPE oracle
OPTIONS (
  host '<hostname>',
  port '<port>',
  user '<user>',
  password '<password>',
  encryption_protocol '<protocol>', -- optional
  timezone_as_region '<true-or-false>' -- optional
);

timezone_as_region contrôle si la connexion indique son fuseau horaire de session à Oracle sous forme de région nommée telle que America/Los_Angeles (true, la valeur par default) ou sous forme de décalage UTC fixe tel que -08:00 (false). Définissez-le sur false uniquement pour contourner timezone region not found l'erreur. Voir ORA-01882 : région de fuseau horaire introuvable.

Databricks vous recommande d'utiliser les secrets Databricks au lieu de chaînes de texte brut pour les valeurs sensibles comme les identifiants. Par exemple :

SQL

CREATE CONNECTION <connection-name> TYPE oracle
OPTIONS (
  host '<hostname>',
  port '<port>',
  user secret ('<secret-scope>','<secret-key-user>'),
  password secret ('<secret-scope>','<secret-key-password>'),
  encryption_protocol '<protocol>' -- optional
)

Pour vérifier l’identité du serveur lors de la liaison TLS (par exemple, lorsque votre serveur Oracle présente un certificat provenant d’une autorité de certification privée ou interne qui ne se trouve pas dans le magasin de confiance default), transmettez le certificat encodé en PEM du serveur dans l’option userProvidedServerCertificate. Un certificat de serveur fourni par l’utilisateur exige que encryption_protocol soit défini sur TLS.

SQL

CREATE CONNECTION <connection-name> TYPE oracle
OPTIONS (
  host '<hostname>',
  port '<port>',
  user secret ('<secret-scope>','<secret-key-user>'),
  password secret ('<secret-scope>','<secret-key-password>'),
  encryption_protocol 'TLS',
  userProvidedServerCertificate '<pem-encoded-certificate>'
)

Si vous devez utiliser des chaînes de texte brut dans les commandes SQL du notebook, évitez de tronquer la chaîne en échappant les caractères spéciaux comme $ avec \. Par exemple : \$.

Pour en savoir plus sur la configuration des secrets, consultez la gestion des secrets.

Créer un catalogue étranger

remarque

Si vous utilisez l’interface utilisateur pour créer une connexion à la source de données, la création du catalogue externe est incluse et vous pouvez ignorer cette étape.

Un catalogue étranger reflète une base de données dans un système de données externe afin que vous puissiez query et gérer l'accès aux données dans cette base de données à l'aide de Databricks et d'Unity Catalog. Pour créer un catalogue étranger, vous utilisez une connexion à la source de données qui a déjà été définie.

Pour créer un catalogue externe, vous pouvez utiliser l'Explorateur de catalogues ou la commande SQL CREATE FOREIGN CATALOG dans un Notebook Databricks ou l'éditeur de query SQL. Vous pouvez également utiliser l'API REST Databricks ou la CLI Databricks pour créer un catalogue. Voir POST /api/2.1/unity-catalog/catalogs et commandes Unity Catalog.

Autorisations requises : autorisation CREATE CATALOG sur le metastore et soit la propriété de la connexion, soit le privilège CREATE FOREIGN CATALOG sur la connexion.

Catalog Explorer

1. Dans le Workspace Databricks, cliquez sur Catalogue pour ouvrir l'Explorateur de catalogues.

2. En haut du volet Catalogue , cliquez sur l'icône Ajouter et sélectionnez Ajouter un catalogue dans le menu.

   Autrement, depuis la page Quick access , cliquez sur le bouton Catalogs , puis cliquez sur le bouton Create catalog .

3. Suivez les instructions pour créer des catalogues étrangers dans Créer des catalogues.

SQL

Exécutez la commande SQL suivante dans un notebook ou un éditeur de requêtes SQL. Les éléments entre crochets sont facultatifs. Remplacez les valeurs des espaces réservés :

• <catalog-name>: Nom du catalogue dans Databricks.
• <connection-name>: L'objet de connexion qui spécifie la source de données, le chemin d'accès et les informations d'identification d'accès.
• <service-name>: Nom du service que vous souhaitez mettre en miroir en tant que catalogue dans Databricks.

SQL

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS (service_name '<service-name>');

Pushdowns pris en charge

Le tableau suivant répertorie les opérations pushdown prises en charge pour Oracle, ainsi que le compute requis pour chacune d’elles.

Pushdown	Compute pris en charge
Agrégats	All compute
Opérateurs arithmétiques (comme +, -, *, %, /) — non pris en charge si ANSI est désactivé	All compute
Opérateurs booléens (tels que =, <=>, <, <=, >, >=)	All compute
Contient, Commence par, Se termine par	All compute
Filtres	All compute
Limite	All compute
Fonctions mathématiques (ABS, FLOOR — prise en charge partielle, expressions de filtre uniquement)	All compute
Fonctions diverses (tels que Alias, Cast, SortOrder — prise en charge partielle, expressions de filtre uniquement)	All compute
Décalage	All compute
Projections	All compute
Tri, lorsqu'il est utilisé avec une limite	All compute
Fonctions de chaîne (UPPER, LOWER, CHAR_LENGTH, TRIM, RTRIM, LTRIM, CONCAT, RPAD, LPAD — prise en charge partielle, expressions de filtre uniquement)	All compute
Jointures	Databricks Runtime 17.2 et versions ultérieures et SQL Warehouse compute. Ce pushdown est en Préversion publique; activez l'option **Pushdown de jointure pour les requêtes fédérées** sur la page **Préversions**.
Fonctions de fenêtre	Non pris en charge

Pushdown	Compute pris en charge
Agrégats	All compute
Opérateurs arithmétiques (comme +, -, *, %, /) — non pris en charge si ANSI est désactivé	All compute
Opérateurs booléens (tels que =, <=>, <, <=, >, >=)	All compute
Contient, Commence par, Se termine par	All compute
Filtres	All compute
Limite	All compute
Fonctions mathématiques (ABS, FLOOR — prise en charge partielle, expressions de filtre uniquement)	All compute
Fonctions diverses (tels que Alias, Cast, SortOrder — prise en charge partielle, expressions de filtre uniquement)	All compute
Décalage	All compute
Projections	All compute
Tri, lorsqu'il est utilisé avec une limite	All compute
Fonctions de chaîne (UPPER, LOWER, CHAR_LENGTH, TRIM, RTRIM, LTRIM, CONCAT, RPAD, LPAD — prise en charge partielle, expressions de filtre uniquement)	All compute
Jointures	Databricks Runtime 17.2 et versions ultérieures et SQL Warehouse compute. Ce pushdown est en Préversion publique; activez l'option **Pushdown de jointure pour les requêtes fédérées** sur la page **Préversions**.
Fonctions de fenêtre	Non pris en charge

Mappages des types de données

Lorsque vous lisez d'Oracle vers Spark, les types de données correspondent comme suit :

Type Oracle	Type Spark
TIMESTAMP WITH TIMEZONE, TIMESTAMP WITH LOCAL TIMEZONE	TimestampType
DATE, TIMESTAMP	TimestampType/TimestampNTZType*
NUMBER, FLOAT	DecimalType**
BINARY FLOAT	FloatType
BINARY DOUBLE	DoubleType
CHAR, NCHAR, VARCHAR2, NVARCHAR2	StringType

Type Oracle	Type Spark
TIMESTAMP WITH TIMEZONE, TIMESTAMP WITH LOCAL TIMEZONE	TimestampType
DATE, TIMESTAMP	TimestampType/TimestampNTZType*
NUMBER, FLOAT	DecimalType**
BINARY FLOAT	FloatType
BINARY DOUBLE	DoubleType
CHAR, NCHAR, VARCHAR2, NVARCHAR2	StringType

* DATE et TIMESTAMP sont mappés à Spark TimestampType si spark.sql.timestampType = TIMESTAMP_LTZ (default). Ils sont mappés à TimestampNTZType si spark.sql.timestampType = TIMESTAMP_NTZ.

** NUMBER sans spécifier de précision sera mappé à DecimalType(38, 10) car il n'y a pas de support pour un Decimal en virgule flottante pure dans Spark.

Dépannage

ORA-01882 : région de fuseau horaire introuvable

Lorsque vous vous connectez à des instances Oracle 11.2.0.3.0 et ultérieures qui ne disposent pas d’une valeur de fuseau horaire de Etc/UTC, la connexion peut échouer avec l’erreur ORA-01882: timezone region not found. Cela se produit lorsque le serveur Oracle ne reconnaît pas la région de fuseau horaire nommée signalée par la connexion lors de l’authentification.

Pour résoudre cette erreur, Databricks recommande de procéder comme suit, dans l'ordre :

1. Mettez à jour les fichiers de fuseau horaire sur le serveur Oracle afin qu’il reconnaisse le nom de la région. Il s’agit de la solution définitive recommandée. Consultez la documentation du support Oracle - ORA-01882.
2. Si vous ne pouvez pas mettre à jour le serveur Oracle, définissez l'option de connexion timezone_as_region sur false. La connexion indique ensuite un décalage UTC fixe au lieu d'un nom de région, ce qui évite l'erreur. Un décalage fixe ne suit pas les changements d'heure saisonniers, de sorte que les valeurs TIMESTAMP WITH LOCAL TIME ZONE ne sont pas ajustées pour l'heure d'été.

Licence

Le driver Oracle et les autres fichiers JAR Oracle nécessaires sont régis par la licence FDHUT sans clic.

Ressources supplémentaires

• Remontée de jointure dans la Lakehouse Federation
• Recommandations de mise en réseau pour Lakehouse Federation
• Interrogez les bases de données externes à l'aide de la fonction remote_query