全部产品
Search

搜索本产品

    E-MapReduce：Katalog Paimon

    文档中心

    E-MapReduce：Katalog Paimon

    更新时间：Jan 22, 2026

    Katalog Paimon adalah katalog eksternal yang didukung oleh StarRocks sejak versi 3.1. Topik ini menjelaskan cara membuat dan melihat katalog Paimon.

    Informasi latar belakang

    Katalog Paimon memungkinkan Anda:

    • Menjalankan kueri data secara langsung di Apache Paimon.

    • Membuat database dan tabel Paimon, serta menulis data ke Paimon.

    • Menggunakan fitur INSERT INTO untuk mentransformasi dan mengimpor data.

    Untuk mengakses data di Paimon, kluster StarRocks Anda harus dapat mengakses sistem penyimpanan dan layanan metadata dari kluster Paimon. StarRocks mendukung sistem penyimpanan dan layanan metadata berikut:

    • Hadoop Distributed File System (HDFS) atau Alibaba Cloud Object Storage Service (OSS).

    • Layanan metadata. Layanan metadata yang didukung adalah Data Lake Formation (DLF) 1.0 (Legacy), DLF, Hive Metastore (HMS), dan File System.

    Batasan

    Pembuatan database Paimon, pembuatan tabel Paimon, dan penyisipan data ke dalam tabel Paimon hanya didukung di StarRocks 3.2.9 dan versi yang lebih baru.

    Buat katalog Paimon

    Sintaksis

    CREATE EXTERNAL CATALOG <catalog_name>
