Referensi inti Dataform

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 /definitions.

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 Resolvable, misalnya: ${ref({ name: "name", schema: "schema", database: "database" })}

Fungsi ini juga dapat dipanggil menggunakan argumen individual untuk nilai "database", "schema", dan "name". Jika hanya dua nilai yang diberikan, database default akan digunakan dan nilai ditafsirkan sebagai "schema" dan "name". Jika hanya satu nilai yang diberikan, database dan skema 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
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 /definitions.

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 properti defaultLocation. Atau, gunakan variabel sistem @@location dalam 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 hermetic ke false. Jika tidak, tetapkan ke true.

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, partitionExpirationDays, memiliki kolom khusus yang diperiksa jenis/validitasnya. Untuk opsi tersebut, gunakan kolom khusus.

Nilai string harus diapit dalam tanda kutip ganda, misalnya: additionalOptions: {numeric_option: "5", string_option: '"string-value"'}

Jika nama opsi berisi karakter khusus, sertakan nama dalam tanda kutip, misalnya: additionalOptions: { "option-name": "value" }.

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, labels: { "label-name": "value" }.

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:

  • PROJECT_ID.LOCATION.CONNECTION_ID

    Ganti nilai berikut:
    • PROJECT_ID: Google Cloud project ID
    • LOCATION: nama lokasi koneksi
    • CONNECTION_ID: nama atau ID koneksi
  • projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID
  • DEFAULT

Nilai defaultnya adalah DEFAULT. Untuk mengetahui informasi selengkapnya, lihat Ringkasan koneksi default.

file_format string

Opsional. Format file untuk data tabel.

Hanya PARQUET yang didukung. Nilai defaultnya adalah PARQUET.

bucket_name string

Wajib di tingkat tabel atau alur kerja. Nama bucket Cloud Storage tempat data tabel disimpan.

Anda harus memberikan bucket_name di blok config pada file definisi tabel, atau menetapkan default tingkat alur kerja di file workflow_settings.yaml. Jika keduanya tidak diberikan, kompilasi akan gagal. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi default tingkat alur kerja untuk tabel Iceberg .

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 workflow_settings.yaml jika ditetapkan. Jika tidak, nilai defaultnya adalah _dataform.

table_folder_subpath string

Opsional. Subfolder dalam tableFolderRoot.

Jika Anda tidak menetapkan properti ini, Dataform akan menggunakan default tingkat alur kerja dari workflow_settings.yaml jika sudah ditetapkan. Jika properti maupun default tingkat alur kerja tidak ditetapkan, subjalur akan ditetapkan secara default ke DATASET_NAME/TABLE_NAME.

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 ref.

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 hermetic harus ditetapkan secara eksplisit ke false. Jika tidak, jika tindakan ini hanya bergantung pada data dari dependensi yang dideklarasikan secara eksplisit, maka tindakan ini harus ditetapkan ke true.

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 true, tindakan ini akan membuat tabel dengan nama yang dikonfigurasi, menggunakan fungsi konteks self().

Contoh: 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 hermetic ke false. Jika tidak, setel ke true.

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:
  • bucketName: Opsional. Nama default untuk bucket Cloud Storage.
  • tableFolderRoot: Opsional. Nama default untuk folder tingkat pertama di dalam bucket Cloud Storage.
  • tableFolderSubpath: Opsional. Nama default untuk subfolder dalam tableFolderRoot.
Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi default tingkat alur kerja untuk tabel Iceberg.
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: "projects/1/locations/eu/taxonomies/2/policyTags/3"

BigQuery mendukung satu tag per kolom.
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 NULL untuk kolom ini.

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 hermetic ke false. Jika tidak, setel ke true.

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 SELECT untuk menentukan apakah kolom ditambahkan atau dihapus.

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 full-refresh. Hal ini berguna untuk tabel yang dibuat dari data sementara, untuk memverifikasi bahwa data historis tidak pernah hilang.

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 Resolvable, misalnya:

${ref({ name: "name", schema: "schema", database: "database" })}

Fungsi ini juga dapat dipanggil menggunakan argumen individual untuk nilai "database", "schema", dan "name".

Jika hanya dua nilai yang diberikan, database default akan digunakan dan nilai ditafsirkan sebagai "schema" dan "name".

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.

falseCase bersifat opsional, dan defaultnya adalah string kosong.

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. Jika onSchemaChange tidak 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 nilai NULL untuk 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 nilai NULL untuk 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 /definitions.

Contoh:

// definitions/file.js

operate("an-operation", ["SELECT 1", "SELECT 2"])

publish()

publish (name: string, queryOrConfig?: Contextable | ITableConfig)

Membuat tabel atau tampilan.

Hanya tersedia di direktori /definitions.

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.