Dokumen ini menjelaskan metode, properti, dan opsi konfigurasi inti Dataform. Anda dapat menggunakan inti Dataform dalam file SQLX dan JavaScript.
assert()
assert
|
(name: string, query?: AContextable
|
|
Menambahkan pernyataan Dataform ke grafik yang dikompilasi. Hanya tersedia di direktori |
Contoh:
// definitions/file.js
assert("name").query(ctx => "select 1");
CommonContext
Metode konteks tersedia saat mengevaluasi kode SQL yang dapat dikontekskan,
seperti dalam file SQLX, atau saat menggunakan argumen
Contextable dengan inti Dataform.
database
|
() => string
|
| Menampilkan database set data ini, jika ada. | |
name
|
() => string
|
| Menampilkan nama tabel ini. | |
ref
|
(ref: Resolvable | string[], rest: string[]) => string
|
Mereferensikan tindakan lain, menambahkannya sebagai dependensi ke tindakan ini,
menampilkan SQL yang valid untuk digunakan dalam ekspresi from.
Fungsi ini dapat dipanggil dengan objek
Fungsi ini juga dapat dipanggil menggunakan argumen individual untuk nilai
${ref("database", "schema", "name")}
${ref("schema", "name")}
${ref("name")}
|
|
resolve
|
(ref: Resolvable | string[], rest: string[]) => string
|
Serupa dengan ref, tetapi tidak menambahkan
tindakan yang dirujuk sebagai dependensi pada tindakan ini.
|
|
self
|
() => string
|
Setara dengan resolve(name()).
Menampilkan string SQL yang valid yang dapat digunakan untuk mereferensikan tabel yang dihasilkan oleh tindakan ini. |
|
schema
|
() => string
|
| Menampilkan skema set data ini. |
Contextable
Argumen yang dapat dikontekskan dapat meneruskan nilai biasa untuk jenis generiknya
T atau fungsi yang dipanggil dengan objek konteks untuk
jenis operasi ini.
T | (ctx: Context) => T
Dataform
Variabel global yang berisi objek IProjectConfig.
Diperlukan untuk mendapatkan properti IProjectConfig, misalnya:
dataform.projectConfig.vars.myVariableName === "myVariableValue"
declare()
declare
|
(dataset: dataform.ITarget)
|
|
Mendeklarasikan set data sebagai sumber data Dataform. Hanya tersedia di direktori |
Contoh:
// definitions/file.js
declare({name: "a-declaration"})
defaultLocation
Properti defaultLocation menentukan lokasi set data BigQuery default Anda. Dataform menggunakan lokasi ini untuk memproses kode Anda dan menyimpan hasilnya. Lokasi pemrosesan ini harus cocok dengan lokasi set data BigQuery Anda. Namun, lokasi ini tidak harus cocok dengan lokasi repositori Dataform.
Jika Anda tidak menetapkan properti defaultLocation, Dataform
akan menentukan lokasi berdasarkan set data yang dirujuk oleh kueri SQL Anda. Cara kerjanya adalah sebagai berikut:
- Jika kueri Anda mereferensikan set data dari lokasi yang sama, Dataform akan menggunakan lokasi tersebut.
- Jika kueri Anda mereferensikan set data dari dua atau beberapa lokasi yang berbeda, error akan terjadi. Untuk mengetahui detail tentang batasan ini, lihat Replikasi set data lintas-region.
- Jika kueri Anda tidak mereferensikan set data apa pun, lokasi default untuk
Dataform adalah multi-region
US. Untuk memilih lokasi lain, tetapkan propertidefaultLocation. Atau, gunakan variabel sistem@@locationdalam kueri Anda.
Untuk mengetahui informasi selengkapnya, lihat Menentukan lokasi.
IActionConfig
Menentukan tag Dataform dan dependensi yang diterapkan ke tindakan alur kerja.
tags
|
string[]
|
|
Daftar tag yang ditentukan pengguna yang harus diberi label pada tindakan. |
|
dependencies
|
Resolvable| Resolvable[]
|
|
Dependensi tindakan. |
|
disabled
|
boolean
|
|
Jika disetel ke benar (true), tindakan ini tidak akan dijalankan. Namun, tindakan tersebut masih dapat diandalkan. Berguna untuk menonaktifkan sementara tindakan yang rusak. |
IAssertionConfig
Opsi konfigurasi untuk jenis tindakan assertion.
database
|
string
|
| Database (project IDGoogle Cloud ) tempat membuat tampilan yang sesuai untuk pernyataan ini. | |
description
|
string
|
| Deskripsi pernyataan ini. | |
disabled
|
boolean
|
Jika ditetapkan ke true, tindakan ini tidak akan dijalankan.
Tindakan ini masih dapat diandalkan. Berguna untuk menonaktifkan sementara tindakan yang rusak.
|
|
hermetic
|
boolean
|
| Mendeklarasikan apakah tindakan ini bersifat hermetik. Tindakan bersifat hermetis
jika semua dependensinya dideklarasikan secara eksplisit.
Jika tindakan ini bergantung pada data dari sumber yang tidak dideklarasikan
sebagai dependensi, tetapkan |
|
schema
|
string
|
| Skema (set data BigQuery) tempat membuat tampilan yang sesuai untuk pernyataan ini. | |
tags
|
string[]
|
| Daftar tag yang ditentukan pengguna yang diterapkan pada tindakan ini. |
IBigQueryOptions
Opsi warehouse khusus BigQuery.
additionalOptions
|
|
| Key-value pair untuk opsi tabel, tampilan,
dan tampilan terwujud.
Beberapa opsi, misalnya,
Nilai string harus diapit dalam tanda kutip ganda, misalnya:
Jika nama opsi berisi karakter khusus, sertakan nama dalam tanda kutip,
misalnya: |
|
clusterBy
|
string[]
|
| Kunci yang digunakan untuk mengelompokkan partisi. | |
labels
|
|
| Pasangan nilai kunci untuk label BigQuery.
Jika nama label berisi karakter khusus, misalnya tanda hubung,
beri tanda kutip pada namanya, misalnya, |
|
partitionBy
|
string
|
| Kunci untuk mempartisi tabel. Biasanya nama stempel waktu atau kolom tanggal. | |
partitionExpirationDays
|
number
|
| Jumlah hari BigQuery menyimpan data di setiap partisi. Setelan ini berlaku untuk semua partisi dalam tabel, tetapi dihitung secara terpisah untuk setiap partisi berdasarkan waktu partisi. | |
requirePartitionFilter
|
boolean
|
Menyatakan apakah tabel berpartisi memerlukan filter predikat klausa WHERE
yang memfilter kolom partisi.
|
|
updatePartitionFilter
|
string
|
| Filter berbasis SQL untuk saat update inkremental diterapkan. | |
iceberg
|
IIcebergOptions
|
| Opsi khusus Apache Iceberg untuk tabel terkelola Iceberg. |
IIcebergOptions
Opsi khusus Apache Iceberg untuk tabel terkelola Iceberg.
connection |
string |
|
Opsional. Nama resource koneksi Cloud Storage Anda, yang menyediakan kredensial untuk membaca dari dan menulis ke penyimpanan eksternal. Formatnya dapat berupa salah satu dari berikut:
Nilai defaultnya adalah |
|
file_format
|
string
|
|
Opsional. Format file untuk data tabel.
Hanya |
|
bucket_name
|
string
|
|
Wajib di tingkat tabel atau alur kerja. Nama bucket Cloud Storage tempat data tabel disimpan.
Anda harus memberikan |
|
table_folder_root
|
string
|
|
Opsional. Nama folder tingkat pertama di dalam bucket Cloud Storage tempat data tabel disimpan.
Jika Anda tidak menetapkan properti ini, Dataform akan menggunakan default tingkat alur kerja dari |
|
table_folder_subpath
|
string
|
|
Opsional. Subfolder dalam
Jika Anda tidak menetapkan properti ini, Dataform akan menggunakan default tingkat alur kerja dari |
Nilai ini membentuk URI Cloud Storage dalam format berikut:
gs://BUCKET_NAME/TABLE_FOLDER_ROOT/TABLE_FOLDER_SUBPATH.
IColumnsDescriptor
Menjelaskan kolom dalam tabel.
{ [name]: string | IRecordDescriptor }
IDeclarationConfig
Opsi konfigurasi untuk jenis tindakan declaration.
columns
|
IColumnsDescriptor
|
| Deskripsi kolom dalam tabel. | |
database
|
string
|
| Database (project IDGoogle Cloud ) tempat tabel sumber berada. | |
description
|
string
|
| Deskripsi tabel. | |
schema
|
string
|
| Skema (set data BigQuery) tempat tabel sumber berada. |
IDependenciesConfig
Menentukan dependensi tindakan alur kerja.
dependencies
|
Resolvable| Resolvable[]
|
|
Satu atau beberapa dependensi eksplisit untuk tindakan ini. Tindakan dependensi
akan berjalan sebelum tindakan dependen.
Biasanya, ini akan tetap tidak ditetapkan, karena sebagian besar dependensi dideklarasikan
sebagai produk sampingan dari penggunaan fungsi |
|
hermetic
|
boolean
|
|
Menyatakan apakah tindakan ini bersifat hermetik atau tidak. Suatu tindakan bersifat hermetis jika
semua dependensinya dideklarasikan secara eksplisit. Jika tindakan ini bergantung pada
data dari sumber yang belum dideklarasikan sebagai dependensi, maka
|
IDocumentableConfig
Menentukan deskripsi set data dan kolomnya.
columns
|
IColumnsDescriptor
|
|
Deskripsi kolom dalam set data. |
|
description
|
string
|
|
Deskripsi set data. |
INamedConfig
Menentukan jenis dan nama tindakan alur kerja.
type
|
string
|
|
Jenis tindakan. |
|
name
|
string
|
|
Nama tindakan. |
IOperationConfig
Opsi konfigurasi untuk jenis tindakan operations.
columns
|
IColumnsDescriptor
|
| Deskripsi kolom dalam tabel. | |
database
|
string
|
| Database (Google Cloud project ID) tempat untuk membuat output tindakan ini. | |
description
|
string
|
| Deskripsi tabel. | |
disabled
|
boolean
|
Jika disetel ke true, tindakan ini tidak akan dijalankan.
Tindakan tersebut masih dapat diandalkan.
Berguna untuk menonaktifkan sementara tindakan yang rusak.
|
|
hasOutput
|
boolean
|
Menyatakan bahwa tindakan operations ini membuat tabel
yang dapat direferensikan menggunakan fungsi ref.
Jika ditetapkan ke create or replace table ${self()} as select ...
|
|
hermetic
|
boolean
|
| Mendeklarasikan apakah tindakan ini bersifat hermetik. Tindakan bersifat hermetis
jika semua dependensinya dideklarasikan secara eksplisit.
Jika tindakan ini bergantung pada data dari sumber yang tidak dideklarasikan
sebagai dependensi, tetapkan |
|
schema
|
string
|
| Skema (set data BigQuery) tempat membuat output tindakan ini. | |
tags
|
string[]
|
| Daftar tag yang ditentukan pengguna yang diterapkan pada tindakan ini. |
IProjectConfig
Berisi setelan kompilasi repositori Dataform.
defaultDatabase
|
string
|
| Wajib. Database default (Google Cloud project ID). | |
defaultSchema
|
string
|
| Wajib. Skema default (ID set data BigQuery). | |
defaultLocation
|
string
|
| Opsional. Lokasi BigQuery default tempat Dataform membuat tabel. | |
assertionSchema
|
string
|
| Wajib. Skema default (ID set data BigQuery) untuk pernyataan. | |
vars
|
map (key: string, value: string)
|
Opsional. Variabel buatan pengguna yang tersedia
untuk kode project selama kompilasi.
Objek yang berisi daftar pasangan "key": value.
Contoh: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
|
|
databaseSuffix
|
string
|
| Opsional. Akhiran yang harus ditambahkan ke semua nama database (project IDGoogle Cloud ). | |
schemaSuffix
|
string
|
| Opsional. Akhiran yang harus ditambahkan ke semua nama skema (ID set data BigQuery). | |
tablePrefix
|
string
|
| Opsional. Awalan yang harus ditambahkan di depan semua nama tabel. | |
defaultIcebergConfig
|
object
|
Opsional. Default tingkat alur kerja untuk tabel terkelola Apache Iceberg.
Berisi kolom berikut:
|
|
preserveGovernanceControls
|
boolean
|
Opsional. Jika ditetapkan ke true, Dataform
otomatis mempertahankan kebijakan data dan tag tata kelola data
BigQuery yang ada (Pratinjau) di seluruh eksekusi alur kerja untuk semua tabel di
repositori.
|
|
warehouse
|
string
|
Wajib. Harus ditetapkan ke bigquery.
|
Anda dapat
menetapkan properti IProjectConfig di setelan alur kerja
di tingkat repositori.
Anda dapat
mengganti properti defaultSchema dan defaultDatabase untuk setiap tabel.
Anda dapat mengakses semua properti IProjectConfig dalam pernyataan SELECT SQL
dalam file SQLX atau JavaScript.
Contoh kode berikut menunjukkan variabel kompilasi kustom myVariableName yang ditetapkan di setelan alur kerja dengan properti projectConfig.vars, yang diakses dalam pernyataan SELECT dalam file SQLX:
config { type: "view" }
SELECT ${when(
dataform.projectConfig.vars.myVariableName === "myVariableValue",
"myVariableName is set to myVariableValue!",
"myVariableName is not set to myVariableValue!"
)}
Untuk mengetahui informasi selengkapnya tentang cara mengganti setelan konfigurasi project untuk setiap hasil kompilasi, lihat resource REST CodeCompilationConfig di Dataform API.
IRecordDescriptor
Menjelaskan struct, objek, atau kumpulan data dalam tabel yang memiliki kolom bertingkat.
bigqueryPolicyTags
|
string | string[]
|
| ID lengkap tag kebijakan BigQuery yang diterapkan
ke kolom ini. ID lengkap tag kebijakan BigQuery mencakup nama project, lokasi, dan taksonomi,
Contoh: |
|
columns
|
IColumnsDescriptor
|
| Deskripsi kolom dalam struct, objek, atau kumpulan data. | |
description
|
string
|
| Deskripsi struct, objek, atau rekaman. |
ITableAssertions
Opsi untuk membuat pernyataan sebagai bagian dari definisi tabel.
nonNull
|
string | string[]
|
Kolom yang tidak boleh berupa NULL.
Jika disetel, pernyataan yang sesuai akan gagal jika ada baris yang berisi
nilai |
|
rowConditions
|
string[]
|
| Kondisi umum yang harus berlaku untuk semua baris dalam tabel.
Jika ditetapkan, pernyataan yang sesuai akan gagal jika ada baris yang melanggar salah satu kondisi ini. |
|
uniqueKey
|
string | string[]
|
| Kolom yang merupakan indeks kunci unik tabel.
Jika disetel, pernyataan yang dihasilkan akan gagal jika ada lebih dari satu baris dalam tabel dengan nilai yang sama untuk semua kolom ini. |
|
uniqueKeys
|
[]
|
| Kombinasi kolom, yang masing-masing merupakan
indeks kunci unik tabel.
Jika disetel, pernyataan yang dihasilkan akan gagal jika ada lebih dari satu baris dalam tabel dengan nilai yang sama untuk semua kolom dalam kunci unik. |
ITableConfig
Opsi konfigurasi untuk tindakan table, termasuk jenis tabel table, view, dan incremental.
Memperluas IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig, dan ITargetableConfig.
assertions
|
ITableAssertions
|
| Pernyataan yang akan dijalankan pada tabel.
Jika dikonfigurasi, pernyataan yang relevan akan otomatis dibuat dan dijalankan sebagai dependensi tabel ini. |
|
bigquery
|
IBigQueryOptions
|
| Opsi warehouse khusus BigQuery. | |
columns
|
IColumnsDescriptor
|
| Deskripsi kolom dalam tabel. | |
database
|
string
|
| Database (Google Cloud project ID) tempat membuat output tindakan ini. | |
description
|
string
|
| Deskripsi tabel. | |
disabled
|
boolean
|
Jika disetel ke true, tindakan ini tidak akan dijalankan.
Tindakan ini masih dapat diandalkan.
Berguna untuk menonaktifkan sementara tindakan yang rusak.
|
|
hermetic
|
boolean
|
| Mendeklarasikan apakah tindakan ini bersifat hermetik. Suatu tindakan bersifat hermetis jika
semua dependensinya dideklarasikan secara eksplisit.
Jika tindakan ini bergantung pada data dari sumber yang tidak dideklarasikan
sebagai dependensi, tetapkan |
|
materialized
|
boolean
|
Hanya valid jika jenis tabelnya adalah view.
Jika disetel ke benar (true), tampilan terwujud akan dibuat. |
|
onSchemaChange
|
onSchemaChange
|
Hanya valid jika jenis tabelnya adalah incremental.
Tindakan yang dilakukan setelah Dataform memeriksa kueri Fitur ini berada dalam Pratinjau. |
|
preserveGovernanceControls
|
boolean
|
Opsional. Jika disetel ke true, Dataform akan mencadangkan
dan menerapkan kembali kebijakan data BigQuery dan tag tata kelola data (Pratinjau) yang ada saat membuat ulang tabel, tampilan, atau tabel inkremental selama
refresh penuh. Mengganti default tingkat alur kerja yang ditetapkan di
workflow_settings.yaml.
|
|
protected
|
boolean
|
Hanya diizinkan untuk jenis tabel incremental .
Jika ditetapkan ke true, menjalankan tindakan ini akan mengabaikan opsi |
|
schema
|
string
|
| Skema (set data BigQuery) tempat membuat output tindakan ini. | |
tags
|
string[]
|
| Daftar tag yang ditentukan pengguna yang diterapkan pada tindakan ini. | |
type
|
TableType
|
| Jenis tabel. | |
uniqueKey
|
string[]
|
| Kunci unik untuk kriteria penggabungan untuk tabel inkremental.
Jika dikonfigurasi, kumpulan data dengan kunci unik yang cocok akan diperbarui, bukan baris baru yang disisipkan. |
ITableContext
Metode konteks tersedia saat mengevaluasi kode SQL yang dapat dikontekstualisasikan,
seperti dalam file SQLX, atau saat menggunakan argumen Contextable
dengan Dataform core.
incremental
|
() => boolean
|
| Menampilkan nilai benar (true) jika konteks saat ini menunjukkan bahwa tabel akan dibuat secara inkremental. | |
name
|
() => string
|
| Menampilkan nama yang sepenuhnya memenuhi syarat dari tabel ini. | |
ref
|
(ref: Resolvable | string[], rest: string[]) => string
|
| Mereferensikan tindakan lain, menambahkannya sebagai dependensi pada tindakan ini,
menampilkan SQL yang valid untuk digunakan dalam ekspresi from.
Fungsi ini dapat dipanggil dengan objek ${ref({ name: "name", schema: "schema", database: "database" })}
Fungsi ini juga dapat dipanggil menggunakan argumen individual untuk nilai
Jika hanya dua nilai yang diberikan, database default akan digunakan dan nilai
ditafsirkan sebagai Jika hanya satu nilai yang diberikan, skema database default akan digunakan, dengan nilai yang diberikan ditafsirkan sebagai `"name"`. ${ref("database", "schema", "name")}
${ref("schema", "name")}
${ref("name")}
|
|
resolve
|
(ref: Resolvable | string[], rest: string[]) => string
|
Mirip dengan ref, tetapi bukan menambahkan dependensi,
tindakan ini menyelesaikan referensi yang diberikan sehingga dapat digunakan di SQL,
misalnya, dalam ekspresi `from`.
|
|
self
|
() => string
|
Setara dengan resolve(name()).
Menampilkan string SQL yang valid yang dapat digunakan untuk mereferensikan tabel yang dihasilkan oleh tindakan ini. |
|
when
|
(cond: boolean, trueCase: string, falseCase: string) => string
|
Singkatan untuk kondisi if .
Setara dengan cond ? trueCase : falseCase.
|
ITarget
Referensi ke tabel dalam BigQuery.
database
|
string
|
name
|
string
|
schema
|
string
|
ITargetableConfig
Menentukan database target dan skema tindakan alur kerja.
database
|
string
|
|
Database tempat output tindakan ini harus dibuat. Harus disetel ke BigQuery. |
|
schema
|
string
|
|
Skema tempat output tindakan ini harus dibuat. |
onSchemaChange
Setelah Anda menetapkan properti onSchemaChange, Dataform
akan memeriksa kueri SELECT untuk menentukan apakah kolom ditambahkan atau dihapus.
Dataform kemudian melakukan tindakan yang ditentukan oleh nilai properti onSchemaChange. Anda dapat menetapkan tindakan ke salah satu
berikut:
IGNORE(default): mengabaikan kolom yang ditambahkan dan menampilkan error untuk kolom yang tidak ada. JikaonSchemaChangetidak disetel, ini adalah perilaku default saat skema berubah.FAIL: menghentikan tindakan jika Dataform mendeteksi perubahan skema, yang membantu menjaga skema tetap konsisten.EXTEND: menambahkan kolom baru dari kueri ke tabel inkremental, dan menambahkan nilaiNULLuntuk data sebelumnya. Menampilkan error jika kolom dihapus atau tidak ada dari skema asli dalam kueri. Anda dapat menggunakan setelan ini untuk menambahkan kolom baru ke tabel inkremental selama runtime.SYNCHRONIZE: menambahkan kolom baru dari kueri ke tabel inkremental, dan menambahkan nilaiNULLuntuk data sebelumnya. Menghapus kolom yang ada dalam skema asli, tetapi sekarang tidak ada dalam kueri saat ini.
operate()
operate
|
(name: string, queries?: Contextable
|
|
Mendefinisikan operasi SQL. Hanya tersedia di direktori |
Contoh:
// definitions/file.js
operate("an-operation", ["SELECT 1", "SELECT 2"])
publish()
publish
|
(name: string, queryOrConfig?: Contextable
|
|
Membuat tabel atau tampilan. Hanya tersedia di direktori |
Contoh:
// definitions/file.js
publish("published-table", {
type: "table",
dependencies: ["a-declaration"],
}).query(ctx => "SELECT 1 AS test");
Dapat diselesaikan
Resolvable dapat berupa nama tabel sebagai string,
atau objek yang menjelaskan jalur lengkap ke relasi.
string | ITarget
TableType
Jenis tindakan tabel yang didukung.
Tabel jenis view akan dibuat sebagai tampilan.
Tabel berjenis table akan dibuat sebagai tabel.
Tabel jenis incremental harus menyertakan klausa where.
Untuk mengetahui informasi selengkapnya, lihat
Mengonfigurasi tabel inkremental.