Hologres:Akses data Paimon dengan Katalog DLF

Gunakan Database Eksternal (direkomendasikan)

Database Eksternal memetakan katalog DLF ke Hologres sehingga Anda dapat melakukan kueri, mengelola, dan mencerminkan tabel Paimon. Fitur ini mendukung dua mode autentikasi:

Gunakan server asing (legacy)

Pendekatan server asing tidak mendukung Time Travel, kueri branch, atau mirroring data. Gunakan database eksternal untuk fitur-fitur tersebut.

Langkah 1: Buat foreign server.

Untuk DLF V2.5 dan lebih baru:

CREATE SERVER IF NOT EXISTS <server_name> FOREIGN DATA WRAPPER dlf_fdw OPTIONS (
  catalog_type 'paimon',
  metastore_type 'dlf-rest',
  dlf_catalog '<dlf_catalog_name>'
);

Untuk DLF V1.0:

CREATE SERVER IF NOT EXISTS <server_name> FOREIGN DATA WRAPPER dlf_fdw OPTIONS (
  dlf_region '',
  dlf_endpoint 'dlf-share.<region>.aliyuncs.com',
  oss_endpoint 'oss-<region_id>-internal.aliyuncs.com',
  dlf_catalog '<dlf_catalog_name>'
);

Untuk operasi server asing lainnya, lihat Operasi server asing tambahan.

Langkah 2: Buat tabel asing.

Gunakan IMPORT FOREIGN SCHEMA untuk mengimpor semua tabel dalam database DLF:

-- Impor semua tabel
IMPORT FOREIGN SCHEMA <dlf_db_name>
FROM SERVER <server_name>
INTO <holo_schema_name>
OPTIONS (if_table_exist 'update');

-- Impor tabel tertentu
IMPORT FOREIGN SCHEMA <dlf_db_name>
LIMIT TO (<table_name>[, ...])
FROM SERVER <server_name>
INTO <holo_schema_name>
OPTIONS (if_table_exist 'update');

Atau buat satu tabel asing dengan CREATE FOREIGN TABLE:

CREATE FOREIGN TABLE <foreign_table_name>
(
  <column_name> <data_type>
  [, ...]
)
SERVER <server_name>
OPTIONS
(
  schema_name '<dlf_db_name>',
  table_name '<dlf_table_name>'
);

Untuk detail sintaksis, lihat IMPORT FOREIGN SCHEMA dan CREATE FOREIGN TABLE.

Kumpulkan statistik untuk optimasi kueri

Jalankan ANALYZE atau AUTO ANALYZE untuk mengumpulkan statistik tabel. Pengoptimal kueri menggunakan statistik ini untuk menyusun rencana kueri optimal.

-- Kumpulkan statistik untuk semua kolom
ANALYZE <ext_database_name>.<ext_schema_name>.<ext_table_name>;

-- Kumpulkan statistik untuk kolom tertentu (lebih akurat; gunakan untuk kolom filter)
ANALYZE <ext_database_name>.<ext_schema_name>.<ext_table_name>(<col_name>[, <col_name>]);

-- Aktifkan AUTO ANALYZE untuk Database Eksternal
ALTER EXTERNAL DATABASE <ext_database_name> WITH enable_auto_analyze 'true';

Untuk detail selengkapnya, lihat ANALYZE dan AUTO ANALYZE.

Kueri dengan Time Travel

Mulai dari V3.2, Hologres mendukung kueri snapshot historis tabel Paimon berdasarkan timestamp, versi (ID snapshot), atau tag.

Daftar snapshot yang tersedia:

SELECT * FROM hologres.hg_list_snapshots('<ext_database_name>.<ext_schema_name>.<ext_table_name>');

Tabel snapshot mengembalikan bidang-bidang berikut:

Anda juga dapat melakukan kueri tabel sistem snapshot Paimon menggunakan fungsi hg_list_versions. Untuk tabel Paimon, versi sesuai dengan ID Snapshot.

SELECT * FROM hologres.hg_list_versions('<ext_database_name>.<ext_schema_name>.<ext_table_name>');

Daftar tag yang tersedia:

SELECT * FROM hologres.hg_list_tags('<ext_database_name>.<ext_schema_name>.<ext_table_name>');

Kueri berdasarkan timestamp:

SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>
FOR TIMESTAMP AS OF '<timestamp>';

Kueri berdasarkan versi (ID snapshot):

SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>'
FOR VERSION AS OF '<version>';

Kueri berdasarkan tag:

SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>'
FOR TAG AS OF '<tag>';

Hologres V3.2.6 dan V4.0.6 serta versi lebih baru mendukung pembacaan data dari tag yang sesuai dengan snapshot Paimon yang telah kedaluwarsa.

Untuk informasi selengkapnya tentang tabel sistem Paimon, lihat tabel sistem Paimon.

Kueri branch Paimon