[COMMENT <comment>]
PROPERTIES
(
    "type" = "paimon",
    CatalogParams,
    StorageCredentialParams
);

    Parameter

    Catatan

    Katalog Paimon di StarRocks memiliki pemetaan satu-ke-satu dengan katalog di native Paimon API. Item konfigurasi dan maknanya identik.

    Konfigurasi parameter bervariasi tergantung pada jenis metadata yang digunakan oleh kluster Paimon.

    Gunakan HMS

    • catalog_name: Nama katalog Paimon. Parameter ini wajib diisi. Nama harus memenuhi persyaratan berikut:

      • Harus dimulai dengan huruf dan hanya boleh berisi huruf (a–z atau A–Z), angka (0–9), atau garis bawah (_).

      • Panjang total tidak boleh melebihi 64 karakter.

    • comment: Deskripsi katalog Paimon. Parameter ini opsional.

    • type: Jenis sumber data. Atur parameter ini ke paimon.

    • CatalogParams: Parameter agar StarRocks dapat mengakses metadata kluster Paimon.

      Property

      Wajib

      Deskripsi

      paimon.catalog.type

      Ya

      Jenis sumber data. Nilainya adalah hive.

      hive.metastore.uris

      Ya

      URI HMS. Formatnya adalah thrift://<alamat IP HMS>:<nomor port>. Port default adalah 9083.

      Jika HMS Anda berada dalam Mode Ketersediaan Tinggi, Anda dapat menentukan beberapa alamat HMS yang dipisahkan dengan koma, misalnya, "thrift://<alamat IP HMS 1>:<port HMS 1>,thrift://<alamat IP HMS 2>:<port HMS 2>,thrift://<alamat IP HMS 3>:<port HMS 3>".

    • StorageCredentialParams: Parameter agar StarRocks dapat mengakses penyimpanan file kluster Paimon.

      • Jika Anda menggunakan HDFS sebagai sistem penyimpanan, Anda tidak perlu mengonfigurasi StorageCredentialParams.

      • Jika Anda menggunakan OSS atau OSS-HDFS, Anda harus mengonfigurasi StorageCredentialParams.

        "aliyun.oss.endpoint" = "<YourAliyunOSSEndpoint>"

        Parameter dijelaskan dalam tabel berikut.

        Property

        Deskripsi

        aliyun.oss.endpoint

        Informasi endpoint untuk OSS atau OSS-HDFS adalah sebagai berikut:

        • OSS: Buka halaman Overview bucket Anda dan temukan endpoint di bagian Access Ports. Anda juga dapat melihat wilayah dan endpoint OSS untuk melihat endpoint wilayah yang sesuai. Misalnya, oss-cn-hangzhou.aliyuncs.com.

        • OSS-HDFS: Buka halaman Overview bucket Anda dan temukan endpoint untuk HDFS Service di bagian Access Ports. Misalnya, endpoint untuk wilayah China (Hangzhou) adalah cn-hangzhou.oss-dls.aliyuncs.com.

          Penting

          Setelah mengonfigurasi parameter ini, Anda juga harus membuka halaman Instance Configuration di konsol EMR Serverless StarRocks. Kemudian, ubah parameter fs.oss.endpoint di core-site.xml dan jindosdk.cfg agar konsisten dengan nilai aliyun.oss.endpoint.

    Gunakan filesystem

    • catalog_name: Nama katalog Paimon. Parameter ini wajib diisi. Nama harus memenuhi persyaratan berikut:

      • Harus dimulai dengan huruf dan hanya boleh berisi huruf (a–z atau A–Z), angka (0–9), atau garis bawah (_).

      • Panjang total tidak boleh melebihi 64 karakter.

    • comment: Deskripsi katalog Paimon. Parameter ini opsional.

    • type: Jenis sumber data. Atur parameter ini ke paimon.

    • CatalogParams: Parameter agar StarRocks dapat mengakses metadata kluster Paimon.

      Property

      Wajib

      Deskripsi

      paimon.catalog.type

      Ya

      Jenis sumber data. Nilainya adalah filesystem.

      paimon.catalog.warehouse

      Ya

      Jalur penyimpanan warehouse tempat data Paimon disimpan. HDFS, OSS, dan OSS-HDFS didukung. Format untuk OSS atau OSS-HDFS adalah oss://<namaBucketAnda>/<jalurAnda>.

      Penting

      Jika Anda menggunakan OSS atau OSS-HDFS sebagai warehouse, Anda harus mengonfigurasi parameter aliyun.oss.endpoint. Untuk informasi selengkapnya, lihat StorageCredentialParams: Parameter agar StarRocks dapat mengakses penyimpanan file kluster Paimon.

    • StorageCredentialParams: Parameter agar StarRocks dapat mengakses penyimpanan file kluster Paimon.

      • Jika Anda menggunakan HDFS sebagai sistem penyimpanan, Anda tidak perlu mengonfigurasi StorageCredentialParams.

      • Jika Anda menggunakan OSS atau OSS-HDFS, Anda harus mengonfigurasi StorageCredentialParams.

        "aliyun.oss.endpoint" = "<YourAliyunOSSEndpoint>"

        Parameter dijelaskan dalam tabel berikut.

        Property

        Deskripsi

        aliyun.oss.endpoint

        Informasi endpoint untuk OSS atau OSS-HDFS adalah sebagai berikut:

        • OSS: Buka halaman Overview bucket Anda dan temukan endpoint di bagian Access Ports. Anda juga dapat melihat wilayah dan endpoint OSS untuk melihat endpoint wilayah yang sesuai. Misalnya, oss-cn-hangzhou.aliyuncs.com.

        • OSS-HDFS: Buka halaman Overview bucket Anda dan temukan endpoint untuk HDFS Service di bagian Access Ports. Misalnya, endpoint untuk wilayah China (Hangzhou) adalah cn-hangzhou.oss-dls.aliyuncs.com.

          Penting

          Setelah mengonfigurasi parameter ini, Anda juga harus membuka halaman Instance Configuration di konsol EMR Serverless StarRocks. Kemudian, ubah parameter fs.oss.endpoint di core-site.xml dan jindosdk.cfg agar konsisten dengan nilai aliyun.oss.endpoint.

    Gunakan DLF 1.0 (Legacy)

    • catalog_name: Nama katalog Paimon. Parameter ini wajib diisi. Nama harus memenuhi persyaratan berikut:

      • Harus dimulai dengan huruf dan hanya boleh berisi huruf (a–z atau A–Z), angka (0–9), atau garis bawah (_).

      • Panjang total tidak boleh melebihi 64 karakter.

    • comment: Deskripsi katalog Paimon. Parameter ini opsional.

    • type: Jenis sumber data. Atur parameter ini ke paimon.

    • CatalogParams: Parameter agar StarRocks dapat mengakses metadata kluster Paimon.

      Property

      Wajib

      Deskripsi

      paimon.catalog.type

      Ya

      Jenis sumber data. Nilainya adalah dlf.

      paimon.catalog.warehouse

      Ya

      Jalur penyimpanan warehouse tempat data Paimon disimpan. HDFS, OSS, dan OSS-HDFS didukung. Format untuk OSS atau OSS-HDFS adalah oss://<namaBucketAnda>/<jalurAnda>.

      Penting

      Jika Anda menggunakan OSS atau OSS-HDFS sebagai warehouse, Anda harus mengonfigurasi parameter aliyun.oss.endpoint. Untuk informasi selengkapnya, lihat StorageCredentialParams: Parameter agar StarRocks dapat mengakses penyimpanan file kluster Paimon.

      dlf.catalog.id

      Tidak

      ID katalog data yang sudah ada di DLF. Jika Anda tidak mengonfigurasi parameter dlf.catalog.id, sistem akan menggunakan katalog DLF default.

    • StorageCredentialParams: Parameter agar StarRocks dapat mengakses penyimpanan file kluster Paimon.

      • Jika Anda menggunakan HDFS sebagai sistem penyimpanan, Anda tidak perlu mengonfigurasi StorageCredentialParams.

      • Jika Anda menggunakan OSS atau OSS-HDFS, Anda harus mengonfigurasi StorageCredentialParams.

        "aliyun.oss.endpoint" = "<YourAliyunOSSEndpoint>"

        Parameter dijelaskan dalam tabel berikut.

        Property

        Deskripsi

        aliyun.oss.endpoint

        Informasi endpoint untuk OSS atau OSS-HDFS adalah sebagai berikut:

        • OSS: Buka halaman Overview bucket Anda dan temukan endpoint di bagian Access Ports. Anda juga dapat melihat wilayah dan endpoint OSS untuk melihat endpoint wilayah yang sesuai. Misalnya, oss-cn-hangzhou.aliyuncs.com.

        • OSS-HDFS: Buka halaman Overview bucket Anda dan temukan endpoint untuk HDFS Service di bagian Access Ports. Misalnya, endpoint untuk wilayah China (Hangzhou) adalah cn-hangzhou.oss-dls.aliyuncs.com.

          Penting

          Setelah mengonfigurasi parameter ini, Anda juga harus membuka halaman Instance Configuration di konsol EMR Serverless StarRocks. Kemudian, ubah parameter fs.oss.endpoint di core-site.xml dan jindosdk.cfg agar konsisten dengan nilai aliyun.oss.endpoint.

    Gunakan DLF

    • catalog_name: Nama katalog Paimon. Parameter ini wajib diisi. Nama harus memenuhi persyaratan berikut:

      • Harus dimulai dengan huruf dan hanya boleh berisi huruf (a–z atau A–Z), angka (0–9), atau garis bawah (_).

      • Panjang total tidak boleh melebihi 64 karakter.

    • comment: Deskripsi katalog Paimon. Parameter ini opsional.

    • type: Jenis sumber data. Atur parameter ini ke paimon.

    • CatalogParams: Parameter agar StarRocks dapat mengakses metadata kluster Paimon.

      Penting

      Jika Anda menggunakan DLF, Anda harus menggunakan Pengguna Resource Access Management (RAM) yang telah dikonfigurasi untuk melakukan operasi di StarRocks Manager. Untuk informasi selengkapnya, lihat Menggunakan katalog DLF.

      Parameter

      Wajib

      Deskripsi

      <catalog_name>

      Ya

      Nama katalog data DLF, misalnya, dlf_catalog.

      type

      Ya

      Jenis katalog. Atur parameter ini ke bidang statis paimon.

      uri

      Ya

      Alamat REST API DLF.

      Formatnya adalah http://<titik akhir VPC>. <titik akhir VPC> adalah titik akhir layanan DLF di wilayah tertentu untuk akses VPC.

      Misalnya, http://cn-hangzhou-vpc.dlf.aliyuncs.com.

      paimon.catalog.type

      Ya

      Jenis katalog Paimon. Atur parameter ini ke bidang statis rest.

      paimon.catalog.warehouse

      Ya

      Nama katalog Paimon. Anda dapat memperolehnya dari halaman Data Catalog di konsol Data Lake Formation.

      token.provider

      Ya

      Penyedia layanan REST. Atur parameter ini ke bidang statis dlf.

    • StorageCredentialParams: Parameter agar StarRocks dapat mengakses penyimpanan file kluster Paimon.

      • Jika Anda menggunakan HDFS sebagai sistem penyimpanan, Anda tidak perlu mengonfigurasi StorageCredentialParams.

      • Jika Anda menggunakan OSS atau OSS-HDFS, Anda harus mengonfigurasi StorageCredentialParams.

        "aliyun.oss.endpoint" = "<YourAliyunOSSEndpoint>"

        Parameter dijelaskan dalam tabel berikut.

        Property

        Deskripsi

        aliyun.oss.endpoint

        Informasi endpoint untuk OSS atau OSS-HDFS adalah sebagai berikut:

        • OSS: Buka halaman Overview bucket Anda dan temukan endpoint di bagian Access Ports. Anda juga dapat melihat wilayah dan endpoint OSS untuk melihat endpoint wilayah yang sesuai. Misalnya, oss-cn-hangzhou.aliyuncs.com.

        • OSS-HDFS: Buka halaman Overview bucket Anda dan temukan endpoint untuk HDFS Service di bagian Access Ports. Misalnya, endpoint untuk wilayah China (Hangzhou) adalah cn-hangzhou.oss-dls.aliyuncs.com.

          Penting

          Setelah mengonfigurasi parameter ini, Anda juga harus membuka halaman Instance Configuration di konsol EMR Serverless StarRocks. Kemudian, ubah parameter fs.oss.endpoint di core-site.xml dan jindosdk.cfg agar konsisten dengan nilai aliyun.oss.endpoint.

    Contoh

    Contoh berikut menunjukkan cara membuat katalog Paimon bernama paimon_catalog untuk menjalankan kueri data di sumber data Paimon.

    Gunakan HMS

    CREATE EXTERNAL CATALOG paimon_catalog
