Menggunakan pengklusteran cairan untuk tabel

Pengklusteran cairan adalah teknik pengoptimalan tata letak data yang menggantikan partisi tabel dan ZORDER. Ini menyederhanakan manajemen tabel dan mengoptimalkan performa kueri dengan mengatur data secara otomatis berdasarkan kunci pengklusteran.

Tidak seperti pemartisian tradisional, Anda dapat menentukan ulang kunci pengklusteran tanpa menulis ulang data yang ada. Ini memungkinkan tata letak data Anda berkembang bersama dengan mengubah kebutuhan analitik. Pengklusteran cairan berlaku untuk tabel streaming dan tampilan materialisasi.

Penting

Pengklusteran liquid umumnya tersedia untuk tabel Delta Lake dengan Databricks Runtime 15.4 LTS ke atas, dan di Pratinjau Umum untuk tabel Apache Iceberg di Databricks Runtime 16.4 LTS ke atas. Databricks merekomendasikan penggunaan Databricks Runtime terbaru untuk performa terbaik.

Tabel Apache Iceberg v3 terkelola juga mendukung vektor penghapusan, pelacakan baris, konkurensi tingkat baris, dan pengklusteran cairan otomatis. Kemampuan ini memerlukan Databricks Runtime 18.0 ke atas. Lihat Menggunakan fitur Apache Iceberg v3.

Kapan menggunakan pengklusteran cair

Databricks merekomendasikan pengklusteran cairan untuk semua tabel baru, termasuk tabel streaming dan tampilan materialisasi. Skenario berikut ini terutama mendapat manfaat dari pengklusteran:

Kueri yang menyaring kolom dengan kardinalitas tinggi.
Tabel dengan ketimpangan data yang berat.
Tabel yang berkembang cepat yang membutuhkan upaya pemeliharaan dan penyetelan.
Tabel dengan persyaratan penulisan paralel.
Tabel dengan pola akses yang bervariasi atau berubah.
Tabel di mana kunci partisi umum mungkin mengembalikan hasil dari terlalu banyak atau terlalu sedikit partisi.

Mengaktifkan pengklusteran cairan

Anda dapat mengaktifkan pengklusteran cair pada tabel yang tidak dipartisi yang ada atau selama pembuatan tabel. Pengklusteran tidak kompatibel dengan partisi atau ZORDER. Databricks merekomendasikan agar platform mengelola semua operasi tata letak dan pengoptimalan untuk data dalam tabel Anda. Setelah mengaktifkan liquid clustering, jalankan OPTIMIZE jobs untuk mengkluster data secara bertahap. Lihat Cara memicu pengklusteran.

Membuat tabel dengan pengklusteran

Untuk mengaktifkan pengklusteran cairan, tambahkan CLUSTER BY frasa ke pernyataan pembuatan tabel, seperti pada contoh di bawah ini. Di Databricks Runtime 14.3 LTS ke atas, Anda dapat menggunakan API DataFrame dan Api DeltaTable di Python atau Scala untuk mengaktifkan pengklusteran cairan untuk tabel Delta Lake.

SQL

Untuk membuat tabel kosong dengan pengklusteran:

CREATE TABLE table1 (col0 INT, col1 STRING) CLUSTER BY (col0);

Untuk membuat tabel dari data yang ada dengan pengklusteran, CLUSTER BY harus muncul setelah nama tabel, bukan dalam SELECT klausa:

CREATE TABLE table2 CLUSTER BY (col0)
AS SELECT * FROM table1;

Untuk menyalin struktur tabel termasuk konfigurasi pengklusterannya:

CREATE TABLE table3 LIKE table1;

Python

Untuk membuat tabel kosong dengan klastering menggunakan API DeltaTable:

(DeltaTable.create()
  .tableName("table1")
  .addColumn("col0", dataType = "INT")
  .addColumn("col1", dataType = "STRING")
  .clusterBy("col0")
  .execute())

Untuk membuat tabel dari DataFrame yang sudah ada:

df = spark.read.table("table1")
df.write.clusterBy("col0").saveAsTable("table2")

Untuk membuat tabel menggunakan DataFrameWriterV2 API (tersedia di Databricks Runtime 14.2 ke atas):

df = spark.read.table("table1")
df.writeTo("table1").using("delta").clusterBy("col0").create()

Scala

Untuk membuat tabel kosong dengan klastering menggunakan API DeltaTable:

DeltaTable.create()
  .tableName("table1")
  .addColumn("col0", dataType = "INT")
  .addColumn("col1", dataType = "STRING")
  .clusterBy("col0")
  .execute()

Untuk membuat tabel dari DataFrame yang sudah ada:

val df = spark.read.table("table1")
df.write.clusterBy("col0").saveAsTable("table2")

Untuk membuat tabel menggunakan DataFrameWriterV2 API (tersedia di Databricks Runtime 14.2 ke atas):

val df = spark.read.table("table1")
df.writeTo("table1").using("delta").clusterBy("col0").create()

Penting

Saat menggunakan API DataFrame untuk mengatur kunci pengklusteran, Anda hanya dapat menentukan kolom pengklusteran selama pembuatan tabel atau saat menggunakan overwrite mode (seperti dengan CREATE OR REPLACE TABLE operasi). Anda tidak dapat mengubah kunci pengklusteran saat menggunakan append mode.

