Menggunakan Dataform CLI open source

Dokumen ini menunjukkan cara menggunakan antarmuka command line (CLI) Dataform open source untuk mengembangkan alur kerja 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 CLI mendukung Kredensial Default Aplikasi (ADC). Dengan ADC, Anda dapat menyediakan kredensial untuk aplikasi di berbagai lingkungan, seperti produksi atau pengembangan lokal, tanpa perlu mengubah kode aplikasi. Untuk menggunakan ADC, Anda harus memberikan kredensial Anda ke ADC terlebih dahulu.

Catatan: Mulai Dataform core 3.0.0., Dataform tidak mendistribusikan image Docker. Anda dapat membangun image Docker Dataform sendiri, yang dapat digunakan untuk menjalankan perintah yang setara dengan perintah Dataform CLI. Untuk membangun image Docker Anda sendiri, lihat Mengontainerkan aplikasi dalam dokumentasi Docker.

Sebelum memulai

Sebelum menginstal Dataform CLI, instal NPM.

Instal Dataform CLI

• Untuk menginstal Dataform CLI, jalankan perintah berikut:

  npm i -g @dataform/cli
  

Catatan: Versi 3.0.0-beta tidak didukung. Jika npm audit melaporkan kerentanan tingkat tinggi terkait paket vm2, perhatikan bahwa meskipun Dataform menggunakan vm2, Dataform tidak menggunakan vm2 untuk sandbox, yang merupakan sumber kerentanan yang dilaporkan. Versi Dataform CLI yang lebih baru tidak bergantung pada versi vm2 yang rentan.

Melakukan inisialisasi project Dataform

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

  dataform init . YOUR_GOOGLE_CLOUD_PROJECT_ID DEFAULT_LOCATION
  

  Ganti kode berikut:

  • YOUR_GOOGLE_CLOUD_PROJECT_ID: Project ID Google Cloud Anda.
  • DEFAULT_LOCATION: lokasi BigQuery tempat Anda ingin Dataform memproses dan menyimpan data.

Memperbarui inti Dataform

• Untuk mengupdate framework inti Dataform, update dataformCoreVersion dalam file workflow_settings.yaml. Jika dataformCoreVersion ditetapkan di workflow_settings.yaml, Dataform akan menginstal @dataform/core secara otomatis saat runtime. Jika project Anda mengelola @dataform/core dalam file package.json tanpa dataformCoreVersion di workflow_settings.yaml, perbarui versi di package.json dan jalankan:

  dataform install
  

Mengupdate Dataform CLI

• Untuk mengupdate alat Dataform CLI, jalankan perintah berikut:

  npm i -g @dataform/cli@^3.0.50
  

Membuat file kredensial

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

Peringatan:Jika Anda menggunakan sistem kontrol sumber, jangan lakukan commit file .df-credentials.json ke repositori Anda untuk melindungi kredensial akses ini. Sebaiknya tambahkan file .df-credentials.json ke .gitignore.

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 Dataform core 3.0.0 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-database YOUR_GOOGLE_CLOUD_PROJECT_ID --default-location DEFAULT_LOCATION
  

  Ganti kode berikut:

  • PROJECT_NAME: nama direktori project Anda.
  • YOUR_GOOGLE_CLOUD_PROJECT_ID: Google Cloud Project ID Anda.
  • DEFAULT_LOCATION: Lokasi BigQuery tempat Anda ingin Dataform memproses dan menyimpan data.

Meng-clone project

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

• Jika project yang di-clone mendeklarasikan dependensi eksternal dalam file package.json (tanpa dataformCoreVersion di workflow_settings.yaml), jalankan perintah berikut di dalam direktori repositori yang di-clone:

  dataform install
  

Catatan: Project yang menentukan dataformCoreVersion di workflow_settings.yaml menginstal @dataform/core secara otomatis saat runtime dan tidak memerlukan 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.

Jalankan kode

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

• Untuk menjalankan kode project Dataform, 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: variabel kompilasi kustom Anda.
  • SAMPLE_VALUE: nilai variabel kompilasi kustom Anda.

• Untuk menjalankan kode project Dataform Anda di BigQuery dan membangun ulang tabel inkremental (kecuali yang ditandai protected) dari awal, jalankan perintah berikut:

  dataform run --full-refresh
  

Tanpa --full-refresh, Dataform memperbarui tabel inkremental tanpa membangunnya kembali dari awal (tabel dan tampilan reguler selalu dibangun kembali).

• Untuk melakukan uji coba kode Anda terhadap BigQuery, jalankan perintah berikut:

  dataform run --dry-run
  

Catatan: Di Dataform core 3.0.2 atau yang lebih baru, Dataform melakukan uji coba setiap tindakan dalam output kompilasi Anda terhadap BigQuery, dan memerlukan izin IAM yang sesuai. Untuk memverifikasi kompilasi tanpa uji coba, lihat output kompilasi.

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 berikutnya

• Untuk mempelajari perintah dan flag Dataform CLI lebih lanjut, lihat referensi Dataform CLI dan referensi Dataform CLI di GitHub.
• Untuk mempelajari Dataform lebih lanjut, lihat Ringkasan Dataform.