PROPERTIES
(
    "type" = "paimon",
    "paimon.catalog.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083"
);

    Gunakan filesystem

    CREATE EXTERNAL CATALOG paimon_catalog
PROPERTIES
(
    "type" = "paimon",
    "paimon.catalog.type" = "filesystem",
    "paimon.catalog.warehouse" = "oss://<namaBucketAnda>/<jalurAnda>",
    "aliyun.oss.endpoint" = "cn-hangzhou.oss-dls.aliyuncs.com"
);

    Gunakan DLF 1.0 (Legacy)

    CREATE EXTERNAL CATALOG paimon_catalog
PROPERTIES
(
    "type" = "paimon",
    "paimon.catalog.type" = "dlf",
    "paimon.catalog.warehouse" = "oss://<namaBucketAnda>/<jalurAnda>",
    "dlf.catalog.id" = "paimon_dlf_test"
);

    Gunakan DLF

    CREATE EXTERNAL CATALOG dlf_catalog
PROPERTIES
(
   "type"= "paimon",
   "uri" = "http://cn-hangzhou-vpc.dlf.aliyuncs.com",
   "paimon.catalog.type" = "rest",
   "paimon.catalog.warehouse" = "test_paimon",
   "token.provider" = "dlf"
);

    Lihat katalog Paimon

    • Anda dapat menjalankan SHOW CATALOGS untuk melihat semua katalog di kluster StarRocks saat ini.

      SHOW CATALOGS;

    • Anda dapat menjalankan SHOW CREATE CATALOG untuk melihat pernyataan pembuatan katalog eksternal.

      SHOW CREATE CATALOG paimon_catalog;

    Hapus katalog Paimon​

    Anda dapat menjalankan DROP CATALOG untuk menghapus katalog eksternal. Misalnya, untuk menghapus katalog Paimon bernama paimon_catalog, jalankan perintah berikut:

    DROP CATALOG paimon_catalog;

    Buat database Paimon

    CREATE DATABASE IF NOT EXISTS <catalog_name>.<database_name>;

    Buat tabel Paimon

    Sintaksis

    CREATE TABLE IF NOT EXISTS <catalog_name>.<database_name>.<table_name>