Untuk mengubah kunci pengklusteran pada tabel yang ada saat menambahkan data, gunakan perintah SQL ALTER TABLE untuk memodifikasi konfigurasi pengklusteran secara terpisah dari operasi penulisan data Anda. Lihat Mengubah kunci pengklusteran.

Di Databricks Runtime 16.4 LTS dan yang lebih baru, Anda dapat membuat tabel dengan liquid clustering yang diaktifkan menggunakan operasi tulis Structured Streaming, seperti pada contoh berikut:

SQL

CREATE TABLE table1 (
  col0 STRING,
  col1 DATE,
  col2 BIGINT
)
CLUSTER BY (col0, col1);

Python

(spark.readStream.table("source_table")
  .writeStream
  .clusterBy("column_name")
  .option("checkpointLocation", checkpointPath)
  .toTable("target_table")
)

Scala

spark.readStream.table("source_table")
  .writeStream
  .clusterBy("column_name")
  .option("checkpointLocation", checkpointPath)
  .toTable("target_table")

Warning

Tabel Delta Lake dengan klaster cair yang diaktifkan menggunakan writer Delta versi 7 dan reader versi 3. Klien Delta yang tidak mendukung protokol ini tidak dapat membaca tabel ini. Anda tidak dapat menurunkan versi protokol tabel. Lihat Kompatibilitas dan protokol fitur Delta Lake.

Untuk mengambil alih pengaktifan fitur default, seperti vektor penghapusan, lihat Mengambil alih pengaktifan fitur default (opsional).

Aktifkan pada tabel yang sudah ada

Untuk mengaktifkan pengklusteran cairan pada tabel Delta Lake yang tidak dipartisi yang ada, lakukan hal berikut:

ALTER TABLE <table_name>
CLUSTER BY (<clustering_columns>)

Untuk tabel Apache Iceberg terkelola, pertimbangkan hal berikut:

Untuk tabel dengan spesifikasi v2, Anda harus secara eksplisit menonaktifkan vektor penghapusan dan pelacakan baris saat mengaktifkan pengklusteran cairan pada tabel yang ada.
Untuk tabel dengan spesifikasi v3, menonaktifkan fitur ini tidak diperlukan karena penghapusan vektor dan pelacakan baris didukung. Lihat Menggunakan fitur Apache Iceberg v3.

Catatan

Perilaku default tidak menerapkan pengklusteran ke data yang ditulis sebelumnya. Untuk memaksakan pengelompokan ulang, gunakan OPTIMIZE FULL atau OPTIMIZE FULL WHERE <predicate>. Lihat Paksa Rekluster.

Mengonversi tabel yang dipartisi menjadi pengklusteran cairan

Dalam Databricks Runtime 18.1 dan yang lebih baru, untuk mengonversi tabel Delta Lake terpartisi yang sudah ada menjadi liquid clustering, gunakan REPLACE PARTITIONED BY WITH CLUSTER BY pada pernyataan ALTER TABLE. Konversi meminimalkan waktu henti bagi pembaca dan penulis serta mendukung tabel eksternal dan tabel terkelola. Setelah konversi, tabel mendukung pembacaan dengan Databricks Runtime 13.3 LTS ke atas.

Catatan

Untuk tabel Iceberg terkelola, konversi tidak diperlukan karena tabel ini menggunakan definisi partisi sebagai kunci pengklusteran cair. Menjalankan perintah konversi menimbulkan kesalahan.

Manfaat mengonversi tabel yang dipartisi ke pengklusteran cairan meliputi:

Peningkatan kinerja untuk tabel yang mengalami kemampuan melewati data yang buruk atau partisi berlebihan.
Peningkatan performa otomatis, menggunakan CLUSTER BY AUTO, untuk tabel dengan pola kueri yang sering berubah.
Kolom pengklusteran fleksibel dan mudah diubah, sedangkan partisi kaku dan sulit diubah.
Konflik penulisan berkurang karena tabel dengan liquid clustering mendukung konkurensi pada tingkat baris. Lihat Konkurensi tingkat baris.

Syntax

ALTER TABLE <table_name>
REPLACE PARTITIONED BY WITH CLUSTER BY [( <clustering_columns> ) | AUTO]

Klausa CLUSTER BY mendukung opsi berikut:

( <clustering_columns> ): Menentukan kolom pengklusteran baru. Databricks merekomendasikan untuk menyimpan kolom pengklusteran baru yang mirip dengan kolom partisi asli. Penggunaan kolom yang sangat berbeda memicu operasi pengelompokan ulang besar-besaran pada saat OPTIMIZE pertama kali dijalankan.
AUTO: Menggunakan kolom partisi saat ini sebagai kolom pengklusteran awal dan memungkinkan pengoptimalan prediktif beradaptasi dari waktu ke waktu. Hanya tersedia untuk tabel terkelola Unity Catalog. Lihat pengklusteran cairan otomatis.
Tidak ada opsi yang ditentukan: Menggunakan kolom partisi saat ini sebagai kolom pengklusteran baru.

Untuk panduan tentang memilih kunci pengklusteran saat bermigrasi dari tabel yang dipartisi, lihat Migrasi dari partisi atau urutan Z.

Contoh

