Déclarer une source de données

Ce document explique comment déclarer des sources de données BigQuery avec Dataform Core.

Tout type de table BigQuery peut être déclaré comme une source de données dans Dataform. Déclarer des sources de données BigQuery externes à Dataform vous permet de les traiter comme des objets Dataform.

La déclaration de sources de données est facultative, mais peut être utile lorsque vous souhaitez effectuer les opérations suivantes :

  • Référencer ou résoudre des sources déclarées de la même manière que n'importe quelle autre table dans Dataform.
  • Afficher les sources déclarées dans le graphique Dataform visualisé.
  • Utiliser Dataform pour gérer les descriptions au niveau de la table et de la colonne des tables créées en externe.
  • Déclencher des appels de workflow qui incluent tous les dépendants d'une source de données externe.

Vous pouvez déclarer des sources de données à l'aide de fichiers JavaScript ou SQLX. Dans un fichier JavaScript, vous pouvez déclarer plusieurs sources de données par fichier. Dans un fichier SQLX, vous ne pouvez déclarer qu'une seule source de données par fichier.

Avant de commencer

Avant de déclarer une source de données, créez et initialisez un espace de travail de développement dans votre dépôt.

Rôles requis

Pour obtenir les autorisations nécessaires pour déclarer une source de données, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Dataform (roles/dataform.editor) sur les espaces de travail. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Créer un fichier JavaScript pour plusieurs déclarations de sources de données

Stockez les fichiers JavaScript pour les déclarations de sources de données dans le répertoire definitions/. Pour créer un fichier JavaScript dans le répertoire definitions/, procédez comme suit :

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

    Accéder à la page Dataform

  2. Sélectionnez un dépôt.

  3. Sélectionnez un espace de travail de développement.

  4. Dans le volet Fichiers, à côté de definitions/, cliquez sur le menu Plus.

  5. Cliquez sur Créer un fichier.

  6. Dans le volet Créer un fichier, procédez comme suit :

    1. Dans le champ Ajouter un chemin d'accès au fichier, après definitions/, saisissez le nom du fichier suivi de .js. Par exemple, definitions/declarations.js.

      Les noms de fichiers ne peuvent contenir que des chiffres, des lettres, des traits d'union et des traits de soulignement.

    2. Cliquez sur Créer un fichier.

Ajouter une déclaration à un fichier JavaScript

Vous pouvez déclarer plusieurs sources de données par fichier JavaScript. Pour ajouter une déclaration, procédez comme suit :

  1. Dans votre espace de travail de développement, dans le volet Fichiers, cliquez sur votre fichier JavaScript pour les déclarations de sources de données.

  2. Dans le fichier, pour chaque source de données, ajoutez l'extrait de code suivant :

      declare({
    database: "DATABASE_PROJECT_ID",
    schema: "BIGQUERY_SCHEMA",
    name: "RELATION_NAME",
  });

    Remplacez les éléments suivants :

    • DATABASE_PROJECT_ID: ID du projet du projet contenant la source de données.
    • BIGQUERY_SCHEMA: ensemble de données BigQuery dans lequel existe la source de données.
    • RELATION_NAME: nom de la table ou de la vue que vous souhaitez utiliser comme source de données. Vous pourrez ensuite vous référer à la source de données dans Dataform à l'aide de ce nom.

Créer un fichier SQLX pour la déclaration de la source de données

Stockez les fichiers SQLX pour les déclarations de sources de données dans le répertoire definitions/. Pour créer un fichier SQLX dans le répertoire definitions/, procédez comme suit :

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

    Accéder à la page Dataform

  2. Sélectionnez un dépôt.

  3. Sélectionnez un espace de travail de développement.

  4. Dans le volet Fichiers, à côté de definitions/, cliquez sur le menu Plus.

  5. Cliquez sur Créer un fichier.

  6. Dans le volet Créer un fichier, procédez comme suit :

    1. Dans le champ Ajouter un chemin d'accès au fichier, après definitions/, saisissez le nom du fichier suivi de .sqlx. Par exemple, definitions/dataset-declaration.sqlx.

      Les noms de fichiers ne peuvent contenir que des chiffres, des lettres, des traits d'union et des traits de soulignement.

    2. Cliquez sur Créer un fichier.

Déclarer une source de données

Vous ne pouvez déclarer qu'une seule source de données par fichier de déclaration SQLX. Pour déclarer une source de données dans le bloc de configuration d'un fichier SQLX, procédez comme suit :

  1. Dans votre espace de travail de développement, dans le volet Fichiers, cliquez sur votre fichier SQLX pour la déclaration de la source de données.

  2. Dans le fichier, saisissez l'extrait de code suivant :

    config {
  type: "declaration",
  database: "DATABASE",
  schema: "SCHEMA",
  name: "NAME",
}

    Remplacez les éléments suivants :

    • DATABASE: ID du projet du projet contenant la source de données.
    • SCHEMA: ensemble de données BigQuery dans lequel existe la source de données.
    • NAME: nom de la table ou de la vue que vous souhaitez utiliser comme source de données. Vous pourrez ensuite vous référer à la source de données dans Dataform à l'aide de ce nom.

  3. Facultatif : cliquez sur Mettre en forme.

L'exemple de code suivant montre un exemple de déclaration de la table shakespeare dans l'ensemble de données samples du projet bigquery-public-data en tant que source de données :

    config {
      type: "declaration",
      database: "bigquery-public-data",
      schema: "samples",
      name: "shakespeare",
    }

Étape suivante