Connecteur Databricks

Cet article explique comment utiliser le connecteur Databricks pour DataGalaxy.

Ce connecteur est disponible dans les modes suivants :

Ce connecteur supporte les modes d'import suivants :

⚠ Un changement récent de l'API REST Databricks impacte la version actuelle du connecteur concernant le lineage autour des notebooks. Certains liens peuvent manquer lorsque les notebooks sont exécutés par un job (aka workflow).
Nous travaillons actuellement sur la prochaine version du connecteur qui utilise une approche différente et plus précise pour récupérer le lineage. Cette nouvelle version est actuellement en recette et sera bientôt livrée. Cette nouvelle approche ne sera disponible qu'en mode URN.

Périmètre, attributs et représentation dans DataGalaxy

Objets

Certains attributs listés ici pourraient ne pas être présents par défaut dans la configuration de vos écrans. Pour les ajouter, il peut être nécessaire d'ajuster la configuration des écrans des objets concernés avant de lancer le connecteur. Reportez-vous à l'article suivant pour en savoir plus sur la customisation d'écrans. 

Instance

Une Instance Databricks est représentée par une Base de Données Relationnelle dans le Dictionnaire et par un Data Flow dans le module Traitements. 

L'URN suit cette syntaxe :

urn:databricks-1:instance

Les attributs suivants sont récupérés dans la configuration du connecteur :

Catalogue

Un Catalogue est représenté par un Modèle.

L'URN suit cette syntaxe :

urn:databricks-1:instance:catalog

La liste des Catalogues est récupérée grâce à la connexion JDBC et la requête SHOW CATALOGS. Les attributs suivants sont récupérés grâce à la requête DESCRIBE CATALOG EXTENDED :

Note : les catalogues system et __databricks_internal sont filtrés implicitement.

Schéma

Un Schéma est représenté par un Modèle.

L'URN suit cette syntaxe :

urn:databricks-1:instance:catalog:schema

La liste des Schémas est récupérée grâce à la connexion JDBC et la requête SHOW SCHEMAS. Les attributs suivants sont récupérés grâce à la requête DESCRIBE SCHEMA EXTENDED :

Note : les schémas INFORMATION_SCHEMA sont filtrés implicitement.

Table (Managed ou External)

Une Table est représentée par une Table.

L'URN suit cette syntaxe :

urn:databricks-1:instance:catalog:schema:table

La liste des Tables est récupérée grâce à la connexion JDBC et la requête SHOW TABLES. Les attributs suivants sont récupérés grâce à la requête DESCRIBE TABLE EXTENDED (certains attributs peuvent ne pas être présents selon le type de Table) :

* Ces informations ne sont disponibles qu'en utilisant la méthode de récupération des métadonnées "DESC TABLE".

Vue (incluant Materialized View)

Une Vue est représentée par une Vue.

L'URN suit cette syntaxe :

urn:databricks-1:instance:catalog:schema:view@view

La liste des Vues est récupérée grâce à la connexion JDBC et la requête SHOW TABLES. Les attributs suivants sont récupérés grâce à la requête DESCRIBE TABLE EXTENDED (certains attributs peuvent ne pas être présents selon le type de Vue) :

* Ces informations ne sont disponibles qu'en utilisant la méthode de récupération des métadonnées "DESC TABLE".

Colonne

Une Colonne est représentée par une Colonne.

L'URN suit cette syntaxe :

urn:databricks-1:instance:catalog:schema:table:column

Les attributs suivants sont récupérés en même temps que les métadonnées de la Table :

Les attributs suivants sont calculés :

Répertoire du Workspace

Un Répertoire du Workspace est représenté par un Data Flow.

L'URN suit cette syntaxe :

urn:databricks-1:instance:Workspace@workspace:directory

Les attributs suivants sont récupérés grâce à l'API REST Databricks List contents (GET /api/2.0/workspace/list) :

Notebook

Un Notebook est représenté par un Data Processing.

L'URN suit cette syntaxe :

urn:databricks-1:instance:Workspace@workspace:directory:notebook@notebook

Les attributs suivants sont récupérés grâce à l'API REST Databricks List contents (GET /api/2.0/workspace/list) :

Workflow

Note: les Workflows ne sont supportés qu'en mode URN.