Untuk mengkluster pada kolom yang berbeda dari partisi asli, seperti untuk tabel yang dipartisi pada (year, month, day), lakukan hal berikut:

ALTER TABLE t1 REPLACE PARTITIONED BY WITH CLUSTER BY (day, id);
OPTIMIZE t1;

Catatan

Untuk mendapatkan manfaat dari mengubah kolom pengklusteran, Anda harus menjalankan OPTIMIZE.

Untuk menggunakan pengklusteran cairan otomatis dan mulai dengan kolom partisi saat ini, lakukan hal berikut:

ALTER TABLE t2 REPLACE PARTITIONED BY WITH CLUSTER BY AUTO;

Untuk mempertahankan kolom partisi saat ini sebagai kolom pengklusteran, lakukan hal berikut:

ALTER TABLE t3 REPLACE PARTITIONED BY WITH CLUSTER BY;

Menangani pembacaan dan penulisan bersamaan selama konversi

Setelah konversi, Databricks Runtime 13.3 LTS dan versi yang lebih baru didukung untuk operasi baca dan tulis. Azure Databricks merekomendasikan Databricks Runtime 15.4 LTS ke atas untuk beban kerja yang membaca atau menulis ke tabel selama konversi.

Lihat tabel berikut untuk cara menangani beban kerja baca dan tulis bersamaan selama konversi:

Tipe beban kerja	Membaca saat konversi	Menulis selama konversi
Batch	Tidak ada waktu henti. Semua versi Databricks Runtime dapat membaca tabel selama konversi.	Tidak ada waktu henti pada Databricks Runtime 15.4 ke atas. Untuk Databricks Runtime 15.3 ke bawah, Databricks menyarankan agar Anda menjeda beban kerja sebelum mengonversi lalu memulai ulang beban kerja setelah konversi selesai.
Streaming	Dengan pelacakan skema dan pemetaan kolom: Mulai ulang aliran tanpa kehilangan commit apa pun. Tanpa pelacakan skema dan pemetaan kolom: Aliran menimbulkan pengecualian. Mulai ulang dengan lokasi checkpoint baru dan versi awal. Commit tidak hilang.	Mulai ulang stream tanpa kehilangan commit apa pun.

Memverifikasi atau mengembalikan konversi

Untuk mengonfirmasi konversi, jalankan DESCRIBE EXTENDED untuk melihat kolom pengklusteran baru. Jalankan DESCRIBE HISTORY untuk melihat serangkaian REORG operasi, UPGRADE PROTOCOL operasi, dan REPLACE PARTITIONED BY WITH CLUSTER BY operasi.

Untuk mengembalikan konversi, gunakan RESTORE untuk kembali ke versi sebelumnya. Atau, Anda dapat menulis ulang tabel menggunakan REPLACE TABLE ... PARTITIONED BY (...) AS SELECT * FROM ....

Untuk menggulung balik menggunakan RESTORE, jalankan perintah berikut:

ALTER TABLE my_table CLUSTER BY NONE;
ALTER TABLE my_table UNSET TBLPROPERTIES ('delta.liquid.hierarchicalClusteringColumns');
RESTORE TABLE my_table TO VERSION AS OF <version_number_before_conversion>;

Lihat RESTORE.

Mengonversi tabel yang dipartisi oleh kolom tanda waktu

Untuk mengonversi tabel (t1) yang dipartisi oleh kolom tanda waktu (timestamp_col) dan menggunakan kolom tanda waktu sebagai kunci pengklusteran, Anda harus mengatur konfigurasi tambahan:

SET spark.databricks.delta.liquidConversion.statsGeneration.enabled = false;
ALTER TABLE t1 REPLACE PARTITIONED BY WITH CLUSTER BY (timestamp_col, id);
ANALYZE TABLE t1 COMPUTE DELTA STATISTICS;

Jika Anda mencoba mengonversi kolom partisi tanda waktu ke kolom pengklusteran tanpa konfigurasi ini, perintah akan menimbulkan kesalahan:

ALTER TABLE REPLACE PARTITIONED BY WITH CLUSTER BY cannot auto-generate stats on table with column event_ts due to unsupported type: timestamp. Disable stats auto-generation by setting 'spark.databricks.delta.liquidConversion.statsGeneration.enabled' to 'false' and retry the command again. SQLSTATE: 42000

Batasan konversi

Batasan berikut berlaku untuk REPLACE PARTITIONED BY WITH CLUSTER BY perintah konversi:

Tabel streaming dan tampilan terwujud yang dibuat dalam alur Lakeflow tidak didukung. Untuk menggunakan pengklusteran cairan, Anda harus memperbarui definisi alur untuk digunakan CLUSTER BY alih-alih PARTITIONED BY.
Tabel yang menggunakan Delta Sharing dengan pemfilteran partisi tidak didukung. Untuk informasi tentang pemfilteran partisi untuk Berbagi Delta, lihat Menentukan partisi tabel yang akan dibagikan.

Menghapus kunci pengklusteran

Untuk menghapus kunci pengklusteran, gunakan sintaks berikut:

ALTER TABLE table_name CLUSTER BY NONE;

Pilih kunci pengklusteran

Pilih kunci pengklusteran berdasarkan kolom yang paling umum digunakan dalam filter kueri. Kunci yang tepat secara signifikan meningkatkan pengabaian data dan kinerja kueri.

