Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Dokumen ini menunjukkan cara mendeklarasikan sumber data BigQuery dengan
Dataform core.
Anda dapat mendeklarasikan jenis tabel BigQuery
sebagai sumber data di Dataform. Dengan mendeklarasikan sumber data BigQuery yang eksternal ke Dataform, Anda dapat memperlakukan sumber data tersebut sebagai objek Dataform.
Mendeklarasikan sumber data bersifat opsional, tetapi dapat berguna saat Anda ingin melakukan hal berikut:
Mereferensikan atau menyelesaikan sumber yang dideklarasikan dengan cara yang sama seperti tabel lainnya di Dataform.
Melihat sumber yang dideklarasikan dalam grafik Dataform yang divisualisasikan.
Gunakan Dataform untuk mengelola deskripsi tingkat tabel dan tingkat kolom dari tabel yang dibuat secara eksternal.
Memicu pemanggilan alur kerja yang mencakup semua dependen sumber data eksternal.
Anda dapat mendeklarasikan sumber data menggunakan file JavaScript atau SQLX. Dalam file JavaScript, Anda dapat mendeklarasikan beberapa sumber data per file. Dalam file SQLX, Anda dapat mendeklarasikan satu sumber data per file.
Untuk mendapatkan izin yang diperlukan guna mendeklarasikan sumber data, minta administrator untuk memberi Anda peran IAM Dataform Editor (roles/dataform.editor) di ruang kerja.
Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.
Membuat file JavaScript untuk beberapa deklarasi sumber data
Simpan file JavaScript untuk deklarasi sumber data di direktori definitions/.
Untuk membuat file JavaScript baru di direktori definitions/, ikuti langkah-langkah berikut:
DATABASE_PROJECT_ID: project ID project yang berisi sumber data.
BIGQUERY_SCHEMA: set data BigQuery tempat sumber data berada.
RELATION_NAME: nama tabel atau tampilan yang ingin Anda gunakan sebagai
sumber data. Anda dapat menggunakan nama tersebut nanti untuk mereferensikan sumber data di Dataform.
Membuat file SQLX untuk deklarasi sumber data
Simpan file SQLX untuk deklarasi sumber data di direktori definitions/.
Untuk membuat file SQLX baru di direktori definitions/, ikuti langkah-langkah berikut:
Di panel Files, di samping definitions/, klik menu More.
Klik Create file.
Di panel Create new file, lakukan hal berikut:
Di kolom Add a file path, setelah definitions/, masukkan nama
file yang diikuti dengan .sqlx. Contoh,
definitions/dataset-declaration.sqlx.
Nama file hanya boleh berisi angka, huruf, tanda hubung, dan garis bawah.
Klik Create file.
Mendeklarasikan sumber data
Anda dapat mendeklarasikan satu sumber data per file deklarasi SQLX. Untuk mendeklarasikan sumber data dalam blok konfigurasi file SQLX, ikuti langkah-langkah berikut:
Di ruang kerja pengembangan Anda, di panel Files, klik file SQLX Anda untuk deklarasi sumber data.
DATABASE: project ID project yang berisi sumber data.
SCHEMA: set data BigQuery tempat sumber data berada.
NAME: nama tabel atau tampilan yang ingin Anda gunakan sebagai
sumber data. Anda dapat menggunakan nama tersebut nanti untuk mereferensikan sumber data di Dataform.
Opsional: Klik Format.
Contoh kode berikut menunjukkan contoh deklarasi tabel shakespeare
dalam set data samples project bigquery-public-data sebagai
sumber data:
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 2025-09-01 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)."]]
