Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Ce document vous explique comment déclarer des sources de données BigQuery avec Dataform Core.
Tout type de table BigQuery peut être déclaré comme 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 des sources de données est facultative, mais peut être utile lorsque vous souhaitez effectuer les opérations suivantes :
Référencez ou résolvez les sources déclarées de la même manière que n'importe quelle autre table dans Dataform.
Affichez les sources déclarées dans le graphique Dataform visualisé.
Utilisez Dataform pour gérer les descriptions au niveau des tables et des colonnes des tables créées en externe.
Déclenchez des appels de workflow qui incluent tous les éléments 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 pouvez déclarer une source de données par fichier.
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 la page Gérer l'accès aux projets, aux dossiers et aux organisations.
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 :
Dans la console Google Cloud , accédez à la page Dataform.
Sélectionnez un espace de travail de développement.
Dans le volet Fichiers, à côté de definitions/, cliquez sur le menu Plus.
Cliquez sur Créer un fichier.
Dans le volet Créer un fichier, procédez comme suit :
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.
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 :
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.
Dans le fichier, pour chaque source de données, ajoutez l'extrait de code suivant :
DATABASE_PROJECT_ID : ID du projet contenant la source de données.
BIGQUERY_SCHEMA : ensemble de données BigQuery dans lequel se trouve 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 utiliser ce nom pour faire référence à la source de données dans Dataform.
Créer un fichier SQLX pour déclarer une 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 :
Dans la console Google Cloud , accédez à la page Dataform.
Sélectionnez un espace de travail de développement.
Dans le volet Fichiers, à côté de definitions/, cliquez sur le menu Plus.
Cliquez sur Créer un fichier.
Dans le volet Créer un fichier, procédez comme suit :
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.
Cliquez sur Créer un fichier.
Déclarer une source de données
Vous pouvez déclarer une 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 :
Dans votre espace de travail de développement, dans le volet Fichiers, cliquez sur votre fichier SQLX pour la déclaration de source de données.
Dans le fichier, saisissez l'extrait de code suivant :
DATABASE : ID du projet contenant la source de données.
SCHEMA : ensemble de données BigQuery dans lequel se trouve 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 utiliser ce nom pour faire référence à la source de données dans Dataform.
Facultatif : Cliquez sur Format.
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 :
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/04 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 2025/09/04 (UTC)."],[[["\u003cp\u003eDataform allows the declaration of BigQuery data sources, treating them as Dataform objects even if they are external to Dataform.\u003c/p\u003e\n"],["\u003cp\u003eDeclaring data sources in Dataform is optional but enables referencing them like any other table, viewing them in the Dataform graph, and managing their descriptions.\u003c/p\u003e\n"],["\u003cp\u003eData sources can be declared using either JavaScript files, where multiple sources are allowed per file, or SQLX files, where only one source per file is allowed.\u003c/p\u003e\n"],["\u003cp\u003eTo declare a data source, you need the Dataform Editor role and can utilize JavaScript or SQLX files, each requiring specific code snippets and file creation processes within the \u003ccode\u003edefinitions/\u003c/code\u003e directory.\u003c/p\u003e\n"],["\u003cp\u003eOnce declared, data sources can be used in workflow invocations that include all dependents of that external data source.\u003c/p\u003e\n"]]],[],null,["# Declare a data source\n\nThis document shows you how to declare BigQuery data sources with\n[Dataform core](/dataform/docs/overview#dataform-core).\n\nYou can declare any [BigQuery table type](/bigquery/docs/tables-intro)\nas a data source in Dataform. Declaring BigQuery data sources\nthat are external to Dataform lets you treat those data sources as\nDataform objects.\n\nDeclaring data sources is **optional**, but can be useful when you want to do the following:\n\n- Reference or resolve declared sources in the same way as any other table in Dataform.\n- View declared sources in the visualized Dataform graph.\n- Use Dataform to manage the table-level and column-level descriptions of externally created tables.\n- Trigger workflow invocations that include all the dependents of an external data source.\n\nYou can declare data sources using JavaScript or SQLX files. In a JavaScript file, you can declare multiple data sources per file. In a SQLX file, you can declare one data source per file.\n\nBefore you begin\n----------------\n\nBefore you declare a data source,\n[create and initialize a development workspace in your repository](/dataform/docs/create-workspace).\n\n### Required roles\n\n\nTo get the permissions that\nyou need to declare a data source,\n\nask your administrator to grant you the\n\n\n[Dataform Editor](/iam/docs/roles-permissions/dataform#dataform.editor) (`roles/dataform.editor`)\nIAM role on workspaces.\n\n\nFor more information about granting roles, see [Manage access to projects, folders, and organizations](/iam/docs/granting-changing-revoking-access).\n\n\nYou might also be able to get\nthe required permissions through [custom\nroles](/iam/docs/creating-custom-roles) or other [predefined\nroles](/iam/docs/roles-overview#predefined).\n\nCreate a JavaScript file for multiple data source declarations\n--------------------------------------------------------------\n\nStore JavaScript files for data source declarations in the `definitions/` directory.\nTo create a new JavaScript file in the `definitions/` directory, follow these steps:\n\n1. In the Google Cloud console, go to the **Dataform** page.\n\n [Go to the Dataform page](https://console.cloud.google.com/bigquery/dataform)\n2. Select a repository.\n\n3. Select a development workspace.\n\n4. In the **Files** pane, next to `definitions/`, click the **More** menu.\n\n5. Click **Create file**.\n\n6. In the **Create new file** pane, do the following:\n\n 1. In the **Add a file path** field, after `definitions/`, enter the name\n of the file followed by `.js`. For example,\n `definitions/declarations.js`.\n\n Filenames can only include numbers, letters, hyphens, and underscores.\n 2. Click **Create file**.\n\n### Add a declaration to a JavaScript file\n\nYou can declare multiple data sources per JavaScript file. To add a new declaration, follow these steps:\n\n1. In your development workspace, in the **Files** pane, click your JavaScript file for data source declarations.\n2. In the file, for each data source, add the following code snippet:\n\n declare({\n database: \"\u003cvar translate=\"no\"\u003eDATABASE_PROJECT_ID\u003c/var\u003e\",\n schema: \"\u003cvar translate=\"no\"\u003eBIGQUERY_SCHEMA\u003c/var\u003e\",\n name: \"\u003cvar translate=\"no\"\u003eRELATION_NAME\u003c/var\u003e\",\n });\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eDATABASE_PROJECT_ID\u003c/var\u003e: the project ID of the project which contains the data source.\n - \u003cvar translate=\"no\"\u003eBIGQUERY_SCHEMA\u003c/var\u003e: the BigQuery dataset in which the data source exists.\n - \u003cvar translate=\"no\"\u003eRELATION_NAME\u003c/var\u003e: the name of the table or view that you want to use as the data source. You can later use that name to reference the data source in Dataform.\n\nCreate a SQLX file for data source declaration\n----------------------------------------------\n\nStore SQLX files for data source declarations in the `definitions/` directory.\nTo create a new SQLX file in the `definitions/` directory, follow these steps:\n\n1. In the Google Cloud console, go to the **Dataform** page.\n\n [Go to the Dataform page](https://console.cloud.google.com/bigquery/dataform)\n2. Select a repository.\n\n3. Select a development workspace.\n\n4. In the **Files** pane, next to `definitions/`, click the **More** menu.\n\n5. Click **Create file**.\n\n6. In the **Create new file** pane, do the following:\n\n 1. In the **Add a file path** field, after `definitions/`, enter the name\n of the file followed by `.sqlx`. For example,\n `definitions/dataset-declaration.sqlx`.\n\n Filenames can only include numbers, letters, hyphens, and underscores.\n 2. Click **Create file**.\n\n### Declare a data source\n\nYou can declare one data source per a SQLX declaration file. To declare a data\nsource in the configuration block of an SQLX file, follow these steps:\n\n1. In your development workspace, in the **Files** pane, click your SQLX file for data source declaration.\n2. In the file, enter the following code snippet:\n\n config {\n type: \"declaration\",\n database: \"\u003cvar translate=\"no\"\u003eDATABASE\u003c/var\u003e\",\n schema: \"\u003cvar translate=\"no\"\u003eSCHEMA\u003c/var\u003e\",\n name: \"\u003cvar translate=\"no\"\u003eNAME\u003c/var\u003e\",\n }\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eDATABASE\u003c/var\u003e: the project ID of the project which contains the data source.\n - \u003cvar translate=\"no\"\u003eSCHEMA\u003c/var\u003e: the BigQuery dataset in which the data source exists.\n - \u003cvar translate=\"no\"\u003eNAME\u003c/var\u003e: the name of the table or view that you want to use as the data source. You can later use that name to reference the data source in Dataform.\n3. Optional: Click **Format**.\n\nThe following code sample shows a sample declaration of the `shakespeare`\ntable in the `samples` dataset of the `bigquery-public-data` project as\na data source: \n\n config {\n type: \"declaration\",\n database: \"bigquery-public-data\",\n schema: \"samples\",\n name: \"shakespeare\",\n }\n\nWhat's next\n-----------\n\n- To learn how to declare a data source with JavaScript, see [Create workflows exclusively with JavaScript](/dataform/docs/javascript-in-dataform#create-workflows-with-javascript).\n- To learn how to define a table, see [Create tables](/dataform/docs/create-tables#create-table).\n- To learn how to configure table partitions and clusters, see [Create table partitions and clusters](/dataform/docs/create-tables#create-table-partitions-clusters)."]]