Tip

Databricks merekomendasikan penggunaan pengklusteran cairan otomatis untuk memilih kunci pengklusteran secara cerdas berdasarkan pola kueri Anda. Lihat pengklusteran cairan otomatis.

Panduan pemilihan kunci

Saat Anda menentukan kunci pengklusteran secara manual, pilih kolom berdasarkan kolom yang paling sering digunakan dalam filter kueri. Anda dapat menentukan kunci pengklusteran dalam urutan apa pun. Jika dua kolom sangat berkorelasi, Anda hanya perlu menyertakan salah satunya sebagai kunci pengklusteran.

Anda dapat menentukan hingga empat kunci pengklusteran. Untuk tabel yang lebih kecil (kurang dari 10 TB), menggunakan lebih banyak kunci pengklusteran dapat menurunkan performa saat memfilter pada satu kolom. Misalnya, pemfilteran dengan empat kunci berkinerja lebih buruk daripada pemfilteran dengan dua kunci. Namun, ketika ukuran tabel meningkat, perbedaan performa ini menjadi dapat diabaikan untuk kueri kolom tunggal.

Kunci pengklusteran harus berupa kolom yang memiliki statistik yang dikumpulkan. Secara default, tabel Delta Lake mengumpulkan statistik untuk 32 kolom pertama. Lihat Menentukan kolom statistik.

Jenis data yang didukung

Pengklusteran mendukung jenis data ini untuk kunci pengklusteran:

Date
Timestamp
TimestampNTZ (Databricks Runtime 14.3 LTS ke atas)
String
Bilangan bulat, Panjang, Pendek, Byte
Float, Double, Desimal

Anda dapat mengkluster StructField dengan menggunakan notasi titik, seperti CLUSTER BY (struct_col.field). Bidang struktur berlapis didukung ke kedalaman apa pun, seperti CLUSTER BY (struct_col.nested.field). Tipe data bidang harus menjadi salah satu jenis yang didukung dalam daftar sebelumnya.

Anda tidak dapat mengelompokkan berdasarkan salah satu dari berikut ini:

Jenis kompleks, seperti StructType, MapType, atau ArrayType
MapType dan ArrayType elemen, seperti map_col['key'], , array_col[0]atau map_col.key.

Migrasi dari partisi atau Z-order

Penting

Databricks merekomendasikan agar Anda menggunakan konversi otomatis dengan REPLACE PARTITIONED BY WITH CLUSTER BY perintah. Lihat Mengonversi tabel yang dipartisi menjadi pengklusteran cairan.

Jika Anda mengonversi tabel yang sudah ada, pertimbangkan rekomendasi berikut:

Teknik pengoptimalan data saat ini	Rekomendasi untuk kunci pengklusteran
Pemartisian Gaya Hive	Gunakan kolom partisi sebagai kunci pengklusteran.
Pengindeksan Z-order	`ZORDER BY` Gunakan kolom sebagai kunci pengklusteran.
Pemartisian gaya Hive dan urutan-Z	Gunakan kolom partisi dan kolom `ZORDER BY` sebagai kunci pengklusteran.
Kolom yang dihasilkan untuk mengurangi kardinalitas (misalnya, tanggal untuk tanda waktu)	Gunakan kolom asli sebagai kunci pengklusteran, dan jangan buat kolom yang dihasilkan.

Pengklusteran cairan otomatis

Di Databricks Runtime 15.4 LTS ke atas, Anda dapat mengaktifkan pengklusteran cairan otomatis untuk tabel Delta Lake yang dikelola Katalog Unity. Untuk tabel Apache Iceberg v3 yang dikelola Unity Catalog, pengklusteran cairan otomatis memerlukan Databricks Runtime 18.0 ke atas. Pengklusteran cairan otomatis memungkinkan Azure Databricks untuk memilih kunci pengklusteran secara cerdas untuk mengoptimalkan performa kueri, menggunakan klausa CLUSTER BY AUTO.

Catatan

Pengklusteran cairan otomatis juga didukung untuk tampilan materialisasi dan tabel streaming, termasuk alur Lakeflow dan alur mandiri. Tentukan CLUSTER BY AUTO dalam definisi alur atau SQL Anda.

Cara kerja pengklusteran cairan otomatis

Pengklusteran cairan otomatis memerlukan pengoptimalan prediktif untuk pemilihan kunci otomatis dan operasi pengklusteran, dan berjalan secara asinkron. Lihat Pengoptimalan prediktif untuk tabel yang dikelola oleh Unity Catalog.

Pengklusteran cairan otomatis menerapkan pengoptimalan cerdas berdasarkan pola penggunaan Anda:

Menganalisis beban kerja kueri: Azure Databricks menganalisis beban kerja kueri historis tabel dan mengidentifikasi kolom kandidat terbaik untuk pengklusteran.
Beradaptasi dengan perubahan: Jika pola kueri atau distribusi data Anda berubah dari waktu ke waktu, pengklusteran cairan otomatis memilih kunci baru untuk mengoptimalkan performa.
Pemilihan berdasarkan biaya: Azure Databricks mengubah kunci pengelompokan hanya ketika penghematan biaya yang diprediksi dari peningkatan skip data melebihi biaya pengelompokan data.