Un Workflow est représenté par un Data Processing.

L'URN suit cette syntaxe :

urn:databricks-1:instance:Workflows@workflows:workflowId

Les attributs suivants sont récupérés grâce à l'API REST Databricks List jobs (GET /api/2.2/jobs/list) et Get a single job (GET /api/2.2/jobs/get) :

Liens

Les liens créés par le connecteur Databricks sont des liens de lineage entre les structures du Dictionnaire et éventuellement les objets Data Processing du module Traîtements. La récupération du lineage est optionnelle, l'option "Récupérer le lineage" doit être activée dans la configuration du connecteur. Alors, le niveau de granularité à la table ou à la colonne peut être choisi*. La méthode de récupération du lineage peut être configurée également*, deux options sont possibles :

• La nouvelle option recommandée par Databricks est d'utiliser les System Tables. Cela peut nécessiter de la configuration de la part d'un administrateur du workspace Databricks pour les rendre utilisables. C'est cette option qui vous permettra d'obtenir le plus haut niveau de précision dans le lineage. Les vues system.access.table_lineage et system.table.column_lineage sont lues par le connecteur pour récupérer le lineage avec cette méthode.
• L'option historique est d'utiliser l'API REST Databricks (GET /api/2.0/lineage-tracking/table-lineage endpoint). Cette API est moins précise que les System Tables. Par exemple, il n'est pas possible d'avoir une correspondance précise entre les objets en entrée et en sortie d'un Notebook ou Workflow, ce qui est disponible avec la méthode System Tables.

Ces deux options ne sont disponibles qu'en mode URN.

Lors de la création des liens autour des Notebooks et Workflows, le comportement suivant est implémenté pour obtenir le lineage le plus complet et le plus précis dans DataGalaxy :

• Si l'option "Récupérer les Notebooks" est sélectionnée, les liens de lineage seront créés autour de tous les notebooks qui font partie du périmètre du connecteur. Si un Notebook ne fait pas partie du périmètre (filtré par le préfixe du chemin, ou faisant partie d'un autre workspace Databricks), alors les liens seront créés directement entre les structures du Dictionnaire.
• Si l'option "Récupérer les Workflows" est sélectionnée, les liens de lineage seront créés autour de tous les Workflows faisant partie du périmètre du connecteur. Si un Workflow ne fait pas partie du périmètre (appartenant à un autre workspace Databricks), alors les liens seront créés directement entre les structures du Dictionnaire.

Lorsqu'un objet Data Processing est impliqué dans le lineage, le connecteur Databricks tire partie des Data Processing Items, afin de fournir une correspondance précise entre les objets en entrée et en sortie. Le nom des objets Data Processing Items créés par le connecteur sont des noms techniques, construits selon les noms des objets en entrée et en sortie, ils ne représentent rien de réel et ne viennent pas de Databricks. Ces noms restent identiques dans le temps tant que les objets en entrée et en sortie ne changent pas.

Note : la Gestion des Objets Orphelins ne supporte pas encore les objets Data Processing Items. Cela signifie que si vous avez d'anciens Data Processing Items, ils ne seront pas nettoyés par le traitement de Gestion des Objets Orphelins. Cela est identifié par l'équipe qui est en train de travailler sur une évolution de cette fonctionnalité pour gérer ces objets.

Périmètre

* Ces objets ne sont disponibles qu'en activant le mode URN du connecteur.

Des attributs complémentaires sont également renseignés selon la technologie et par type d'objet. Pour les faire apparaître dans les écrans DataGalaxy, il peut être nécessaire d'adapter les écrans des objets concernés. Consultez cet article pour en savoir plus sur la personnalisation des écrans.

Périmètre détaillé

Entrée (module Dictionnaire)

• Catalog, schema, table et view

Depuis la page d'accueil de votre compte Databricks, ces éléments sont visibles dans la rubrique "Catalog" située à gauche.

• Column

En cliquant sur une table ou une vue donnée, vous aurez le détail des colonnes qui la composent.

Entrée (module Traitements)

• Folders

Depuis la page d'accueil de votre compte Databricks, les folders sont visibles dans la rubrique "Workspace" située à gauche. Seront remontés les dossiers contenus dans le dossier "Workspace". Les dossiers "User" et "Repos" seront ignorés lors de l'import.

• Notebooks

Les notebooks sont visibles en cliquant sur un dossier. Ils apparaîtrons alors dans la partie centrale de l'écran.

• Workflows (uniquement avec la version Unity Catalog de Databricks)

Depuis la page d'accueil de votre compte Databricks, les workflows sont visibles dans la rubrique "Jobs et Pipelines" située à gauche. 

En cliquant sur un job donné vous aurez les détails qui y sont associés, et notamment le linéage associé, avec les tables upstream et downstream (ce qui correspondra dans DataGalaxy à des liens avec des tables).

Vous retrouverez également cette information et ouvrant l'onglet "linéage" d'une table donnée de la rubrique "Catalog".

Sortie (module Dictionnaire)

• Catalog, schema, table, view et column

Sortie (module Traitements)

• Folders et Notebooks

Configuration de la connexion

    Côté Databricks

Le connecteur Databricks exploite le driver JDBC fourni par Databricks ainsi que l'API REST de Unity Catalog. La connexion à une instance Databricks nécessite donc un cluster pour exécuter les commandes SQL via le driver JDBC. Vous pouvez soit utiliser un cluster interactif soit un cluster SQL Warehouse. L'accès aux informations de connexion d'un cluster est disponible ici. Afin d'optimiser les temps de traitement, vous pouvez allumer le cluster en amont du lancement du connecteur.

Pour s'authentifier sur le cluster Databricks, trois modes sont disponibles :

L'authentification par jeton (token)

La procédure détaillée de génération d'un jeton est disponible ici. Le jeton est associé à un utilisateur qui doit avoir accès aux tables que vous souhaitez remonter par le connecteur (en clair, lorsque vous vous connectez avec le compte associé au token, si vous ne voyez pas ce que vous souhaitez remonter alors l'import avec ce token ne remontera pas non plus les objets manquants).

Pour générer un token suivez les étapes suivantes :

• Connectez-vous à l'aide du User auquel vous voulez associer le token
• Depuis la page d'accueil, cliquez sur l'icône utilisateur en haut à droite puis sur "Settings"
• Ouvrez le menu "Developer" puis cliquez sur le bouton "Manage" d'"Access tokens"
• Générez votre token en lui attribuant une description et une durée de vie
• Conservez le token généré, vous pouvez maintenant l'utiliser pour configurer votre connexion DataGalaxy

L'authentification par Service Principal Entra ID (Azure AD)

Afin d'utiliser les service principals sur Azure Databricks, un utilisateur Admin doit d'abord créer une nouvelle application Microsoft Entra ID (anciennement Azure AD) en suivant les étapes suivantes :

• Accédez au portail Azure (par exemple en cliquant sur l'icône utilisateur depuis votre compte Databricks puis sur "Azure Portal")
• Une fois sur le portail Azure, dans la barre de recherche trouvez et cliquez sur "Microsoft Entra ID"
• Cliquez ensuite sur "+ Add" puis "App registration"
• Rentrez les informations nécessaires, sans oublier de choisir pour la section "Supported account types" l'option "Accounts in this organizational directory only (Single tenant)"
• Une fois l'application créée, n'oubliez pas de copier/coller l'"Application (client) ID" et le "Directory (tenant) ID" avant de cliquer à gauche sur "Certificates and secrets"
• Dans "Certificates and secrets", générez un secret grâce à "+ New client secret". Dans la fenêtre de droite rentrez une description et une date d'expiration avant de cliquer sur "Add"
• Conservez le secret généré, vous pouvez maintenant l'utiliser pour configurer votre connexion DataGalaxy

Une fois l'application créée dans Microsoft Entra ID, il va falloir la lier à votre compte Databricks en suivant les opérations suivantes :

• Depuis la page d'accueil, cliquez sur l'icône utilisateur en haut à droite puis sur "Settings"
• Ouvrez le menu "Identité et accès" puis cliquez sur le bouton "Manage" de "Service Principals"
• Vous aurez ensuite la possibilité de créer un service principal avec le bouton "Add service principal"
• Il vous suffira alors de copier le Microsoft Entra Application ID" pour associer votre Application Azure au compte Azure Databricks

L'authentification par Service Principal Databricks

Un Service Principal est une identité spécialisée utilisée pour les accès automatiques et les opérations programmées. Vous pouvez gérer les accès d'un Service Principal Databricks de la même manière que vous gérez ceux d'un utilisateur. Pour le créer suivez les étapes suivantes :

• Depuis la page d'accueil, cliquez sur l'icône utilisateur en haut à droite puis sur "Settings"
• Ouvrez le menu "Identité et accès" puis cliquez sur le bouton "Manage" de "Service Principals"
• Vous aurez ensuite la possibilité de créer un service principal avec le bouton "Add service principal"
• Une fois le service principal créé, cliquer dessus pour accéder à ses détails, et notamment à l'onglet "Secrets" où vous trouverez le bouton "Generate secret". Comme avec le token il vous sera proposé de rentrer une durée de vie à ce secret
• Conservez le secret généré, vous pouvez maintenant l'utiliser pour configurer votre connexion DataGalaxy

Détail des droits nécessaires à l'obtention des métadonnées

Nous allons maintenant détailler les autorisations associées aux différents types de métadonnées, divisées en catégories

• Catalogue, Schéma, Table/Vue

Pour octroyer les droits nécessaire à votre Service Principal Databricks/Azure, la manipulation sera la même:

1. Sélectionnez à gauche "Catalog"
2. Sélectionnez la source à laquelle vous souhaitez donner accès
3. Aller dans l'onglet "Permissions" et cliquez sur "Grant"
4. Dans la fenêtre qui s'ouvre ajouter votre Service Principal puis cocher les droits USE CATALOG, USE SCHEMA et SELECT avant de valider (si vous utilisez le mode de récupération des métadonnées "INFORMATION_SCHEMA", remplacez SELECT par BROWSE)

   Si vous souhaitez gagner en précision vous pouvez attribuer les autorisations USE SCHEMA et SELECT au niveau des schémas et des tables

• Folder, Notebook (Fonctionnalité - Récupérer les Notebooks)

Pour octroyer les droits nécessaire à votre Service Principal Databricks/Azure, la manipulation sera la même :

1. Sélectionnez à gauche "Workspace"
2. Sélectionnez le dossier "Workspace" auquel vous souhaitez donner accès
3. Cliquez sur le bouton "Share"
4. Dans la fenêtre qui s'ouvre indiquez le nom de votre Service Principal et donnez-lui le droit "Can View"

• Workflow (Fonctionnalité - Récupérer les Workflows) 

Pour octroyer les droits nécessaire à votre Service Principal Databricks/Azure, la manipulation sera la même :

1. Sélectionnez à gauche "Jobs & Pipelines"
2. Sélectionnez l'élément auquel vous souhaitez donner accès
3. Dans la fenêtre de droite descendez jusqu'à "Permissions" et cliquez sur "Edit permissions"
4. Dans la fenêtre qui s'ouvre indiquez le nom de votre Service Principal et donnez-lui le droit "Can View"

• Linéage Unity (Fonctionnalité - Récupérer le lineage depuis Unity)

Quand la fonctionnalité "Récupérer le lineage depuis Unity" est activé, avoir les autorisations ci-dessus sur les tables, notebooks et workflows concernés par le linéage suffit pour remonter toutes les informations de linéage qui les relient 

• Ressource de calcul

Pour donner à votre Service Principal Databricks/Azure le droit d'utiliser la ressource de calcul nécessaire à l'import vers DataGalaxy, voici les étapes à suivre :

1. Sélectionnez à gauche "SQL Warehouses"
2. Sélectionnez la ressource que vous souhaitez utiliser pour votre import ou créez-là
3. Cliquez à droite sur "Permissions"
4. Dans la fenêtre qui s'ouvre choisissez votre Service Principal et donnez lui le droit "Can Use"
5. Enfin dans l'onglet "Connexion details" vous trouverez tout ce dont vous avez besoin pour paramétrer la connexion côté DataGalaxy, à savoir le "Server hostname" et le "HTTP path"

Pour plus de précisions concernant les droits des clusters, veuillez consulter le tableau suivant. La gestion des permissions dans Databricks est disponible ici.

    Côté DataGalaxy

Les informations suivantes sont demandées pour configurer une connexion:

⚠ La récupération du lineage peut significativement augmenter la durée d'exécution du connecteur et par conséquent les coûts associés au cluster de calcul utilisé.

* Uniquement en mode URN

Du mode standard au mode URN

Différences

1. En mode Standard le nom de votre objet racine sera celui que vous lui donnerez lorsque vous créez la connexion (ou de l'objet racine du module Dictionnaire que vous ciblerez). En mode URN le nom de l'objet racine sera le nom de serveur Databricks.
   • Mode Standard
   • Mode URN
2. En mode Standard, dans le module "Traitements", vos objets projets "Flux" et "Traitement" seront regroupés directement sous votre objet racine. En mode URN ces mêmes objets seront regroupés un niveau plus bas dans la hiérarchie, sous un objet nommé "Workspace". Un objet supplémentaire nommé "Workflows" fera également son apparition au même niveau que l'objet "Workspace"
   • Mode Standard
   • Mode URN

Guide de migration

Ce guide a pour but de vous indiquer les étapes à suivre pour passer votre objet racine et tous les objets Databricks qu'il contient du mode Standard au mode URN. Une fois ces étapes effectuées, vous serez en mesure de réaliser tous vos futurs imports en mode URN et de profiter des nouvelles fonctionnalités associées à ce mode. 

1. Descendre d'un niveau les objets contenus dans votre objet racine Databricks du module "Traitements"
   • Ouvrir le menu associé à votre objet racine (”Databricks” ici) et choisir l’option “+ Créer un enfant”. Il sera de type “Flux” et vous le nommerez "Workspace"
   • Une fois cela fait il vous faudra déplacer chacun de vos autres objets (”Shared” et "Test" ici) en ouvrant leurs menus associés et en choisissant l’option “Déplacer”. Vous ciblerez l’objet créé juste avant, “Workspace” 
   • Si vous ne réalisez pas cette opération, lors de l'import en mode URN final sur votre objet racine vous créerez des doublons de tous les objets remontés depuis Databricks
2. Si ce n'est pas encore le cas, associer aux sources “Database” du module "Dictionnaire" l'attribut "URN". Faites de même pour les objets "Flux" du module "Traitement"
3. Associer à vos objets racine des modules "Dictionnaire" et "Traitement" l'URN correspondant
   • A ce propos nous conseillons de suivre les étapes suivantes pour éviter toute erreur:
     • Réaliser un import en mode URN, lequel va créer un nouvel objet racine dans chaque module pour lequel l'attribut URN sera renseigné
     • Copier lesdits attributs URN
     • Supprimer les objets racine que vous venez d'importer en mode URN ainsi que tous leurs enfants (vu qu'un URN doit être unique, si vous ne supprimez pas cet objet racine avant d'assigner son URN à un autre objet la plateforme retournera une erreur)
     • Coller les URNs pour renseigner les attribut URN de vos objets racine qui sont encore en mode Standard dans chacun des modules
4. Réaliser un nouvel import en mode URN
   • Cette fois-ci tous les attributs URN des enfants sous vos objets racine des deux modules devraient être renseignés

Félicitations, vous avez migré du mode Standard au mode URN et êtes en mesure de profiter de toutes les nouvelles fonctionnalités offertes par celui-ci !

Exécution du connecteur

Etape 1: Installation

• Télécharger le connecteur DataGalaxy depuis le portail (voir ici)
• Extraire l'archive du connecteur dans le répertoire de votre choix
• Télécharger le plug-in Databricks depuis le portail et le copier dans le répertoire /lib du connecteur

Etape 2: Exécution du connecteur

• Après avoir démarré le connecteur, accéder aux connecteurs du Dictionnaire ou des Traitements

• S'il a été correctement installé, le plug-in Databricks apparaît dans la liste

• Complétez les champs correspondants à l'aide des informations de connexion données ci-dessus

Jeton Databricks:

Service Principal Azure AD:

Service Principal Databricks:

• Cliquez sur "Test" pour tester la connexion
• Une fois le test de connexion passé vous pouvez suivre les étapes pour finaliser votre import.
  

Ce connecteur est également disponible en mode online, pour plus de précisions consulter cette page: 

[HowTo] Exécution du Connecteur Online.

Releases