Hologres:Mengakses data Paimon dengan Katalog DLF

Gunakan Database Eksternal (direkomendasikan)

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

Gunakan server asing (legacy)

Pendekatan server asing tidak mendukung Time Travel, kueri cabang, atau pencermatan data. Gunakan Database Eksternal untuk fitur-fitur tersebut.

Langkah 1: Buat foreign server.

Untuk DLF V2.5 dan versi 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 sintaks, 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

Hologres V3.2 dan versi lebih baru mendukung pengkuerian 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 mengkueri 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 kedaluwarsa.

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

Kueri cabang Paimon

Hologres V3.2 dan versi lebih baru mendukung pengkuerian data dari cabang Paimon tertentu dan pengkuerian snapshot historis dalam suatu cabang.

Daftar cabang yang tersedia:

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

Kueri data terkini suatu cabang:

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 cabang fallback. Lihat Kelola cabang.

Kueri snapshot historis dalam suatu cabang:

-- 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>';

Mempercepat kueri dengan pencerminan tabel lake

Hologres V3.2 dan versi lebih baru mendukung pencermatan 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 mengurangi latensi kueri secara signifikan. Pencermatan penuh maupun parsial untuk tabel terpartisi didukung.

Untuk detail penyiapan, lihat Lake table mirroring.

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. Mulai dari V3.0, tabel asing MaxCompute dan tabel asing DLF didukung sebagai tabel dasar untuk Tabel Dinamis.

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 menyisipkan 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 jika diperlukan
  "bucket"        = '4'             -- Sesuaikan jika diperlukan
);

-- Sisipkan 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;