Pengklusteran cairan otomatis mungkin tidak memilih kunci karena alasan berikut:

Tabel terlalu kecil untuk mendapatkan manfaat dari pengklusteran cairan.
Tabel sudah memiliki skema pengklusteran yang efektif, baik dari kunci manual sebelumnya atau urutan penyisipan alami yang cocok dengan pola kueri.
Tabel tidak memiliki kueri yang sering.
Anda tidak menggunakan Databricks Runtime 15.4 LTS atau lebih tinggi.

Anda dapat menerapkan pengklusteran cairan otomatis untuk semua tabel terkelola Unity Catalog, terlepas dari karakteristik data dan kueri. Heuristik memutuskan apakah itu menguntungkan biaya untuk memilih kunci pengklusteran.

Kompatibilitas versi Databricks Runtime

Anda dapat membaca atau menulis tabel dengan pengklusteran otomatis diaktifkan dari semua versi Databricks Runtime yang mendukung pengklusteran cairan. Namun, pemilihan kunci cerdas bergantung pada metadata yang diperkenalkan dalam Databricks Runtime 15.4 LTS.

Gunakan Databricks Runtime 15.4 LTS atau lebih tinggi untuk memastikan bahwa kunci yang dipilih secara otomatis menguntungkan semua beban kerja Anda dan bahwa beban kerja ini dipertimbangkan saat memilih kunci baru.

Mengaktifkan atau menonaktifkan pengklusteran cairan otomatis

SQL

Untuk membuat tabel dengan pengklusteran cairan otomatis:

CREATE OR REPLACE TABLE table1 (column01 int, column02 string) CLUSTER BY AUTO;

Untuk mengaktifkan pengklusteran cairan otomatis pada tabel yang ada, termasuk tabel dengan kunci yang ditentukan secara manual:

ALTER TABLE table1 CLUSTER BY AUTO;

Untuk mengatur petunjuk kolom pengklusteran awal untuk pemilihan kunci, atur kunci pengklusteran lalu aktifkan pengklusteran otomatis:

ALTER TABLE table1 CLUSTER BY (c1, c2);
ALTER TABLE table1 CLUSTER BY AUTO;

Atau, gunakan API Python untuk mengatur petunjuk dalam satu operasi.

Untuk menonaktifkan pengklusteran cairan otomatis:

ALTER TABLE table1 CLUSTER BY NONE;

Untuk menonaktifkan pengklusteran cairan otomatis dan menentukan kolom pengklusteran:

ALTER TABLE table1 CLUSTER BY (column01, column02);

Jika tabel yang sudah ada telah mengaktifkan pengelompokan cair otomatis, menjalankan CREATE OR REPLACE table_name tanpa CLUSTER BY AUTO akan menonaktifkan pengelompokan otomatis dan tidak mempertahankan kolom pengelompokan. Untuk mempertahankan pengklusteran cairan otomatis dan kolom yang dipilih sebelumnya, sertakan CLUSTER BY AUTO dalam pernyataan ganti. Dengan CLUSTER BY AUTO, pengoptimalan prediktif menggunakan beban kerja kueri historis untuk tabel guna mengidentifikasi kunci pengklusteran terbaik.

Python

API Python tersedia di Databricks Runtime 16.4 ke atas. Anda hanya dapat menggunakan Python saat membuat atau mengganti tabel. Gunakan SQL untuk mengubah clusterByAuto status tabel yang sudah ada.

Untuk membuat tabel dengan pengklusteran cairan otomatis menggunakan DataFrameWriter:

df = spark.read.table("table1")
df.write
  .format("delta")
  .option("clusterByAuto", "true")
  .saveAsTable(...)

Untuk mengatur petunjuk kolom pengklusteran awal untuk pemilihan kunci menggunakan DataFrameWriter:

df.write
  .format("delta")
  .clusterBy("clusteringColumn1", "clusteringColumn2")
  .option("clusterByAuto", "true")
  .saveAsTable(...)

Untuk membuat tabel dengan pengklusteran cairan otomatis menggunakan DataFrameWriterV2:

df.writeTo(...).using("delta")
  .option("clusterByAuto", "true")
  .create()

Untuk mengatur petunjuk kolom pengklusteran awal untuk pemilihan kunci menggunakan DataFrameWriterV2:

df.writeTo(...).using("delta")
  .clusterBy("clusteringColumn1", "clusteringColumn2")
  .option("clusterByAuto", "true")
  .create()

Untuk membuat tabel streaming dengan pengklusteran cairan otomatis:

spark.readStream.table("source_table")
  .writeStream
  .option("clusterByAuto", "true")
  .option("checkpointLocation", checkpointPath)
  .toTable("target_table")

Untuk mengatur petunjuk kolom pengklusteran awal untuk pemilihan kunci dalam tabel streaming:

spark.readStream.table("source_table")
  .writeStream
  .clusterBy("column1", "column2")
  .option("clusterByAuto", "true")
  .option("checkpointLocation", checkpointPath)
  .toTable("target_table")

Saat Anda menggunakan .clusterBy untuk petunjuk pemilihan kunci kluster bersama dengan .option('clusterByAuto', 'true'), perilakunya adalah sebagai berikut:

Jika ini mengatur pengklusteran cairan otomatis untuk pertama kalinya, kolom pengklusteran diatur ke kolom yang ditentukan di .clusterBy.
Jika ini adalah tabel yang sudah ada dengan pengelompokan liquid otomatis diaktifkan, petunjuk .clusterBy hanya diterima satu kali. Misalnya, kolom yang ditentukan oleh .clusterBy hanya diatur jika tabel tidak memiliki kolom pengklusteran yang ditetapkan.

Penting

Saat menggunakan API DataFrame, clusterByAuto opsi hanya dapat diatur saat menggunakan overwrite mode. Anda tidak dapat mengatur clusterByAuto ketika menggunakan append mode. Pembatasan ini sama seperti saat mengatur kolom pengklusteran secara manual. Anda hanya dapat mengonfigurasi pengaturan pengklusteran selama operasi pembuatan tabel atau penggantian menggunakan overwrite mode.

Sebagai solusinya, jika Anda ingin mengubah clusterByAuto status pada tabel yang ada saat menambahkan data, gunakan perintah SQL ALTER TABLE untuk memodifikasi konfigurasi pengklusteran secara terpisah dari operasi penulisan data Anda.

Periksa apakah pengklusteran otomatis diaktifkan

Untuk memeriksa apakah tabel mengaktifkan pengklusteran cairan otomatis, gunakan DESCRIBE TABLE atau SHOW TBLPROPERTIES.

Jika pengklusteran cairan otomatis diaktifkan, clusterByAuto properti diatur ke true. Properti clusteringColumns menunjukkan kolom pengklusteran saat ini yang dipilih secara otomatis atau manual.

Keterbatasan

Pengklusteran cairan otomatis tidak tersedia untuk tabel Apache Iceberg v2 terkelola. Ini didukung untuk tabel Apache Iceberg v3 terkelola di Databricks Runtime 18.0 ke atas.

Menulis data ke tabel berkluster

Untuk menulis ke tabel Delta Lake berkluster, Anda harus menggunakan klien penulis Delta yang mendukung semua fitur tabel protokol tulis Delta yang digunakan oleh pengklusteran cairan. Untuk menulis ke tabel Iceberg berkluster, Anda dapat menggunakan Iceberg REST Catalog API Unity Catalog. Pada Azure Databricks, Anda harus menggunakan Databricks Runtime 13.3 LTS ke atas.

Operasi yang mendukung pengklusteran saat menulis

Operasi yang dikelompokkan saat penulisan meliputi hal-hal berikut:

INSERT INTO Operasi
CTAS dan RTAS pernyataan
COPY INTO dari format Parquet
spark.write.mode("append")

Ambang ukuran untuk pengklusteran

Pengklusteran saat penulisan hanya dipicu ketika data dalam transaksi memenuhi ambang ukuran. Ambang batas ini bervariasi menurut jumlah kolom pengklusteran dan lebih rendah untuk tabel terkelola Katalog Unity daripada tabel Delta Lake lainnya.

Jumlah kolom pengklusteran	Ukuran ambang batas untuk tabel terkelola Katalog Unity	Ukuran ambang batas untuk tabel Delta Lake lainnya
1	64 MB	256 MB
2	256 MB	1 GB
3	512 MB	2 GB
4	1 GB	4 GB

Karena tidak semua operasi menerapkan pengklusteran cairan, Databricks merekomendasikan untuk sering berjalan OPTIMIZE untuk memastikan bahwa semua data diklusterkan secara efisien.

Beban kerja streaming

Beban kerja Streaming Terstruktur mendukung pengklusteran saat menulis saat Anda mengatur konfigurasi spark.databricks.delta.liquid.eagerClustering.streaming.enabled Spark ke true. Pengklusteran untuk beban kerja ini hanya aktif jika setidaknya salah satu dari lima pembaruan streaming terakhir melebihi ambang batas ukuran dari tabel di atas.

Cara memicu pengklusteran

Pengoptimalan prediktif secara otomatis menjalankan OPTIMIZE perintah untuk tabel yang diaktifkan. Lihat Pengoptimalan prediktif untuk tabel yang dikelola oleh Unity Catalog. Saat menggunakan pengoptimalan Prediktif, Databricks merekomendasikan untuk menonaktifkan pekerjaan terjadwal OPTIMIZE apa pun.

Untuk memicu pengklusteran, Anda harus menggunakan Databricks Runtime 13.3 LTS atau lebih tinggi. Databricks merekomendasikan Databricks Runtime 17.3 LTS ke atas untuk performa yang lebih cepat OPTIMIZE pada tabel besar. OPTIMIZE Gunakan perintah pada tabel Anda:

OPTIMIZE table_name;

Pengklusteran cairan bertahap, yang berarti bahwa hanya menulis ulang data seperlunya untuk mengakomodasi data yang membutuhkan OPTIMIZE. OPTIMIZE tidak menulis ulang file data dengan kunci pengklusteran yang tidak cocok dengan data yang diklusterkan. Lihat Paksa Rekluster.

Jika Anda tidak menggunakan pengoptimalan prediktif, Databricks merekomendasikan untuk menjadwalkan job rutin OPTIMIZE guna mengelompokkan data. Untuk tabel yang banyak diperbarui atau disisipkan, Databricks merekomendasikan penjadwalan OPTIMIZE job setiap satu atau dua jam. Karena pengklusteran cairan bersifat inkremental, sebagian besar OPTIMIZE pekerjaan untuk tabel berkluster berjalan dengan cepat.

