Praktik terbaik untuk repositori

Dokumen ini menyajikan informasi berikut tentang repositori Dataform:

Ringkasan praktik terbaik repositori di Dataform

Bagian ini menyajikan ringkasan praktik terbaik untuk mengelola ukuran repositori, struktur repositori, dan siklus proses kode di Dataform.

Praktik terbaik untuk ukuran repositori

Ukuran repositori memengaruhi beberapa aspek pengembangan di Dataform, seperti berikut:

  • Kolaborasi
  • Keterbacaan codebase
  • Proses pengembangan
  • Kompilasi alur kerja
  • Eksekusi alur kerja

Dataform memberlakukan kuota dan batas API pada resource kompilasi. Ukuran repositori yang besar dapat menyebabkan repositori Anda melampaui kuota dan batas ini. Hal ini dapat menyebabkan kompilasi dan eksekusi alur kerja Anda gagal.

Untuk mengurangi risiko tersebut, sebaiknya pisahkan repositori besar. Saat memisahkan repositori besar, Anda membagi alur kerja besar menjadi sejumlah alur kerja yang lebih kecil yang ditempatkan di repositori berbeda dan dihubungkan oleh dependensi lintas repositori.

Dengan pendekatan ini, Anda dapat mematuhi kuota dan batas Dataform, menerapkan proses dan izin yang terperinci, serta meningkatkan keterbacaan dan kolaborasi codebase. Namun, mengelola repositori terpisah bisa lebih sulit daripada mengelola satu repositori.

Untuk mempelajari lebih lanjut dampak ukuran repositori di Dataform, lihat Ringkasan ukuran repositori. Untuk mempelajari lebih lanjut praktik terbaik dalam memisahkan repositori, lihat Memisahkan repositori.

Praktik terbaik untuk struktur repositori

Sebaiknya susun file di direktori definitions untuk mencerminkan tahapan alur kerja Anda. Perlu diingat bahwa Anda dapat menerapkan struktur kustom yang paling sesuai dengan kebutuhan Anda.

Struktur subdirektori definitions yang direkomendasikan berikut mencerminkan tahapan utama sebagian besar alur kerja:

  • sources untuk menyimpan deklarasi sumber data.
  • intermediate untuk menyimpan logika transformasi data.
  • output untuk menyimpan definisi tabel output.
  • extras (opsional) untuk menyimpan file tambahan.

Nama semua file di Dataform harus sesuai dengan pedoman penamaan tabel BigQuery. Sebaiknya nama file di direktori definitions dalam repositori Dataform mencerminkan struktur subdirektori.

Untuk mempelajari lebih lanjut praktik terbaik dalam menyusun dan memberi nama file di repositori, lihat Menyusun kode dalam repositori.

Praktik terbaik untuk siklus proses kode

Siklus proses kode default di Dataform terdiri dari fase berikut:

Untuk mengelola siklus proses kode di Dataform, Anda dapat membuat lingkungan eksekusi seperti pengembangan, staging, dan produksi.

Untuk mempelajari lebih lanjut siklus proses kode di Dataform, lihat Pengantar siklus proses kode di Dataform.

Anda dapat memilih untuk menyimpan lingkungan eksekusi di satu repositori, atau di beberapa repositori.

Lingkungan eksekusi dalam satu repositori

Anda dapat membuat lingkungan eksekusi terpisah seperti pengembangan, penyiapan, dan produksi dalam satu repositori Dataform dengan penggantian kompilasi ruang kerja dan konfigurasi rilis.

Anda dapat membuat lingkungan eksekusi terisolasi dengan cara berikut:

  • Membagi tabel pengembangan dan produksi menurut skema.
  • Membagi tabel pengembangan dan produksi menurut skema dan Google Cloud project.
  • Membagi tabel pengembangan, staging, dan produksi menurut Google Cloud project.

Kemudian, Anda dapat menjadwalkan eksekusi di lingkungan staging dan produksi dengan konfigurasi alur kerja. Sebaiknya picu eksekusi secara manual di lingkungan pengembangan.

Untuk mempelajari lebih lanjut praktik terbaik dalam mengelola siklus proses alur kerja di Dataform, lihat Praktik terbaik untuk siklus proses alur kerja.

