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, kompilasi, pengujian, dan menjalankan inti Dataform secara lokal, di luar Google Cloud.

Dataform CLI 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 terlebih dahulu memberikan kredensial ke ADC.

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

Melakukan inisialisasi project Dataform

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

    dataform init . PROJECT_NAME DEFAULT_LOCATION

    Ganti kode berikut:

    • PROJECT_NAME: nama project Anda.
    • DEFAULT_LOCATION: region tempat Anda ingin Dataform menulis data BigQuery. Untuk mengetahui informasi selengkapnya tentang region BigQuery, lihat Lokasi BigQuery.

Memperbarui inti Dataform

  • Untuk mengupdate framework inti Dataform, perbarui dataformCoreVersion dalam file workflow_settings.yaml, lalu jalankan kembali penginstalan NPM:

    npm i

Mengupdate Dataform CLI

  • Untuk mengupdate alat CLI Dataform, jalankan perintah berikut:

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

Membuat file kredensial

Dataform memerlukan file kredensial untuk 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 memandu Anda dalam pembuatan file kredensial.

Membuat project

Project Dataform kosong di 3.0.0-beta.0 core Dataform atau yang lebih baru 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 kode berikut:

    • PROJECT_NAME: nama project Anda.
    • YOUR_GOOGLE_CLOUD_PROJECT_ID: 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

Menentukan 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: jenis tabel: table, incremental, atau view.
    • SELECT_STATEMENT: pernyataan SELECT yang menentukan tabel.
    • FILE: 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: pernyataan SELECT yang menentukan pernyataan.
    • FILE: 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: operasi SQL kustom Anda.
    • FILE: 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: variabel kompilasi kustom Anda.
    • SAMPLE_VALUE: nilai variabel kompilasi kustom Anda.

Menjalankan kode

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

  • Untuk mengeksekusi kode project Dataform, jalankan perintah berikut:

    dataform run

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

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

    Ganti kode berikut:

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

  • Untuk mengeksekusi kode project Dataform 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 membangun ulang dari awal.

  • Untuk melihat kode SQL akhir yang dikompilasi dan disesuaikan dengan status BigQuery saat ini, tanpa menjalankannya 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