Mulai dari V3.2, Hologres dapat melakukan kueri data dari branch Paimon tertentu, termasuk snapshot historis di dalam branch tersebut.

Daftar branch yang tersedia:

SELECT * FROM hologres.hg_list_branches('<ext_database_name>.<ext_schema_name>.<ext_table_name>');

Kueri data cabang saat ini:

SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>'
FOR branch AS OF '<branch_name>';

Jika scan.fallback-branch diatur pada tabel Paimon, Hologres secara otomatis membaca partisi yang hilang dari branch fallback. Lihat Kelola branch.

Kueri snapshot historis di dalam sebuah branch:

-- Berdasarkan timestamp
SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>'
FOR branch AS OF '<branch_name>' TIMESTAMP AS OF '<timestamp>';

-- Berdasarkan tag
SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>'
FOR branch AS OF '<branch_name>' TAG AS '<tag_name>';

Percepat kueri dengan mirroring tabel lake

Mulai dari V3.2, Hologres mendukung mirroring tabel lake, yang menyinkronkan metadata dan data tabel Paimon ke Hologres secara near-real-time atau pada interval terjadwal. Data yang dicerminkan disajikan dari penyimpanan Hologres, sehingga secara signifikan mengurangi latensi kueri. Mirroring tabel penuh dan mirroring parsial tabel terpartisi keduanya didukung.

Untuk detail penyiapan, lihat Mirroring tabel lake.

Percepat kueri dengan Bitmap File Index

Mulai dari V5.0, Hologres membaca langsung Bitmap File Index (format indeks V2) pada tabel Paimon. Saat Anda memfilter kolom yang diindeks dengan predikat equality (=) atau IN, pembaca Hologres menggunakan bitmap untuk menemukan baris yang cocok dan melewati baris yang tidak relevan. Hal ini mengurangi jumlah data yang dipindai dan mempercepat kueri point serta kueri multi-nilai pada tabel lake. Kemampuan ini diaktifkan secara default.

Cara kerja dan kapan berlaku:

• Penulis Paimon menghasilkan indeks. Flink, Spark, dan mesin lain dapat menulisnya, dan Hologres juga menghasilkannya secara otomatis saat Anda menjalankan INSERT terhadap tabel asing Paimon—asalkan file-index.bitmap.columns dideklarasikan pada tabel.

• Indeks disimpan per file data. Setiap file data memiliki file pendamping .index yang namanya diawali dengan nama file data.

• Pembaca Hologres mendeteksi versi format indeks secara otomatis, dan kedua format dapat berdampingan dalam tabel yang sama: format indeks V2 menggunakan parser V2, format indeks V1 tetap menggunakan parser V1. Kueri yang ada tidak terpengaruh.

• Tipe kolom yang didukung untuk indeks mencakup tipe panjang tetap (SMALLINT, INT, BIGINT, DATE, TIME, TIMESTAMP, dan sebagainya) serta tipe panjang variabel (STRING atau TEXT). FLOAT, DOUBLE, dan DECIMAL tidak didukung.

• Hanya predikat equality (=) dan IN yang mendapat manfaat. Predikat rentang, LIKE, dan predikat lainnya tidak menggunakan indeks bitmap.

Langkah-langkah:

1. Deklarasikan kolom indeks bitmap saat membuat tabel.

   -- Buat tabel asing Paimon dan deklarasikan kolom indeks bitmap
   CREATE EXTERNAL TABLE EXT_DATABASE_NAME.EXT_SCHEMA_NAME.EXT_TABLE_NAME (
     id        INT,
     c_id      INT,
     c_name    TEXT
   )
   WITH (
     "table_format"              = 'paimon',
     "file_format"               = 'parquet',       -- Baik Parquet maupun ORC mendukung pembacaan Bitmap File Index
     "bucket"                    = '4',
     "bucket-key"                = 'id',
     "file-index.bitmap.columns" = 'c_id,c_name'    -- Kolom yang diindeks, dipisahkan koma
   );

   Catatan

   Untuk menurunkan kolom tertentu ke format indeks V1, atur "file-index.bitmap.<COLUMN_NAME>.version" = '1' untuk kolom tersebut. Default-nya adalah format indeks V2.

2. Verifikasi bahwa sakelar Bitmap File Index diaktifkan. Hologres mengaktifkan sakelar berikut secara default mulai dari V5.0. Untuk mengonfirmasi statusnya atau mengaktifkannya secara manual, jalankan:

   -- Flag global yang mengontrol pembacaan Bitmap File Index
   SELECT hg_admin_command('set_global_flag','enable_paimon_bitmap_index=true');                    -- Sakelar utama
   SELECT hg_admin_command('set_global_flag','enable_push_bitmap_to_fse_parquet_reader=true');      -- Pushdown di pembaca Parquet
   SELECT hg_admin_command('set_global_flag','enable_push_bitmap_to_fse_orc_reader=true');          -- Pushdown di pembaca ORC

