Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
In diesem Dokument wird beschrieben, wie Sie BigQuery-Datenquellen mit Dataform Core deklarieren.
Sie können jeden BigQuery-Tabellentyp als Datenquelle in Dataform deklarieren. Wenn Sie BigQuery-Datenquellen deklarieren, die sich außerhalb von Dataform befinden, können Sie diese Datenquellen als Dataform-Objekte behandeln.
Das Deklarieren von Datenquellen ist optional, kann aber in folgenden Fällen nützlich sein:
Sie können auf deklarierte Quellen genauso wie auf jede andere Tabelle in Dataform verweisen oder sie auflösen.
Deklarierte Quellen im visualisierten Dataform-Diagramm ansehen
Mit Dataform können Sie die Beschreibungen auf Tabellen- und Spaltenebene von extern erstellten Tabellen verwalten.
Workflow-Aufrufe auslösen, die alle abhängigen Elemente einer externen Datenquelle enthalten.
Sie können Datenquellen mit JavaScript- oder SQLX-Dateien deklarieren. In einer JavaScript-Datei können Sie mehrere Datenquellen pro Datei deklarieren. In einer SQLX-Datei können Sie eine Datenquelle pro Datei deklarieren.
Bitten Sie Ihren Administrator, Ihnen für Arbeitsbereiche die IAM-Rolle Dataform Editor (roles/dataform.editor) zuzuweisen, damit Sie die Berechtigungen erhalten, die Sie zum Deklarieren einer Datenquelle benötigen.
Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.
JavaScript-Datei für mehrere Datenquellendeklarationen erstellen
Speichern Sie JavaScript-Dateien für Datenquellendeklarationen im Verzeichnis definitions/.
So erstellen Sie eine neue JavaScript-Datei im Verzeichnis definitions/:
Rufen Sie in der Google Cloud Console die Seite Dataform auf.
DATABASE_PROJECT_ID: Die Projekt-ID des Projekts, das die Datenquelle enthält.
BIGQUERY_SCHEMA: Das BigQuery-Dataset, in dem sich die Datenquelle befindet.
RELATION_NAME: der Name der Tabelle oder Ansicht, die Sie als Datenquelle verwenden möchten. Sie können diesen Namen später verwenden, um in Dataform auf die Datenquelle zu verweisen.
SQLX-Datei für die Deklaration von Datenquellen erstellen
Speichern Sie SQLX-Dateien für Datenquellendeklarationen im Verzeichnis definitions/.
So erstellen Sie eine neue SQLX-Datei im Verzeichnis definitions/:
Rufen Sie in der Google Cloud Console die Seite Dataform auf.
DATABASE: Die Projekt-ID des Projekts, das die Datenquelle enthält.
SCHEMA: Das BigQuery-Dataset, in dem sich die Datenquelle befindet.
NAME: der Name der Tabelle oder Ansicht, die Sie als Datenquelle verwenden möchten. Sie können diesen Namen später verwenden, um in Dataform auf die Datenquelle zu verweisen.
Optional: Klicken Sie auf Formatieren.
Das folgende Codebeispiel zeigt eine Beispieldeklaration der Tabelle shakespeare im Dataset samples des Projekts bigquery-public-data als Datenquelle:
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-19 (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)."]]