Pengelompokan ulang paksa

Di Databricks Runtime 16.4 LTS ke atas, Anda dapat memaksa pencatatan ulang semua rekaman dalam tabel dengan sintaks berikut:

OPTIMIZE table_name FULL;

Penting

Menjalankan OPTIMIZE FULL mengelompokkan ulang semua data yang ada seperlunya. Untuk tabel besar yang sebelumnya belum diklusterkan pada kunci yang ditentukan, operasi ini mungkin memakan waktu berjam-jam.

Jalankan OPTIMIZE FULL saat Anda mengaktifkan pengklusteran untuk pertama kalinya atau mengubah kunci pengklusteran. Jika sebelumnya Anda telah menjalankan OPTIMIZE FULL dan belum ada perubahan pada kunci pengklusteran, OPTIMIZE FULL berjalan sama dengan OPTIMIZE. Dalam skenario ini, OPTIMIZE menggunakan pendekatan inkremental dan hanya menulis ulang file yang sebelumnya belum dipadatkan. Selalu gunakan OPTIMIZE FULL untuk memastikan bahwa tata letak data mencerminkan kunci pengklusteran saat ini.

Rekluster parsial

Di Databricks Runtime 18.1 dan versi yang lebih baru, Anda dapat memaksa pengelompokan ulang untuk sebagian catatan menggunakan OPTIMIZE FULL WHERE <predicate>. File disertakan jika ada bagian dari rentangnya yang tumpang tindih dengan predikat . Lihat Parameter.

OPTIMIZE events FULL WHERE event_date >= '2025-01-01';

Membaca data dari tabel terkluster

Anda dapat membaca data dalam tabel Delta Lake berkluster menggunakan klien Delta Lake apa pun yang mendukung vektor penghapusan baca. Dengan menggunakan Iceberg REST Catalog API, Anda dapat membaca data dalam tabel Iceberg berkluster. Pengklusteran cairan meningkatkan performa kueri melalui lompati data otomatis saat memfilter kunci pengklusteran.

SELECT * FROM table_name WHERE cluster_key_column_name = "some_value";

Mengelola kunci pengklusteran

Lihat bagaimana tabel diklusterkan

Anda dapat menggunakan DESCRIBE perintah untuk melihat kunci pengklusteran untuk tabel, seperti dalam contoh berikut:

DESCRIBE TABLE table_name;

DESCRIBE DETAIL table_name;

Mengubah kunci pengklusteran

Anda dapat mengubah kunci pengklusteran untuk tabel kapan saja dengan menjalankan ALTER TABLE perintah, seperti dalam contoh berikut:

ALTER TABLE table_name CLUSTER BY (new_column1, new_column2);

Saat Anda mengubah kunci pengklusteran, operasi berikutnya OPTIMIZE dan tulis menggunakan pendekatan pengklusteran baru, tetapi data yang ada tidak ditulis ulang. Untuk menulis ulang data yang ada dengan kunci pengklusteran yang diperbarui, lihat Memaksa rekluster.

Anda juga dapat menonaktifkan pengklusteran dengan mengatur kunci ke NONE, seperti dalam contoh berikut:

ALTER TABLE table_name CLUSTER BY NONE;

Mengatur kunci kluster agar NONE tidak menulis ulang data berkluster, tetapi mencegah operasi di masa mendatang OPTIMIZE menggunakan kunci pengklusteran.

Menggunakan pengklusteran cairan dari mesin eksternal

Anda dapat mengaktifkan pengklusteran cairan pada tabel Iceberg terkelola dari mesin Iceberg eksternal. Untuk mengaktifkan pengklusteran cairan, tentukan kolom partisi saat membuat tabel. Katalog Unity menginterpretasikan partisi sebagai kunci pengklusteran. Misalnya, jalankan perintah di bawah ini di OSS Spark:

CREATE OR REPLACE TABLE main.schema.icebergTable
PARTITIONED BY c1;

Untuk menonaktifkan pengklusteran cairan:

ALTER TABLE main.schema.icebergTable DROP PARTITION FIELD c2;

Untuk mengubah kunci pengklusteran menggunakan evolusi partisi Iceberg:

ALTER TABLE main.schema.icebergTable ADD PARTITION FIELD c2;

Jika Anda menentukan partisi menggunakan transformasi wadah, Katalog Unity akan menghilangkan ekspresi dan menggunakan kolom sebagai kunci pengklusteran:

CREATE OR REPLACE TABLE main.schema.icebergTable
PARTITIONED BY (bucket(c1, 10));

Kompatibilitas untuk tabel dengan pengklusteran cair

Pengklusteran liquid menggunakan fitur tabel Delta Lake yang memerlukan versi Databricks Runtime tertentu untuk membaca dan menulis. Tabel yang dibuat dengan pengklusteran cair di Databricks Runtime 14.3 LTS ke atas menggunakan titik pemeriksaan V2 secara default. Anda dapat membaca dan menulis tabel dengan titik pemeriksaan V2 di Databricks Runtime 13.3 LTS ke atas. Lihat Titik Pemeriksaan V2.

