Menyusun kode dalam 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 tahap alur kerja SQL. Anda dapat menggunakan struktur apa pun yang sesuai dengan kebutuhan bisnis Anda.

Anda dapat menyusun kode alur kerja SQL di direktori definitions karena alasan berikut:

  • Meningkatkan kolaborasi pada codebase dengan menetapkan tim ke bagian alur kerja yang dipilih.
  • Meningkatkan kemampuan pemeliharaan alur kerja SQL jika terjadi perubahan organisasi.
  • Meningkatkan navigasi melalui codebase Anda.
  • Meningkatkan skalabilitas codebase.
  • Meminimalkan overhead administratif untuk tim Anda.

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

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

Anda dapat membedakan tiga tahap utama alur kerja SQL:

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

Struktur subdirektori berikut di 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 mengubah data sebelum Anda menggunakan data yang diubah untuk menentukan tabel outputs. Tabel biasanya tidak ditampilkan 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 dan tabel sumber data yang memfilter, mengategorikan, mentransmisikan, atau mengganti nama kolom.

Hindari menyimpan tabel yang menggabungkan data dari beberapa sumber.

Mengubah 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 informasi selengkapnya tentang cara membuat deklarasi sumber data dengan JavaScript, lihat Membuat alur kerja SQL Dataform 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 dari perubahan sumber data, Anda dapat membuat tampilan untuk setiap deklarasi sumber data, misalnya, analytics_users_filtered.sqlx. Tampilan dapat berisi pemfilteran dan pemformatan dasar data sumber. Simpan tampilan di subdirektori sources.

Kemudian, saat Anda membuat tabel intermediate atau outputs, lihat 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 membuat 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 Anda dari data yang ditransformasi.

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

Kelompokkan tabel outputs menurut entitas bisnis yang terkait, misalnya, pemasaran, pesanan, atau analisis. Sediakan subdirektori untuk setiap entitas bisnis.

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

Contoh berikut menunjukkan struktur subdirektori outputs dengan entity bisnis sales dan marketing:

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 di Dataform harus sesuai dengan pedoman penamaan tabel BigQuery.

Sebaiknya nama file di direktori definitions dalam repositori Dataform mencerminkan struktur subdirektori.

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 membedakan file intermediate dengan jelas. Pilih awalan unik, dan terapkan hanya ke file dalam direktori intermediate. Contohnya, stg_ads_concept.sqlx

Di subdirektori outputs, nama file harus ringkas, misalnya orders.sqlx. Jika Anda memiliki tabel outputs dengan nama yang sama di subdirektori entity yang 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