Siklus proses kode di beberapa repositori

Untuk menyesuaikan izin Identity and Access Management di setiap tahap siklus proses kode, Anda dapat membuat beberapa salinan repositori dan menyimpannya di project Google Cloud yang berbeda.

Setiap Google Cloud project berfungsi sebagai lingkungan eksekusi yang sesuai dengan tahap siklus proses kode Anda—misalnya, pengembangan dan produksi.

Dalam pendekatan ini, sebaiknya pertahankan codebase repositori yang sama di semua project. Untuk menyesuaikan kompilasi dan eksekusi di setiap salinan repositori, gunakan penggantian kompilasi ruang kerja, konfigurasi rilis, dan konfigurasi alur kerja.

Ringkasan ukuran repositori

Bagian ini membantu Anda memahami pengaruh ukuran repositori terhadap pengembangan alur kerja dan penggunaan resource kompilasi Dataform, serta cara memperkirakan penggunaan resource kompilasi repositori Anda.

Tentang ukuran repositori di Dataform

Ukuran repositori memengaruhi aspek pengembangan berikut di Dataform:

  • Kolaborasi. Beberapa kolaborator yang mengerjakan repositori besar dapat membuat terlalu banyak permintaan pull, sehingga meningkatkan risiko konflik penggabungan.

  • Keterbacaan codebase. Jumlah file yang lebih besar yang membentuk alur kerja dalam satu repositori dapat mempersulit penjelajahan repositori.

  • Proses pengembangan. Beberapa area alur kerja besar dalam satu repositori mungkin memerlukan izin atau proses kustom, seperti penjadwalan, yang berbeda dari izin dan proses yang diterapkan ke alur kerja lainnya. Ukuran repositori yang besar menyulitkan penyesuaian proses pengembangan ke area alur kerja tertentu.

  • Kompilasi alur kerja. Dataform menerapkan batas penggunaan pada resource kompilasi. Ukuran repositori yang besar dapat menyebabkan batas ini terlampaui, sehingga kompilasi gagal.

  • Eksekusi alur kerja. Selama eksekusi, Dataform menjalankan kode repositori di dalam ruang kerja Anda dan men-deploy aset ke BigQuery. Makin besar repositori, makin banyak waktu yang dibutuhkan Dataform untuk menjalankannya.

Jika ukuran repositori yang besar berdampak negatif pada pengembangan Anda di Dataform, Anda dapat membagi repositori menjadi beberapa repositori yang lebih kecil.

Tentang batas resource kompilasi repositori

Selama pengembangan, Dataform mengompilasi semua kode repositori di dalam ruang kerja Anda untuk menghasilkan representasi alur kerja di repositori Anda. Hal ini disebut hasil kompilasi. Dataform menerapkan batas penggunaan pada resource kompilasi.

Repositori Anda mungkin melebihi batas penggunaan karena alasan berikut:

  • Bug loop tak terbatas dalam kode repositori.
  • Bug kebocoran memori dalam kode repositori.
  • Ukuran repositori yang besar, kira-kira lebih dari 1.000 tindakan alur kerja.

Untuk mengetahui informasi selengkapnya tentang batas penggunaan pada resource kompilasi, lihat Batas resource kompilasi Dataform.

Memperkirakan penggunaan resource kompilasi repositori Anda

Anda dapat memperkirakan penggunaan resource kompilasi berikut untuk repositori Anda:

  • Penggunaan waktu CPU.
  • Ukuran total maksimum data berseri dari grafik tindakan yang dihasilkan yang ditentukan di repositori Anda.

Untuk mendapatkan perkiraan kasar penggunaan waktu CPU kompilasi saat ini untuk kompilasi repositori Anda, Anda dapat mengukur waktu kompilasi alur kerja Dataform di komputer Linux atau macOS lokal.

  • Untuk mengukur waktu kompilasi alur kerja, di dalam repositori, jalankan perintah Dataform CLI dataform compile dalam format berikut:

    time dataform compile

    Contoh kode berikut menunjukkan hasil eksekusi perintah time dataform compile:

    real    0m3.480s
user    0m1.828s
sys     0m0.260s

Anda dapat memperlakukan hasil real sebagai indikator kasar penggunaan waktu CPU untuk kompilasi repositori Anda.