3. Jalankan kueri equality atau IN, lalu konfirmasi bahwa indeks berlaku dengan EXPLAIN (ANALYZE).

   -- Kueri dan verifikasi
   EXPLAIN (ANALYZE)
   SELECT count(*) FROM EXT_DATABASE_NAME.EXT_SCHEMA_NAME.EXT_TABLE_NAME WHERE c_id = 1;

   Dalam rencana kueri, node Seq Scan tingkat paling bawah melaporkan bitmap_used=N, di mana N adalah jumlah predikat yang dilayani oleh indeks bitmap. scan_rows konvergen ke jumlah baris yang cocok alih-alih jumlah baris tabel penuh. Kedua sinyal ini berarti indeks berlaku. Contoh output:

   ->  Seq Scan on EXT_TABLE_NAME  (cost=0.00..5.03 rows=1000 width=1)
         Filter: (c_id = 1)
         Engine: FSE
         Foreign Table Type: DLF
       [id=1 split_count=1 rows=4(4/4/4) scan_rows=4(4/4/4) bitmap_used=1]

Gunakan Tabel Dinamis untuk refresh berkelanjutan

Tabel Dinamis secara otomatis memproses dan menyimpan hasil agregat dari satu atau beberapa tabel asing Paimon, dengan strategi refresh bawaan. Tabel asing MaxCompute dan tabel asing DLF telah didukung sebagai tabel dasar sejak V3.0.

Refresh penuh — mengganti semua data pada setiap siklus refresh:

CREATE DYNAMIC TABLE paimon_dt_table
WITH (
  auto_refresh_mode = 'full',
  freshness = '3 minutes'
) AS SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>;

Refresh bertahap — hanya memproses data baru atau yang berubah:

CREATE DYNAMIC TABLE paimon_dt_table_incremental
WITH (
  auto_refresh_mode = 'incremental',
  freshness = '3 minutes'
) AS SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>;

Refresh otomatis — secara otomatis memilih refresh penuh atau bertahap berdasarkan perubahan data:

CREATE DYNAMIC TABLE paimon_dt_table_auto
WITH (
  auto_refresh_mode = 'auto',
  freshness = '3 minutes'
) AS SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>;

Untuk detail selengkapnya, lihat Ikhtisar Tabel Dinamis.

INSERT INTO

Contoh berikut membuat tabel primary key Paimon dan memasukkan baris.

-- Buat tabel primary key Paimon
CREATE EXTERNAL TABLE <ext_database_name>.<ext_schema_name>.<ext_table_name> (
  id         BIGINT,
  customer_id BIGINT,
  item       TEXT,
  amount     FLOAT,
  dt         TEXT,
  PRIMARY KEY (id)
)
WITH (
  "table_format"  = 'paimon',
  "file_format"   = 'orc',
  "merge-engine"  = 'deduplicate',  -- Sesuaikan sesuai kebutuhan
  "bucket"        = '4'             -- Sesuaikan sesuai kebutuhan
);

-- Masukkan baris
INSERT INTO <ext_database_name>.<ext_schema_name>.<ext_table_name>
  (id, customer_id, item, amount, dt)
VALUES
  (1, 1001, 'apple',  3.50, '2025-09-10'),
  (2, 1002, 'banana', 2.00, '2025-09-10'),
  (3, 1003, 'orange', 4.20, '2025-09-11');

INSERT OVERWRITE

Contoh berikut membuat tabel append-only Paimon terpartisi dan menimpa partisi.

-- Buat tabel append-only Paimon terpartisi
CREATE EXTERNAL TABLE <ext_database_name>.<ext_schema_name>.<ext_table_name> (
  id     BIGINT,
  name   TEXT,
  amount FLOAT8,
  dt     TEXT
)
LOGICAL PARTITION BY LIST(dt)
WITH (
  "table_format" = 'paimon',
  "file_format"  = 'parquet',
  "merge-engine" = 'deduplicate',
  "bucket-key"   = 'id',
  "bucket"       = '2'
);

-- Timpa data
INSERT OVERWRITE <ext_database_name>.<ext_schema_name>.<ext_table_name>
  (id, name, amount, dt)
VALUES
  (1, 'Alice', 100.50, '2025-09-01'),
  (2, 'Bob',   200.00, '2025-09-01'),
  (3, 'Carol', 150.75, '2025-09-02');

UPDATE

UPDATE hanya didukung pada tabel primary key Paimon dengan Merge Engine deduplicate atau partial-update. Memperbarui kolom primary key tidak didukung.

UPDATE <ext_database_name>.<ext_schema_name>.<ext_table_name>
SET amount = 5
WHERE id = 1;

DELETE

DELETE hanya didukung pada tabel primary key Paimon dengan Merge Engine deduplicate atau partial-update. Untuk tabel partial-update, aktifkan properti partial-update.remove-record-on-delete sebelum menjalankan DELETE.

DELETE FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>
WHERE id = 2;