Menggunakan Dataform CLI open source

Dokumen ini menunjukkan cara menggunakan antarmuka command line (CLI) Dataform open source untuk mengembangkan alur kerja SQL secara lokal menggunakan terminal.

Dengan Dataform CLI open source, Anda dapat melakukan inisialisasi, mengompilasi, menguji, dan menjalankan Dataform core secara lokal, di luar Google Cloud.

Dataform mendistribusikan image Docker yang dapat Anda gunakan untuk menjalankan perintah CLI Dataform yang setara.

CLI Dataform mendukung Kredensial Default Aplikasi (ADC). Dengan ADC, Anda dapat menyediakan kredensial untuk aplikasi di berbagai lingkungan, seperti pengembangan atau produksi lokal, tanpa perlu mengubah kode aplikasi. Untuk menggunakan ADC, Anda harus memberikan kredensial ke ADC terlebih dahulu.

Sebelum memulai

Sebelum menginstal Dataform CLI, instal NPM.

Menginstal Dataform CLI

  • Untuk menginstal Dataform CLI, jalankan perintah berikut:

    npm i -g @dataform/cli@^3.0.0-beta.2

Menginisialisasi project Dataform

  • Untuk menginisialisasi project Dataform baru, jalankan perintah berikut di dalam direktori project Anda:

    dataform init

Perbarui Formulir Data

  • Untuk mengupdate framework Dataform, update dataformCoreVersion di file workflow_settings.yaml, lalu jalankan kembali penginstalan NPM:

    npm i

Mengupdate CLI Dataform

  • Untuk mengupdate alat Dataform CLI, jalankan perintah berikut:

    npm i -g @dataform/cli@^3.0.0-beta.2

Membuat file kredensial

Dataform memerlukan file kredensial agar dapat terhubung ke layanan jarak jauh dan membuat file .df-credentials.json di disk Anda.

Untuk membuat file kredensial, ikuti langkah-langkah berikut:

  1. Jalankan perintah berikut:

    dataform init-creds

  2. Ikuti wizard init-creds yang akan memandu Anda melalui pembuatan file kredensial.

Membuat project

Project Dataform kosong memiliki struktur berikut:

   project-dir
   ├── definitions
   ├── includes
   └── workflow_settings.yaml

  • Untuk membuat project Dataform guna men-deploy aset ke BigQuery, jalankan perintah berikut:

    dataform init PROJECT_NAME --default-project YOUR_GOOGLE_CLOUD_PROJECT_ID

    Ganti PROJECT_NAME dengan nama project Anda dan YOUR_GOOGLE_CLOUD_PROJECT_ID dengan project ID Google Cloud Anda.

Meng-clone project

Untuk meng-clone project Dataform yang ada dari repositori Git pihak ketiga, ikuti petunjuk dari penyedia Git Anda.

  • Setelah repositori di-clone, jalankan perintah berikut di dalam direktori repositori yang di-clone:

    dataform install

Tentukan tabel

Simpan definisi di folder definitions/.

  • Untuk menentukan tabel, jalankan perintah berikut:

    echo "config { type: 'TABLE_TYPE' } SELECT_STATEMENT" > definitions/FILE.sqlx

    Ganti kode berikut:

    • TABLE_TYPE dengan jenis tabel: table, incremental, atau view.
    • SELECT_STATEMENT dengan pernyataan SELECT yang menentukan tabel.
    • FILE dengan nama untuk file definisi tabel.

Contoh kode berikut menentukan tampilan dalam file SQLX example.

echo "config { type: 'view' } SELECT 1 AS test" > definitions/example.sqlx

Menentukan pernyataan manual

Simpan definisi di folder definitions/.

  • Untuk menentukan pernyataan manual, jalankan perintah berikut:

    echo "config { type: 'assertion' } SELECT_STATEMENT" > definitions/FILE.sqlx

    Ganti kode berikut:

    • SELECT_STATEMENT dengan pernyataan SELECT yang menentukan pernyataan.
    • FILE dengan nama untuk file definisi operasi SQL kustom.

Menentukan operasi SQL kustom

Simpan definisi di folder definitions/.

  • Untuk menentukan operasi SQL kustom, jalankan perintah berikut:

    echo "config { type: 'operations' } SQL_QUERY" > definitions/FILE.sqlx

    Ganti kode berikut:

    • SQL_QUERY dengan operasi SQL kustom Anda.
    • FILE dengan nama untuk file definisi operasi SQL kustom.

Melihat output kompilasi

Dataform mengompilasi kode Anda secara real time.

  • Untuk melihat output proses kompilasi di terminal, jalankan perintah berikut:

    dataform compile

  • Untuk melihat output proses kompilasi sebagai objek JSON, jalankan perintah berikut:

    dataform compile --json

  • Untuk melihat output kompilasi dengan variabel kompilasi kustom, jalankan perintah berikut:

    dataform compile --vars=SAMPLE_VAR=SAMPLE_VALUE,foo=bar

    Ganti kode berikut:

    • SAMPLE_VAR dengan variabel kompilasi kustom Anda.
    • SAMPLE_VALUE dengan nilai variabel kompilasi kustom.

Menjalankan kode

Untuk menjalankan kode Anda, Dataform mengakses BigQuery untuk menentukan statusnya saat ini dan menyesuaikan SQL yang dihasilkan.

  • Untuk menjalankan kode project Dataform Anda, jalankan perintah berikut:

    dataform run

  • Untuk menjalankan kode project Dataform Anda di BigQuery dengan variabel kompilasi kustom, jalankan perintah berikut:

    dataform run --vars=SAMPLE_VAR=SAMPLE_VALUE,sampleVar2=sampleValue2

    Ganti kode berikut:

    • SAMPLE_VAR dengan variabel kompilasi kustom Anda.
    • SAMPLE_VALUE dengan nilai variabel kompilasi kustom.

  • Untuk menjalankan kode project Dataform Anda di BigQuery dan mem-build ulang semua tabel dari awal, jalankan perintah berikut:

    dataform run --full-refresh

Tanpa --full-refresh, Dataform akan memperbarui tabel inkremental tanpa mem-build ulang tabel tersebut dari awal.

  • Untuk melihat kode SQL terkompilasi akhir yang disesuaikan dengan status BigQuery saat ini, tanpa mengeksekusinya di dalam BigQuery, jalankan perintah berikut:

    dataform run --dry-run

Dapatkan bantuan

  • Untuk menampilkan semua perintah dan opsi yang tersedia, jalankan perintah berikut:

    dataform help

  • Untuk melihat deskripsi perintah tertentu, jalankan perintah berikut:

    dataform help COMMAND

    Ganti COMMAND dengan perintah yang ingin Anda pelajari.

Langkah selanjutnya