Membuat struktur kode di repositori

Dokumen ini menjelaskan praktik terbaik untuk menyusun dan memberi nama file alur kerja SQL di direktori definitions root repositori Dataform. Struktur direktori definitions yang direkomendasikan mencerminkan tahapan alur kerja SQL. Anda dapat menggunakan struktur apa pun yang sesuai dengan kebutuhan bisnis Anda.

Anda mungkin ingin menyusun kode alur kerja SQL dalam direktori definitions karena alasan berikut:

  • Meningkatkan kolaborasi pada codebase dengan menunjuk tim ke bagian tertentu dalam alur kerja Anda.
  • Meningkatkan pemeliharaan alur kerja SQL jika terjadi perubahan organisasi.
  • Meningkatkan navigasi melalui codebase Anda.
  • Meningkatkan skalabilitas codebase.
  • Meminimalkan {i>overhead<i} administratif untuk tim Anda.

Direktori definitions root dalam repositori Dataform berisi kode yang membuat elemen alur kerja SQL Anda. Anda dapat menyusun file di direktori definitions menjadi struktur direktori yang mencerminkan struktur alur kerja.

Saat mengembangkan alur kerja SQL, Anda mendeklarasikan tabel sumber dan mengubahnya untuk membuat tabel output yang dapat digunakan untuk tujuan bisnis atau analisis.

Anda dapat membedakan tiga tahap utama dari alur kerja SQL:

  1. Deklarasi sumber data
  2. Transformasi data sumber
  3. Definisi tabel output dari data sumber yang ditransformasi

Struktur subdirektori berikut dalam direktori definitions mencerminkan tahapan utama alur kerja SQL:

sources
Deklarasi sumber data dan transformasi dasar data sumber, misalnya pemfilteran.
intermediate
Tabel dan tindakan yang membaca dari sources dan mentransformasikan data sebelum Anda menggunakan data yang ditransformasi untuk menentukan tabel outputs. Tabel biasanya tidak terekspos ke proses atau alat tambahan, seperti alat business intelligence (BI), setelah Dataform mengeksekusinya ke BigQuery.
outputs
Definisi tabel yang digunakan oleh proses atau alat, seperti BI, setelah Dataform mengeksekusinya di BigQuery.
extra
File di luar pipeline utama alur kerja SQL Anda, misalnya, file yang berisi data alur kerja yang disiapkan untuk penggunaan tambahan, seperti machine learning. Subdirektori opsional dan kustom.

Praktik terbaik untuk sources

Subdirektori sources berisi tahap pertama alur kerja SQL Anda: deklarasi dan transformasi dasar data sumber.

Di subdirektori sources, simpan deklarasi sumber data dan tabel yang memfilter, mengategorikan, mentransmisikan, atau mengganti nama kolom.

Hindari menyimpan tabel yang menggabungkan data dari beberapa sumber.

Transformasikan data sources dalam tabel yang disimpan di subdirektori intermediate.

Jika Anda mendeklarasikan sumber data dari beberapa kumpulan, misalnya, Google Ads atau Google Analytics, dedikasikan subdirektori untuk setiap kumpulan.

Contoh berikut menunjukkan struktur subdirektori sources dengan dua kumpulan sumber:

definitions/
    sources/
        google_ads/
            google_ads_filtered.sqlx
            google_ads_criteria_metrics.sqlx
            google_ads_criteria_metrics_filtered.sqlx
            google_ads_labels.sqlx
            google_ads_labels_filtered.sqlx
        google_analytics/
            google_analytics_users.sqlx
            google_analytics_users_filtered.sqlx
            google_analytics_sessions.sqlx

Jika mendeklarasikan beberapa tabel sumber data dalam skema yang sama, Anda dapat menggabungkan deklarasinya ke dalam satu file JavaScript. Dalam file JavaScript, Anda dapat menyimpan beberapa deklarasi sumber data. Untuk mengetahui informasi selengkapnya tentang cara membuat deklarasi sumber data dengan JavaScript, lihat Membuat alur kerja Dataform SQL dengan JavaScript.

Contoh kode berikut menunjukkan beberapa sumber data dalam satu skema, yang dideklarasikan dalam satu file JavaScript:

[
  "source_table_1",
  "source_table_2",
  "source_table_3"
].forEach((name) =>
  declare({
    database: "gcp_project",
    schema: "source_dataset",
    name,
  })
);