(
   id STRING,
   name STRING,
   day INT
)
PRIMARY KEY (id, day)  -- Opsional untuk membuat tabel append-only --
PARTITION BY (`day`) -- Opsional untuk membuat tabel non-partisi --
PROPERTIES (  -- Opsional jika tidak ada PROPERTIES yang ditentukan --
  key = value
);

    Parameter

    Parameter umum `PROPERTIES` dijelaskan dalam tabel berikut.

    Key

    Deskripsi

    file.format

    Menentukan format penyimpanan data untuk tabel. Nilai default adalah parquet.

    bucket

    Menentukan jumlah bucket untuk tabel, digunakan untuk distribusi data dan optimasi kueri. Nilai default adalah -1, yang berarti bucketing tidak digunakan.

    bucket_key

    Menentukan kolom yang digunakan untuk mendistribusikan catatan ke dalam bucket.

    Batasan

    • Saat membuat tabel partisi, semua kolom kunci partisi harus ditempatkan di akhir definisi kolom.

    • Untuk tabel partisi, semua kolom kunci partisi harus disertakan dalam definisi kunci primer.

    • bucket_key yang ditentukan tidak boleh menjadi bagian dari kunci partisi atau kunci primer.

    Contoh

    CREATE TABLE dlf_catalog.sr_dlf_db.ads_age_pvalue_analytics(
    final_gender_code STRING COMMENT 'gender',
    age_level STRING COMMENT 'age_level',
    pvalue_level STRING COMMENT 'consumption_level',
    clicks INT COMMENT 'clicks',
    total_behaviors INT COMMENT 'total_behaviors'
);

    Lihat skema tabel Paimon

    Anda dapat melihat skema tabel Paimon dengan cara berikut.

    • Lihat skema tabel

      DESC[RIBE] <catalog_name>.<database_name>.<table_name>;

    • Lihat skema tabel dan lokasi penyimpanan file dari pernyataan CREATE TABLE

      SHOW CREATE TABLE <catalog_name>.<database_name>.<table_name>;

    Kueri data di tabel Paimon

    • Untuk menjalankan kueri data di tabel dalam katalog Paimon, lakukan langkah-langkah berikut:

      1. Jalankan SHOW DATABASES untuk melihat database di katalog Paimon yang ditentukan.

        SHOW DATABASES FROM <catalog_name>;

      2. Jalankan SET CATALOG untuk beralih ke katalog yang diinginkan untuk session saat ini.

        SET CATALOG <catalog_name>;

        Kemudian, jalankan USE untuk menentukan database yang diinginkan untuk session saat ini.

        USE <db_name>;

        Atau, Anda dapat menjalankan USE untuk langsung beralih session ke database tertentu dalam katalog target.

        USE <catalog_name>.<db_name>;

      3. Jalankan pernyataan SELECT untuk menjalankan kueri tabel target di database target.

        SELECT count(*) FROM <table_name> LIMIT 10;

    • Anda juga dapat langsung menjalankan kueri tabel target dengan menentukan katalog dan database dalam pernyataan SELECT.

      SELECT * FROM <catalog_name>.<database_name>.<table_name>;

    Tulis data ke Paimon

    Tulis ke tabel Paimon

    Catatan

    • Di StarRocks, data ditulis ke tabel Paimon secara batch (Batch Write). Karena keterbatasan Paimon, Anda tidak dapat menulis data ke tabel yang mode bucket-nya HASH_DYNAMIC atau CROSS_PARTITION. Skenario umum adalah menulis ke tabel kunci primer. Jika Anda tidak menentukan properti `bucket` dalam pernyataan pembuatan tabel, nilai default-nya adalah -1 (Dynamic Bucket Mode), yang mencegah operasi penulisan.

    • Kit pengembangan perangkat lunak (SDK) Paimon mensyaratkan bahwa kolom kunci partisi atau kunci primer dalam data yang akan ditulis tidak boleh bernilai null. StarRocks tidak melakukan pemeriksaan awal terhadap data sebelum menulisnya ke tabel Paimon. Oleh karena itu, pengecualian akan dilemparkan jika Anda mencoba menulis nilai null.

    INSERT INTO <catalog_name>.<database_name>.<table_name> (column1, column2, ...) VALUES (value1, value2, ...);

    Misalnya, Anda dapat menyisipkan data berikut langsung ke tabel `ads_age_pvalue_analytics`.

    INSERT INTO dlf_catalog.sr_dlf_db.ads_age_pvalue_analytics (final_gender_code, age_level, pvalue_level, clicks, total_behaviors)
VALUES 
('M', '18-24', 'Low', 1500, 2500),
('F', '25-34', 'Medium', 2200, 3300),
('M', '35-44', 'High', 2800, 4000);

    Impor data Paimon ke tabel internal

    Asumsikan bahwa tabel OLAP bernama olap_tbl ada di StarRocks. Anda dapat mentransformasi data dari tabel Paimon dan mengimpornya ke tabel StarRocks olap_tbl sebagai berikut:

    INSERT INTO default_catalog.olap_db.olap_tbl SELECT * FROM <paimon_catalog>.<db_name>.<table_name>;

    Referensi

    Untuk informasi selengkapnya tentang Paimon, lihat Ikhtisar Paimon.