Untuk mendapatkan perkiraan kasar ukuran total grafik tindakan yang dihasilkan di repositori Anda, Anda dapat menulis output grafik ke file JSON. Anda dapat memperlakukan ukuran file JSON yang tidak dikompresi sebagai indikator kasar dari total ukuran grafik.

  • Untuk menulis output grafik alur kerja yang dikompilasi ke file JSON, di dalam repositori Anda, jalankan perintah Dataform CLI berikut:

    dataform compile --json > graph.json

Memisahkan repositori

Bagian ini membahas strategi untuk memisahkan repositori Dataform dan mengelola dependensi lintas repositori.

Repositori adalah unit inti di Dataform. Repositori menyimpan semua file SQLX dan JavaScript yang membentuk alur kerja Anda, serta file dan paket konfigurasi Dataform. Anda dapat menyimpan alur kerja dalam satu repositori, atau membagi alur kerja di antara beberapa repositori.

Memisahkan repositori di Dataform memberikan keuntungan berikut:

  • Mematuhi batas Dataform terkait penggunaan resource kompilasi. Membagi alur kerja besar menjadi beberapa repositori yang lebih kecil akan mengurangi risiko melampaui batas Dataform pada resource kompilasi.
  • Proses yang lebih mendetail. Anda dapat menetapkan proses, seperti aturan integrasi berkelanjutan (CI), satu per satu untuk setiap fragmen pemisahan alur kerja dan tim yang mengembangkannya.
  • Izin terperinci. Anda dapat menetapkan izin satu per satu untuk setiap fragmen alur kerja dan tim yang mengembangkannya untuk meningkatkan keamanan alur kerja secara keseluruhan.
  • Meningkatkan kolaborasi dengan meminimalkan jumlah kolaborator yang mengerjakan setiap fragmen terpisah dari alur kerja Anda.
  • Meningkatkan keterbacaan codebase. Membagi file yang membentuk alur kerja besar menjadi beberapa repositori akan memudahkan navigasi setiap repositori satu per satu daripada menavigasi seluruh alur kerja sekaligus.
  • Mempercepat eksekusi alur kerja setiap fragmen terpisah dari alur kerja Anda dibandingkan dengan eksekusi seluruh alur kerja.

Memisahkan repositori di Dataform memiliki kekurangan berikut:

  • Konfigurasi continuous integration dan continuous development (CI/CD) kustom diperlukan untuk setiap repositori Dataform dan repositori Git yang sesuai.
  • Konfigurasi penjadwalan kustom diperlukan untuk setiap repositori Dataform dan repositori Git yang sesuai.
  • Kesulitan dalam mengelola dependensi antara objek alur kerja yang disimpan di beberapa repositori.
  • Kurangnya visualisasi directed acyclic graph (DAG) yang komprehensif dari alur kerja SQL yang dibagi di antara beberapa repositori. Di setiap repositori, DAG yang dihasilkan hanya merepresentasikan sebagian alur kerja yang lengkap.

Strategi untuk memisahkan repositori

Saat memisahkan repositori, Anda membagi file yang membentuk alur kerja SQL induk menjadi alur kerja turunan yang lebih kecil dan ditempatkan di repositori Dataform terpisah.

Anda dapat memilih untuk memisahkan repositori dengan salah satu cara berikut:

  • Satu repositori per tim pengembangan.
  • Satu repositori per domain—misalnya, penjualan, pemasaran, atau logistik.
  • Satu repositori pusat dan satu repositori per domain yang menggunakan konten repositori pusat sebagai sumber data.

Untuk menampung alur kerja induk di platform hosting Git pihak ketiga, Anda harus menghubungkan setiap repositori terpisah yang berisi alur kerja turunan ke repositori Git pihak ketiga khusus secara terpisah.

Mengelola dependensi lintas repositori

Cara paling efisien untuk memisahkan repositori adalah dengan membagi alur kerja SQL induk menjadi alur kerja turunan yang mandiri, sehingga membuat repositori independen. Repositori independen tidak menggunakan konten repositori lain sebagai sumber data. Pendekatan ini tidak memerlukan pengelolaan dependensi lintas repositori.

Jika Anda tidak dapat menghindari dependensi lintas repositori, Anda dapat mengelolanya dengan membagi repositori menjadi serangkaian repositori, yang mana repositori bergantung pada pendahulunya dan merupakan sumber data bagi penerusnya. Urutan repositori dan dependensinya harus mencerminkan struktur alur kerja induk Anda dengan sebaik-baiknya.

Anda dapat membuat dependensi antar-repositori dengan deklarasi sumber data Dataform. Anda dapat mendeklarasikan jenis tabel BigQuery dari repositori Dataform yang berbeda sebagai sumber data di repositori yang sedang diedit. Setelah mendeklarasikan sumber data, Anda dapat mereferensikannya seperti tindakan alur kerja Dataform lainnya dan menggunakannya untuk mengembangkan alur kerja Anda.

Saat menjadwalkan eksekusi alur kerja yang dibagi di antara repositori dengan dependensi lintas repositori, Anda harus menjalankan repositori satu per satu dalam urutan dependensi lintas repositori.

Sebaiknya hindari memisahkan repositori menjadi sekelompok repositori dengan dependensi dua arah. Dependensi dua arah antara repositori terjadi saat repositori menjadi sumber data untuk repositori lain dan juga menggunakan repositori tersebut sebagai sumber data. Dependensi dua arah antara repositori mempersulit penjadwalan dan eksekusi alur kerja induk, serta proses pengembangan.

Menyusun kode dalam repositori

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

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

  • Meningkatkan kolaborasi pada codebase dengan menunjuk tim untuk bagian alur kerja yang dipilih.
  • Meningkatkan kemudahan pemeliharaan alur kerja jika terjadi perubahan organisasi.
  • Meningkatkan kualitas 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 Anda. Anda dapat mengatur file di direktori definitions ke dalam struktur direktori yang mencerminkan struktur alur kerja.

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

Anda dapat membedakan tiga tahap utama alur kerja:

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

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

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 diekspos ke proses atau alat tambahan, seperti alat business intelligence (BI), setelah Dataform menjalankannya ke BigQuery.
outputs
Definisi tabel yang digunakan oleh proses atau alat, seperti BI, setelah Dataform menjalankannya di BigQuery.
extra
File di luar pipeline utama alur kerja Anda—misalnya, file yang berisi data alur kerja yang disiapkan untuk penggunaan tambahan, seperti machine learning. Subdirektori kustom dan opsional.

Praktik terbaik untuk sources

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

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

Hindari menyimpan tabel yang menggabungkan data dari beberapa sumber.

Ubah data sources dalam tabel yang disimpan di subdirektori intermediate.

Jika Anda mendeklarasikan sumber data dari beberapa kumpulan, misalnya, Google Ads atau Google Analytics, tetapkan 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 Anda mendeklarasikan beberapa tabel sumber data dalam skema yang sama, Anda dapat menggabungkan deklarasinya ke dalam satu file JavaScript.

Untuk mengetahui informasi selengkapnya tentang cara membuat deklarasi sumber data dengan JavaScript, lihat Membuat alur kerja secara eksklusif 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 Anda 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 alih-alih tabel sumber mentah. Pendekatan ini memungkinkan Anda menguji tabel sumber. Jika tabel sumber berubah, Anda dapat mengubah tampilannya—misalnya, dengan menambahkan filter atau mengubah jenis data.

Praktik terbaik untuk intermediate

Subdirektori intermediate berisi tahap kedua alur kerja 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, intermediate tabel tidak digunakan untuk tujuan tambahan—misalnya, analisis data—setelah Dataform menjalankannya ke BigQuery. Anda dapat menganggap tabel intermediate sebagai logika transformasi data yang memungkinkan pembuatan tabel output.

Sebaiknya Anda mendokumentasikan dan menguji semua tabel intermediate.

Praktik terbaik untuk outputs

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

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

Kelompokkan tabel outputs berdasarkan entitas bisnis yang terkait dengannya, misalnya—pemasaran, pesanan, atau analisis. Tentukan subdirektori untuk setiap entitas bisnis.

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

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

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

Sebaiknya Anda mendokumentasikan dan menguji 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 di direktori intermediate, misalnya, 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 entitas yang berbeda, tambahkan awalan yang mengidentifikasi entitas —misalnya, sales_revenue.sqlx atau 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 berikutnya