Untuk melindungi alur kerja SQL Anda dari perubahan sumber data, Anda dapat membuat tampilan untuk setiap deklarasi sumber data, misalnya, analytics_users_filtered.sqlx. Tampilan dapat berisi pemfilteran dasar dan pemformatan data sumber. Simpan tampilan di subdirektori sources.

Kemudian, saat Anda membuat tabel intermediate atau outputs, rujuk tampilan, bukan tabel sumber mentah. Pendekatan ini memungkinkan Anda menguji tabel sumber. Jika tabel sumber berubah, Anda dapat mengubah tampilannya, misalnya, dengan menambahkan filter atau melakukan transmisi ulang data.

Praktik terbaik untuk intermediate

Subdirektori intermediate berisi tahap kedua alur kerja SQL Anda: transformasi dan agregasi data sumber dari satu atau beberapa sumber.

Di subdirektori intermediate, simpan file yang secara signifikan mengubah data sumber dari satu atau beberapa sumber di subdirektori sources, misalnya, tabel yang menggabungkan data. Tabel di subdirektori intermediate biasanya membuat kueri data dari tabel sumber atau tabel intermediate lainnya.

Gunakan tabel intermediate untuk membuat tabel outputs. Biasanya, tabel intermediate tidak digunakan untuk tujuan tambahan, misalnya analisis data, setelah Dataform mengeksekusinya ke BigQuery. Anda dapat menganggap tabel intermediate sebagai logika transformasi data yang memungkinkan pembuatan tabel output.

Sebaiknya dokumentasikan dan uji semua tabel intermediate.

Praktik terbaik untuk outputs

Subdirektori outputs berisi tahap akhir alur kerja SQL Anda: pembuatan tabel output untuk tujuan bisnis dari data yang ditransformasi.

Dalam direktori outputs, simpan tabel yang ingin Anda gunakan dalam proses atau alat tambahan setelah Dataform mengeksekusinya ke BigQuery, misalnya, laporan atau dasbor. Tabel di direktori outputs biasanya mengkueri data dari tabel intermediate.

Mengelompokkan tabel outputs berdasarkan entity bisnis yang terkait dengannya, misalnya, pemasaran, pesanan, atau analisis. Dedikasikan subdirektori untuk setiap entitas bisnis.

Untuk menyimpan tabel output secara terpisah di BigQuery, Anda dapat mengonfigurasi skema khusus untuk tabel output. Untuk mendapatkan petunjuk tentang cara mengonfigurasi skema tabel, lihat Mengonfigurasi setelan tabel tambahan.

Contoh berikut menunjukkan struktur subdirektori outputs dengan dua entity bisnis:

definitions/
    outputs/
        orders/
            orders.sqlx
            returns.sqlx
        sales/
            sales.sqlx
            revenue.sqlx
        marketing/
            campaigns.sqlx

Sebaiknya dokumentasikan dan uji semua tabel outputs.

Strategi penamaan

Nama semua file dalam Dataform harus mematuhi panduan penamaan tabel BigQuery.

Sebaiknya nama file dalam direktori definitions dalam repositori Dataform mencerminkan struktur subdirektorinya.

Di subdirektori sources, nama file harus mengarah ke sumber yang terkait dengan file tersebut. Tambahkan nama sumber sebagai awalan ke nama file, misalnya analytics_filtered.sqlx

Di subdirektori intermediate, nama file harus mengidentifikasi subdirektori, sehingga kolaborator dapat dengan jelas membedakan file intermediate. Pilih awalan yang unik, dan terapkan hanya ke file dalam direktori intermediate. Contohnya, stg_ads_concept.sqlx

Dalam subdirektori outputs, nama file harus ringkas, misalnya orders.sqlx. Jika Anda memiliki tabel outputs dengan nama yang sama di subdirektori entity berbeda, tambahkan awalan yang mengidentifikasi entity, misalnya, sales_revenue.sqlx dan ads_revenue.sqlx.

Contoh berikut menunjukkan struktur subdirektori di dalam direktori definitions dengan nama file yang sesuai dengan strategi penamaan yang direkomendasikan:

definitions/
    sources/
        google_analytics.sqlx
        google_analytics_filtered.sqlx
    intermediate/
        stg_analytics_concept.sqlx
    outputs/
        customers.sqlx
        sales/
            sales.sqlx
            sales_revenue.sqlx
        ads/
            campaigns.sqlx
            ads_revenue.sqlx

Langkah selanjutnya