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 Dataform core.

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

Dapat dikontekskan

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"})

IActionConfig

Menentukan tag Dataform dan dependensi yang diterapkan ke tindakan alur kerja.

tags string[]

Daftar tag yang ditentukan pengguna yang harus digunakan untuk memberi 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 tindakan yang rusak untuk sementara.

IAssertionConfig

Opsi konfigurasi untuk jenis tindakan assertion.

database string
Database (ID projectGoogle Cloud ) tempat tampilan yang sesuai untuk pernyataan ini dibuat.
description string
Deskripsi pernyataan ini.
disabled boolean
Jika ditetapkan ke true, tindakan ini tidak akan dijalankan. Tindakan tersebut masih dapat diandalkan. Berguna untuk menonaktifkan sementara tindakan yang rusak.
hermetic boolean
Mendeklarasikan apakah tindakan ini bersifat hermetik. Tindakan bersifat hermetik 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 tampilan yang sesuai untuk pernyataan ini.
tags string[]
Daftar tag yang ditentukan pengguna yang diterapkan pada tindakan ini.

IBigQueryOptions

Opsi warehouse khusus BigQuery.

additionalOptions
Pasangan nilai kunci untuk opsi tabel, tampilan, dan tampilan terwujud.

Beberapa opsi, misalnya, partitionExpirationDays, memiliki kolom jenis/validitas khusus yang diperiksa. Untuk opsi tersebut, gunakan kolom khusus.

Nilai string harus diapit dalam tanda petik 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 untuk mengelompokkan partisi menurut.
labels
Pasangan nilai kunci untuk label BigQuery.

Jika nama label berisi karakter khusus, misalnya, tanda hubung, maka kutip namanya, misalnya, labels: { "label-name": "value" }.
partitionBy string
Kunci yang digunakan 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
Mendeklarasikan apakah tabel berpartisi memerlukan filter predikat klausa WHERE yang memfilter kolom partisi.
updatePartitionFilter string
Filter berbasis SQL untuk waktu update inkremental diterapkan.

IColumnsDescriptor

Menjelaskan kolom dalam tabel.

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

Opsi konfigurasi untuk jenis tindakan declaration.

columns IColumnsDescriptor
Deskripsi kolom dalam tabel.
database string
Database (ID projectGoogle 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 disetel, karena sebagian besar dependensi dideklarasikan sebagai produk sampingan dari penggunaan fungsi ref.
hermetic boolean

Menyatakan apakah tindakan ini bersifat hermetik atau tidak. Tindakan bersifat hermetik 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, tindakan ini harus ditetapkan ke true.

IDocumentableConfig

Mendefinisikan 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 ditetapkan ke true, tindakan ini tidak akan dijalankan. Tindakan tersebut masih dapat diandalkan. Berguna untuk menonaktifkan tindakan yang rusak untuk sementara.
hasOutput boolean
Mendeklarasikan bahwa tindakan operations ini membuat tabel yang dapat dirujuk menggunakan fungsi ref.

Jika disetel 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 hermetik 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
Wajib. Lokasi BigQuery default yang akan digunakan. Untuk mengetahui informasi selengkapnya tentang lokasi BigQuery, lihat https://cloud.google.com/bigquery/docs/locations.
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 (Google Cloud project ID).
schemaSuffix string
Opsional. Sufiks yang harus ditambahkan ke semua nama skema (ID set data BigQuery).
tablePrefix string
Opsional. Awalan yang harus ditambahkan ke semua nama tabel.
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 SQL SELECT 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 mengganti setelan konfigurasi project untuk hasil kompilasi individual, lihat resource REST projects.locations.repositories.compilationResults#CodeCompilationConfig di Dataform API.

IRecordDescriptor

Mendeskripsikan struct, objek, atau rekaman 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 rekaman.
description string
Deskripsi struct, objek, atau rekaman.

ITableAssertions

Opsi untuk membuat pernyataan sebagai bagian dari definisi tabel.

nonNull string | string[]
Kolom yang tidak boleh NULL.

Jika disetel, pernyataan yang sesuai akan gagal jika ada baris yang berisi nilai NULL untuk kolom ini.
rowConditions string[]
Kondisi umum yang harus benar 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 membentuk 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 untuk membuat output tindakan ini.
description string
Deskripsi tabel.
disabled boolean
Jika ditetapkan ke true, tindakan ini tidak akan dijalankan. Tindakan tersebut masih dapat diandalkan. Berguna untuk menonaktifkan tindakan yang rusak untuk sementara.
hermetic boolean
Mendeklarasikan apakah tindakan ini bersifat hermetik. Tindakan bersifat hermetik 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.
protected boolean
Hanya diizinkan untuk jenis tabel incremental .

Jika disetel ke benar (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, data dengan kunci unik yang cocok akan diperbarui, bukan menyisipkan baris baru.

ITableContext

Metode konteks tersedia saat mengevaluasi kode SQL yang dapat dikontekskan, seperti dalam file SQLX, atau saat menggunakan argumen Contextable dengan inti Dataform.

incremental () => boolean
Menampilkan nilai benar (true) jika konteks saat ini menunjukkan bahwa tabel akan dibuat secara inkremental.
name () => string
Menampilkan nama tabel ini yang sepenuhnya memenuhi syarat.
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, API ini menyelesaikan referensi yang diberikan sehingga dapat digunakan dalam 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 dan skema target 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.

operate()

operate (name: string, queries?: Contextable)

Menentukan 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 berjenis 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.