Untuk mendukung pembaca yang menggunakan Databricks Runtime 12.2 LTS ke 13.2, nonaktifkan titik pemeriksaan V2 dan turunkan protokol tabel. Lihat Beralih ke versi klasik.

Mengesampingkan pengaktifan fitur default (opsional)

Anda dapat mengambil alih pengaktifan fitur tabel Delta Lake default selama pengaktifan pengklusteran cairan. Ini mencegah peningkatan protokol pembaca dan penulis yang terkait dengan fitur tabel tersebut. Anda harus memiliki tabel yang sudah ada untuk menyelesaikan langkah-langkah berikut:

Gunakan ALTER TABLE untuk mengatur properti tabel yang menonaktifkan satu atau beberapa fitur. Misalnya, untuk menonaktifkan vektor penghapusan, jalankan hal berikut:
```
ALTER TABLE table_name SET TBLPROPERTIES ('delta.enableDeletionVectors' = false);
```
Aktifkan pengklusteran cairan pada tabel dengan menjalankan hal berikut:
```
ALTER TABLE <table_name>
CLUSTER BY (<clustering_columns>)
```

Tabel berikut ini memiliki informasi tentang fitur Delta yang dapat Anda ambil alih dan bagaimana pengaktifan memengaruhi kompatibilitas dengan versi Databricks Runtime:

Fitur Delta	Kompatibilitas runtime	Properti untuk menonaktifkan pengaktifan	Efek pada pengklusteran cairan jika dinonaktifkan
Vektor penghapusan	Baca dan tulis memerlukan Databricks Runtime 12.2 LTS ke atas.	`'delta.enableDeletionVectors' = false`	Menonaktifkan deletion vector juga menonaktifkan konkurensi pada level baris, sehingga transaksi dan operasi klastering lebih mungkin mengalami konflik. Lihat Konkurensi tingkat baris. `DELETE`, `MERGE`, dan `UPDATE` perintah mungkin berjalan lebih lambat.
Pelacakan baris data	Penulisan memerlukan Databricks Runtime 13.3 LTS ke atas. Dapat dibaca dari versi Databricks Runtime apa pun.	`'delta.enableRowTracking' = false`	Menonaktifkan pelacakan baris juga menonaktifkan konkurensi pada tingkat baris, sehingga transaksi dan operasi klastering lebih mungkin mengalami konflik. Lihat Konkurensi tingkat baris.
Titik Pemeriksaan V2	Baca dan tulis memerlukan Databricks Runtime 13.3 LTS ke atas.	`'delta.checkpointPolicy' = 'classic'`	Tidak ada efek pada perilaku pengklusteran cairan. Lihat Titik Pemeriksaan V2.

Keterbatasan

Databricks Runtime 15.1 ke bawah: Pengklusteran saat penulisan tidak mendukung kueri sumber yang mencakup filter, gabungan, atau agregasi.
Databricks Runtime 15.4 LTS dan di bawah ini: Anda tidak dapat membuat tabel dengan pengklusteran cair diaktifkan menggunakan penulisan Streaming Terstruktur. Anda dapat menggunakan Streaming Terstruktur untuk menulis data ke tabel yang ada dengan pengklusteran cair diaktifkan.
Apache Iceberg v2: Konkurensi tingkat baris tidak didukung pada tabel Apache Iceberg v2 terkelola karena vektor penghapusan dan pelacakan baris tidak didukung.
- Konkurensi tingkat baris didukung pada tabel Apache Iceberg v3 terkelola karena spesifikasi v3 mendukung vektor penghapusan dan pelacakan baris. Lihat Menggunakan fitur Apache Iceberg v3.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-10

Menggunakan pengklusteran cairan untuk tabel

Kapan menggunakan pengklusteran cair

Mengaktifkan pengklusteran cairan

Membuat tabel dengan pengklusteran

SQL

Python

Scala

SQL

Python

Scala

Aktifkan pada tabel yang sudah ada

Mengonversi tabel yang dipartisi menjadi pengklusteran cairan

Syntax

Contoh

Menangani pembacaan dan penulisan bersamaan selama konversi

Memverifikasi atau mengembalikan konversi

Mengonversi tabel yang dipartisi oleh kolom tanda waktu

Batasan konversi

Menghapus kunci pengklusteran

Pilih kunci pengklusteran

Panduan pemilihan kunci

Jenis data yang didukung

Migrasi dari partisi atau Z-order

Pengklusteran cairan otomatis

Cara kerja pengklusteran cairan otomatis

Kompatibilitas versi Databricks Runtime

Mengaktifkan atau menonaktifkan pengklusteran cairan otomatis

SQL

Python

Periksa apakah pengklusteran otomatis diaktifkan

Keterbatasan

Menulis data ke tabel berkluster

Operasi yang mendukung pengklusteran saat menulis

Ambang ukuran untuk pengklusteran

Beban kerja streaming

Cara memicu pengklusteran

Pengelompokan ulang paksa

Rekluster parsial

Membaca data dari tabel terkluster

Mengelola kunci pengklusteran

Lihat bagaimana tabel diklusterkan

Mengubah kunci pengklusteran

Menggunakan pengklusteran cairan dari mesin eksternal

Kompatibilitas untuk tabel dengan pengklusteran cair

Mengesampingkan pengaktifan fitur default (opsional)

Keterbatasan

Saran dan Komentar

Sumber Daya Tambahan: