Importer des métadonnées depuis Snowflake Horizon

Éliminez les silos de données et évitez de passer d'un outil à l'autre en utilisant un connecteur Knowledge Catalog (anciennement Dataplex Universal Catalog) pour importer des métadonnées de Snowflake Horizon directement dans Google Cloud.

Ce connecteur est compatible avec les instances Snowflake Horizon hébergées surGoogle Cloud, Microsoft Azure ou Amazon Web Services (AWS).

Le tableau suivant liste les métadonnées capturées par le connecteur Snowflake Horizon :

Catégorie Métadonnées capturées
Technique
  • Métastore (compte Snowflake)
  • Catalogue (base de données)
  • Schéma
  • Table (y compris les tables temporaires, externes, dynamiques, interactives, hybrides et Apache Iceberg) et colonnes
  • Vue (standard, matérialisée et sécurisée)
  • Stages (internes et externes), importés en tant qu'ensembles de fichiers
  • Fonctions définies par l'utilisateur (UDF) et procédures stockées
Opérations
  • Métriques d'utilisation (vues, lectures et écritures sur 30 et 90 jours ; utilisateurs fréquents et tables fréquemment jointes sur 30 jours)
  • Clés primaires et clés étrangères
Entreprise
  • Tags (tags d'objet, de colonne et de membre de vue sémantique)
  • Qualité des données (attentes des fonctions de métriques de données, détection d'anomalies et résultats de la surveillance automatique de la qualité des données)
  • Profilage des données (mesures des fonctions de métriques de données et résultats de la classification des données)
  • Jointures et relations (déduites de l'historique des requêtes, déclarées dans les vues sémantiques et les dépendances vue-table)
  • Propriétaire (rôle propriétaire), date de création et date de dernière modification
Sémantique
  • Vue sémantique (tables logiques, dimensions, faits, métriques, relations, synonymes, exemples de valeurs et instructions personnalisées)
  • Propriétaire de la vue sémantique
  • Utilisation de la vue sémantique (vues et lectures sur 30 et 90 jours ; utilisateurs fréquents et tables fréquemment jointes sur 30 jours)

Limites

Le connecteur Snowflake Horizon présente les limites suivantes :

  • La traçabilité n'est pas prise en charge.
  • Le connecteur importe les métadonnées de vos tables Iceberg, mais il ne les associe pas automatiquement aux tables physiques sous-jacentes de votre catalogue Iceberg REST (IRC).
  • Les tags, les résultats de profilage et de qualité des données, les résultats de classification, les jointures de l'historique des requêtes et les insights d'utilisation qui lisent ACCESS_HISTORY (utilisateurs fréquents et tables fréquemment jointes) nécessitent Snowflake Enterprise Edition ou une version ultérieure.

Avant de commencer

Avant de pouvoir importer des métadonnées depuis Snowflake Horizon, effectuez les tâches suivantes :

  1. Accordez les rôles et autorisations requis.
  2. Activez l'API Dataplex et l'API du service de transfert de données BigQuery.
  3. Remplissez les conditions préalables de Snowflake Horizon.
  4. Remplissez les conditions préalables de mise en réseau.

Rôles et autorisations IAM

Pour créer et gérer un job de connecteur Knowledge Catalog, vous devez disposer de rôles IAM (Identity and Access Management) qui accordent des autorisations pour Knowledge Catalog et le service de transfert de données BigQuery.

Pour obtenir les autorisations nécessaires pour configurer un connecteur Snowflake Horizon, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Vous devez également attribuer les deux rôles suivants à l'agent de service du service de transfert de données BigQuery (service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com) :

  • Importateur de groupe d'entrées Dataplex (roles/dataplex.entryGroupImporter) sur le groupe d'entrées de destination ou sur le projet qui le contient. Ce rôle permet à l'agent de service d'importer des métadonnées dans le groupe d'entrées (dataplex.entryGroups.import).

  • Propriétaire des entrées et des liens d'entrée Dataplex (roles/dataplex.entryOwner) sur le projet contenant le groupe d'entrées de destination. Ce rôle permet à l'agent de service d'importer des métadonnées d'utilisation, d'activité et de qualité des données, ainsi que des liens d'entrée. Il comprend les autorisations suivantes :

    • dataplex.entryGroups.useDataProfileAspect
    • dataplex.entryGroups.useDataQualityScorecardAspect
    • dataplex.entryGroups.useManagedConnectorTypes
    • dataplex.entryGroups.useReferenceEntryLink
    • dataplex.entryGroups.useSchemaAspect
    • dataplex.entryGroups.useSchemaJoinAspect
    • dataplex.entryGroups.useSchemaJoinEntryLink
    • dataplex.entryGroups.useUsageAspect
    • dataplex.entryLinks.reference

    Attribuez ce rôle au projet, et pas seulement au groupe d'entrées, car l'importation vérifie l'autorisation dataplex.entryLinks.reference sur le projet. Si l'agent de service ne dispose pas de cette autorisation sur le projet, l'exécution du transfert échoue avec une erreur telle que Permission 'dataplex.entryLinks.reference' denied, et aucune métadonnée n'est importée.

Au lieu d'accorder ces deux rôles, vous pouvez accorder le rôle Propriétaire du groupe d'entrées Dataplex (roles/dataplex.entryGroupOwner) sur le projet contenant le groupe d'entrées de destination. Ce rôle inclut les autorisations des deux rôles et permet également à l'agent de service de créer, de supprimer et de gérer l'accès à tous les groupes d'entrées du projet.

Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Activer les API

Activez l'API Dataplex et l'API Service de transfert de données BigQuery.

Activer les API

Prérequis pour Snowflake Horizon

Si vous souhaitez également exécuter des requêtes SQL ou des jobs Spark sur le catalogue Snowflake distant, consultez Configurer une connexion cross-cloud pour le catalogue Snowflake Horizon.

Le connecteur se connecte à Snowflake en tant qu'utilisateur Snowflake avec une authentification par paire de clés et lit les métadonnées du schéma SNOWFLAKE.ACCOUNT_USAGE. L'authentification par mot de passe n'est pas acceptée. Un administrateur Snowflake, tel qu'un utilisateur disposant du rôle ACCOUNTADMIN, doit effectuer les étapes suivantes :

  1. Créez un rôle pour le connecteur et accordez-lui l'accès à ACCOUNT_USAGE et à un entrepôt qui exécute les requêtes de métadonnées :

    CREATE ROLE IF NOT EXISTS DATAPLEX_CATALOG_READER;
GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE
  TO ROLE DATAPLEX_CATALOG_READER;
GRANT USAGE ON WAREHOUSE WAREHOUSE_NAME
  TO ROLE DATAPLEX_CATALOG_READER;

    Remplacez WAREHOUSE_NAME par le nom de l'entrepôt Snowflake qui exécute les requêtes de métadonnées.

  2. Créez un utilisateur de service pour le connecteur ou utilisez un utilisateur existant, puis attribuez-lui le rôle suivant :

    CREATE USER IF NOT EXISTS USERNAME
  TYPE = SERVICE
  DEFAULT_ROLE = DATAPLEX_CATALOG_READER
  DEFAULT_WAREHOUSE = WAREHOUSE_NAME;
GRANT ROLE DATAPLEX_CATALOG_READER TO USER USERNAME;

    Remplacez USERNAME par le nom de l'utilisateur Snowflake pour le connecteur.

  3. Générez une paire de clés RSA avec la clé privée au format PKCS#8 :

    openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

    Pour chiffrer la clé privée, remplacez -nocrypt par -v2 aes-256-cbc et fournissez la phrase secrète lorsque vous configurez le connecteur. Conservez le fichier de clé privée (rsa_key.p8) dans un endroit sécurisé, car vous le fournirez lors de la configuration du connecteur.

  4. Attribuez la clé publique à l'utilisateur Snowflake :

    ALTER USER USERNAME SET RSA_PUBLIC_KEY='PUBLIC_KEY';

    Remplacez PUBLIC_KEY par le contenu de rsa_key.pub, à l'exclusion des lignes -----BEGIN PUBLIC KEY----- et -----END PUBLIC KEY-----.

  5. Facultatif : pour importer des métadonnées supplémentaires, accordez au rôle de connecteur les droits suivants :

    • Profils de données et résultats de qualité des données : accordez le rôle d'application SNOWFLAKE.DATA_QUALITY_MONITORING_VIEWER :

      GRANT APPLICATION ROLE SNOWFLAKE.DATA_QUALITY_MONITORING_VIEWER
  TO ROLE DATAPLEX_CATALOG_READER;

      Les résultats de qualité des données ne sont importés que pour les vérifications que le rôle peut afficher, ce qui nécessite USAGE sur la base de données et le schéma, SELECT sur la table et USAGE sur les fonctions de métriques de données personnalisées.

    • Clés primaires et clés étrangères : accordez USAGE sur la base de données et le schéma, et SELECT ou REFERENCES sur les tables.

    • Exemples de valeurs et d'instructions personnalisées des vues sémantiques : accordez REFERENCES sur les vues sémantiques.

Pour trouver l'identifiant de compte que vous saisissez lorsque vous configurez le connecteur, exécutez la requête suivante dans Snowflake :

SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME();

Conditions préalables de mise en réseau

Pour permettre au service de transfert de données BigQuery de se connecter de manière sécurisée à des bases de données externes ou à des sources de données cloud tierces avec une adresse IP privée au sein d'un réseau privé, configurez un rattachement de réseau via Private Service Connect.

Si vous vous connectez à un environnement sur site ou à une instance hébergée dans le cloud à l'aide d'une adresse IP publique, aucun rattachement de réseau n'est requis.

Configurer un connecteur Snowflake Horizon

Configurez un connecteur Snowflake Horizon à l'aide de la consoleGoogle Cloud ou de l'API REST.

Console

  1. Dans la console Google Cloud , accédez à la page Knowledge Catalog.

    Accéder à Knowledge Catalog

  2. Dans le menu de navigation, dans la section Gérer, cliquez sur Connecteurs, puis sur Ajouter une connexion.

  3. Dans la liste Connecteurs, sélectionnez la fiche Snowflake Horizon.

  4. Dans la section Détails de la source de données, fournissez les informations de connexion de votre compte Snowflake :

    • Pour Rattachement de réseau, sélectionnez un rattachement de réseau existant si nécessaire, ou créez-en un.
    • Dans le champ Identifiant de compte, saisissez l'identifiant de votre compte Snowflake sans .snowflakecomputing.com (par exemple, myorg-myaccount). Vous pouvez également saisir un localisateur de compte, tel que xy12345.us-east-2.aws.
    • Dans le champ Nom d'utilisateur, saisissez l'utilisateur Snowflake que vous avez configuré pour l'authentification par paire de clés.
    • Dans le champ Clé privée, saisissez la clé privée PKCS#8 de l'utilisateur, par exemple le contenu du fichier rsa_key.p8.
    • Facultatif : pour Phrase secrète de la clé privée, si la clé privée est chiffrée, saisissez sa phrase secrète.
    • Facultatif : Pour Entrepôt, saisissez l'entrepôt qui exécute les requêtes de métadonnées. Si vous ne spécifiez pas d'entrepôt, le connecteur utilise l'entrepôt par défaut de l'utilisateur.
    • (Facultatif) Dans le champ Rôle, saisissez le rôle utilisé par le connecteur, par exemple DATAPLEX_CATALOG_READER. Si vous ne spécifiez pas de rôle, le connecteur utilise le rôle par défaut de l'utilisateur.

    • Dans le champ Objets Snowflake à transférer, cliquez sur Parcourir pour sélectionner les bases de données, les schémas ou les objets individuels (tables, vues, vues sémantiques, zones de préproduction, fonctions et procédures) à importer. La sélection d'une base de données ou d'un schéma importe tous les objets qu'il contient. Les fonctions et les procédures sont listées avec leurs types d'arguments, par exemple CALC(NUMBER, VARCHAR).

      Vous pouvez également saisir manuellement des objets au format TYPE:ACCOUNT/DATABASE[/SCHEMA[/OBJECT]], où TYPE correspond à CATALOG (ou DATABASE), SCHEMA, TABLE, VIEW, SEMANTIC-MODEL, FILESET, FUNCTION ou PROCEDURE (par exemple, SCHEMA:myorg-myaccount/SALES/PUBLIC). Saisissez ACCOUNT au format ORG_NAME-ACCOUNT_NAME en minuscules, comme indiqué dans Parcourir. Les noms de base de données, de schéma et d'objet sont sensibles à la casse. Les formats de nom ne sont pas acceptés.

  5. Dans la section Paramètres de destination :

    • Cliquez sur Parcourir et sélectionnez un groupe d'entrées Knowledge Catalog existant pour stocker les métadonnées importées, ou cliquez sur Créer un groupe d'entrées.
    • Indiquez si vous souhaitez définir les autorisations sur le groupe d'entrées maintenant ou plus tard. Pour permettre aux utilisateurs d'afficher les métadonnées importées, définissez des autorisations sur le groupe d'entrées. Si vous n'avez pas attribué le rôle Importateur de groupes d'entrées Dataplex (roles/dataplex.entryGroupImporter) ou l'autorisation dataplex.entryGroups.import à l'agent de service du service de transfert de données BigQuery au niveau du projet, attribuez-le à ce groupe d'entrées. Vous devez toujours accorder le rôle Propriétaire d'entrées et d'EntryLinks Dataplex (roles/dataplex.entryOwner) sur le projet, car l'autorisation dataplex.entryLinks.reference est vérifiée au niveau du projet. Pour en savoir plus, consultez Rôles et autorisations IAM.

  6. Dans la section Nom de la configuration de transfert, sous Nom à afficher, saisissez le nom du job d'importation des métadonnées.

  7. Dans la section Options de programmation, configurez la fréquence du job d'importation des métadonnées. Si vous sélectionnez À la demande, le job ne s'exécute que lorsque vous le déclenchez manuellement.

  8. Facultatif : dans la section Options de notification, configurez une notification par e-mail ou Pub/Sub en cas d'échec de la tâche.

  9. Facultatif : Dans la section Options avancées, configurez les paramètres de chiffrement. Si vous sélectionnez une clé de chiffrement gérée par le client (CMEK), elle chiffre toutes les données temporaires stockées avant de lancer les jobs d'importation des métadonnées Knowledge Catalog. La clé ne chiffre pas les métadonnées dans le groupe d'entrées Knowledge Catalog de destination.

  10. Cliquez sur Enregistrer.

REST

Exécutez la méthode projects.locations.transferConfigs.create. Dans la ressource TransferConfig, configurez les champs suivants :

  • Définissez le champ dataSourceId sur "snowflake_horizon".
  • Dans le champ metadataDestination, renseignez le champ dataplexConfiguration.entryGroup avec le chemin d'accès à la ressource du groupe d'entrées Knowledge Catalog cible : projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID.
  • Dans le champ params, définissez les paramètres suivants :
    • connector.accountIdentifier (obligatoire) : identifiant de votre compte Snowflake sans .snowflakecomputing.com (par exemple, myorg-myaccount) ou localisateur de compte (tel que xy12345.us-east-2.aws).
    • connector.authentication.username (obligatoire) : l'utilisateur Snowflake.
    • connector.authentication.privateKey (obligatoire) : clé privée de l'utilisateur au format PKCS#8 PEM.
    • connector.authentication.privateKeyPassphrase (facultatif) : phrase secrète de la clé privée, si la clé est chiffrée.
    • connector.warehouse (facultatif) : entrepôt qui exécute les requêtes de métadonnées. Si vous omettez ce paramètre, le connecteur utilise l'entrepôt par défaut de l'utilisateur.
    • connector.role (facultatif) : rôle utilisé par le connecteur. Si vous omettez ce paramètre, le connecteur utilise le rôle par défaut de l'utilisateur.
    • connector.networkAttachment (facultatif) : rattachement de réseau au format projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT_ID.
    • assets (obligatoire) : liste des objets Snowflake à importer au format TYPE:ACCOUNT/DATABASE[/SCHEMA[/OBJECT]], par exemple ["SCHEMA:myorg-myaccount/SALES/PUBLIC"].
  • Facultatif : Pour ne pas inclure la clé privée dans la configuration de transfert, stockez-la dans Secret Manager :
    1. Définissez connector.authentication.privateKey (et connector.authentication.privateKeyPassphrase, si vous en utilisez un) sur le nom de ressource de la version du secret au format projects/SECRET_PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID, puis ajoutez ces noms de paramètres au champ paramConfig.secretManagerManagedParams.
    2. Attribuez le rôle Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) sur chaque secret à l'agent de service du service de transfert de données BigQuery du projet contenant la configuration de transfert (service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com). Les secrets peuvent se trouver dans un autre projet. Si l'agent de service ne peut pas lire un secret, l'exécution échoue avant de démarrer avec une erreur telle que Failed to retrieve secret ... Permission 'secretmanager.versions.access' denied. Le service de transfert de données BigQuery lit les secrets au début de chaque exécution. Par conséquent, si vous définissez VERSION_ID sur latest, une clé alternée est utilisée à partir de l'exécution suivante.

L'exemple suivant montre un corps de requête TransferConfig :

{
  "displayName": "snowflake-metadata-import",
  "dataSourceId": "snowflake_horizon",
  "schedule": "every 24 hours",
  "params": {
    "connector.accountIdentifier": "myorg-myaccount",
    "connector.authentication.username": "USERNAME",
    "connector.authentication.privateKey": "PRIVATE_KEY",
    "connector.warehouse": "WAREHOUSE_NAME",
    "connector.role": "DATAPLEX_CATALOG_READER",
    "assets": [
      "SCHEMA:myorg-myaccount/SALES/PUBLIC"
    ]
  },
  "metadataDestination": {
    "dataplexConfiguration": {
      "entryGroup": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID"
    }
  }
}

Le job s'exécute automatiquement en fonction de votre planification, ou vous pouvez le déclencher manuellement.

Surveiller un job de connecteur Snowflake Horizon

Surveillez un job de connecteur Snowflake Horizon à l'aide de la consoleGoogle Cloud ou de l'API REST.

Console

  1. Dans la console Google Cloud , sur la page Connecteurs, cliquez sur le nom à afficher du job de transfert Snowflake Horizon.
  2. Dans l'onglet Historique des exécutions, cliquez sur Afficher les détails pour afficher les journaux.
  3. Pour afficher les entrées créées, cliquez sur l'onglet Détails, puis sur le lien du groupe d'entrées Destination des métadonnées.

REST

  • Pour lister les exécutions d'une configuration de transfert et afficher leur état, utilisez la méthode projects.locations.transferConfigs.runs.list.

  • Chaque exécution importe les métadonnées collectées dans Knowledge Catalog avec un job d'importation de métadonnées dont l'ID est dts-run-RUN_ID. Pour afficher le résultat de l'importation, comme le nombre d'entrées créées, filtrez les journaux du job dans Logging à l'aide de la requête suivante :

    logName="projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fmetadata_job"
AND resource.labels.metadata_job_id="dts-run-RUN_ID"

  • Pour afficher le résultat d'une importation sans utiliser Logging, appelez la méthode projects.locations.metadataJobs.get sur projects/PROJECT_ID/locations/LOCATION/metadataJobs/dts-run-RUN_ID. Le champ importResult indique le nombre d'entrées et de liens d'entrée créés, mis à jour, inchangés et supprimés.

Rechercher et afficher les métadonnées Snowflake Horizon

  1. Dans la console Google Cloud , accédez à la page Rechercher de Knowledge Catalog.

    Accéder à la recherche

  2. Dans le panneau Filtres, filtrez les éléments Snowflake Horizon à l'aide des sections Projet, Systèmes et Alias de type. Pour filtrer toutes les métadonnées Snowflake Horizon, dans la section Systèmes, sélectionnez Contexte importé, puis dans la sous-section Connecteurs gérés, sélectionnez Snowflake Horizon.

  3. Dans le champ de recherche, saisissez un mot clé ou une requête de recherche en langage naturel. Par exemple, pour afficher tous les éléments Snowflake Horizon via une recherche par mot clé, saisissez system=SNOWFLAKE.

    Pour en savoir plus sur la recherche de ressources, consultez Rechercher des ressources dans Knowledge Catalog. Pour en savoir plus sur les expressions que vous pouvez utiliser dans le champ de recherche, consultez Syntaxe de recherche pour Knowledge Catalog.

Vous pouvez également utiliser l'API LookupContext pour récupérer le contexte LLM de ressources Snowflake Horizon spécifiques. Pour en savoir plus, consultez Récupérer le contexte des éléments de données.

Étapes suivantes