すべてのプロダクト
Search

このプロダクト

    E-MapReduce:Paimon カタログ

    ドキュメントセンター

    E-MapReduce:Paimon カタログ

    最終更新日:Nov 27, 2025

    Paimon カタログは、StarRocks バージョン 3.1 以降でサポートされている外部カタログです。このトピックでは、Paimon カタログの作成方法と表示方法について説明します。

    背景情報

    Paimon カタログを使用すると、次のことが可能になります。

    • Apache Paimon のデータを直接クエリする。

    • Paimon データベースとテーブルを作成し、Paimon にデータを書き込む。

    • INSERT INTO 機能を使用してデータを変換およびインポートする。

    Paimon のデータにアクセスするには、ご利用の StarRocks クラスターが Paimon クラスターのストレージシステムとメタデータサービスにアクセスできる必要があります。StarRocks は、次のストレージシステムとメタデータサービスをサポートしています。

    • Hadoop 分散ファイルシステム (HDFS) または Alibaba Cloud Object Storage Service (OSS)。

    • メタデータサービス。サポートされているメタデータサービスは、Data Lake Formation (DLF) 1.0 (レガシー)、DLF、Hive Metastore (HMS)、およびファイルシステムです。

    制限事項

    Paimon データベースの作成、Paimon テーブルの作成、および Paimon テーブルへのデータ挿入は、StarRocks 3.2.9 以降でのみサポートされます。

    Paimon カタログの作成

    構文

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

    パラメーター

    説明

    StarRocks の Paimon カタログは、ネイティブ Paimon API のカタログと 1 対 1 でマッピングされます。設定項目とその意味は同じです。

    パラメーターの構成は、Paimon クラスターが使用するメタデータの型によって異なります。

    HMS の使用

    • catalog_name: Paimon カタログの名前。このパラメーターは必須です。名前は次の要件を満たす必要があります:

      • 文字で始まり、文字 (a-z または A-Z)、数字 (0-9)、またはアンダースコア (_) のみを含めることができます。

      • 全長は 64 文字を超えることはできません。

    • comment: Paimon カタログの説明。このパラメーターはオプションです。

    • type: データソースの型。このパラメーターを paimon に設定します。

    • CatalogParams: StarRocks が Paimon クラスターのメタデータにアクセスするためのパラメーター。

      プロパティ

      必須

      説明

      paimon.catalog.type

      はい

      データソースの型。値は hive です。

      hive.metastore.uris

      はい

      HMS の URI。フォーマットは thrift://<HMS IP アドレス>:<ポート番号> です。デフォルトのポートは 9083 です。

      HMS が高可用性モードの場合は、コンマで区切って複数の HMS アドレスを指定できます。例: "thrift://<HMS IP アドレス 1>:<HMS ポート 1>,thrift://<HMS IP アドレス 2>:<HMS ポート 2>,thrift://<HMS IP アドレス 3>:<HMS ポート 3>"。

    • StorageCredentialParams: StarRocks が Paimon クラスターのファイルストレージにアクセスするためのパラメーター。

      • ストレージシステムとして HDFS を使用する場合、StorageCredentialParams を構成する必要はありません。

      • OSS または OSS-HDFS を使用する場合、StorageCredentialParams を構成する必要があります。

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

        パラメーターを次の表に示します。

        プロパティ

        説明

        aliyun.oss.endpoint

        OSS または OSS-HDFS のエンドポイント情報は次のとおりです。

        • OSS: バケットの [概要] ページに移動し、[アクセスポート] セクションでエンドポイントを見つけます。また、「OSS リージョンとエンドポイント」を参照して、対応するリージョンのエンドポイントを表示することもできます。例: oss-cn-hangzhou.aliyuncs.com。

        • OSS-HDFS: バケットの [概要] ページに移動し、[アクセスポート] セクションで [HDFS サービス] のエンドポイントを見つけます。たとえば、中国 (杭州) リージョンのエンドポイントは cn-hangzhou.oss-dls.aliyuncs.com です。

          重要

          このパラメーターを構成した後、EMR Serverless StarRocks コンソールの [インスタンス構成] ページに移動する必要もあります。次に、core-site.xml と jindosdk.cfg の [fs.oss.endpoint] パラメーターを aliyun.oss.endpoint の値と一致するように変更します。

    ファイルシステムの使用

    • catalog_name: Paimon カタログの名前。このパラメーターは必須です。名前は次の要件を満たす必要があります:

      • 文字で始まり、文字 (a-z または A-Z)、数字 (0-9)、またはアンダースコア (_) のみを含めることができます。

      • 全長は 64 文字を超えることはできません。

    • comment: Paimon カタログの説明。このパラメーターはオプションです。

    • type: データソースの型。このパラメーターを paimon に設定します。

    • CatalogParams: StarRocks が Paimon クラスターのメタデータにアクセスするためのパラメーター。

      プロパティ

      必須

      説明

      paimon.catalog.type

      はい

      データソースの型。値は filesystem です。

      paimon.catalog.warehouse

      はい

      Paimon データが保存されているウェアハウスのストレージパス。HDFS、OSS、および OSS-HDFS がサポートされています。OSS または OSS-HDFS のフォーマットは oss://<yourBucketName>/<yourPath> です。

      重要

      ウェアハウスとして OSS または OSS-HDFS を使用する場合、aliyun.oss.endpoint パラメーターを構成する必要があります。詳細については、「StorageCredentialParams: StarRocks が Paimon クラスターのファイルストレージにアクセスするためのパラメーター。」をご参照ください。

    • StorageCredentialParams: StarRocks が Paimon クラスターのファイルストレージにアクセスするためのパラメーター。

      • ストレージシステムとして HDFS を使用する場合、StorageCredentialParams を構成する必要はありません。

      • OSS または OSS-HDFS を使用する場合、StorageCredentialParams を構成する必要があります。

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

        パラメーターを次の表に示します。

        プロパティ

        説明

        aliyun.oss.endpoint

        OSS または OSS-HDFS のエンドポイント情報は次のとおりです。

        • OSS: バケットの [概要] ページに移動し、[アクセスポート] セクションでエンドポイントを見つけます。また、「OSS リージョンとエンドポイント」を参照して、対応するリージョンのエンドポイントを表示することもできます。例: oss-cn-hangzhou.aliyuncs.com。

        • OSS-HDFS: バケットの [概要] ページに移動し、[アクセスポート] セクションで [HDFS サービス] のエンドポイントを見つけます。たとえば、中国 (杭州) リージョンのエンドポイントは cn-hangzhou.oss-dls.aliyuncs.com です。

          重要

          このパラメーターを構成した後、EMR Serverless StarRocks コンソールの [インスタンス構成] ページに移動する必要もあります。次に、core-site.xml と jindosdk.cfg の [fs.oss.endpoint] パラメーターを aliyun.oss.endpoint の値と一致するように変更します。

    DLF 1.0 (レガシー) の使用

    • catalog_name: Paimon カタログの名前。このパラメーターは必須です。名前は次の要件を満たす必要があります:

      • 文字で始まり、文字 (a-z または A-Z)、数字 (0-9)、またはアンダースコア (_) のみを含めることができます。

      • 全長は 64 文字を超えることはできません。

    • comment: Paimon カタログの説明。このパラメーターはオプションです。

    • type: データソースの型。このパラメーターを paimon に設定します。

    • CatalogParams: StarRocks が Paimon クラスターのメタデータにアクセスするためのパラメーター。

      プロパティ

      必須

      説明

      paimon.catalog.type

      はい

      データソースの型。値は dlf です。

      paimon.catalog.warehouse

      はい

      Paimon データが保存されているウェアハウスのストレージパス。HDFS、OSS、および OSS-HDFS がサポートされています。OSS または OSS-HDFS のフォーマットは oss://<yourBucketName>/<yourPath> です。

      重要

      ウェアハウスとして OSS または OSS-HDFS を使用する場合、aliyun.oss.endpoint パラメーターを構成する必要があります。詳細については、「StorageCredentialParams: StarRocks が Paimon クラスターのファイルストレージにアクセスするためのパラメーター。」をご参照ください。

      dlf.catalog.id

      いいえ

      DLF 内の既存のデータカタログの ID。dlf.catalog.id パラメーターを構成しない場合、システムはデフォルトの DLF カタログを使用します。

    • StorageCredentialParams: StarRocks が Paimon クラスターのファイルストレージにアクセスするためのパラメーター。

      • ストレージシステムとして HDFS を使用する場合、StorageCredentialParams を構成する必要はありません。

      • OSS または OSS-HDFS を使用する場合、StorageCredentialParams を構成する必要があります。

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

        パラメーターを次の表に示します。

        プロパティ

        説明

        aliyun.oss.endpoint

        OSS または OSS-HDFS のエンドポイント情報は次のとおりです。

        • OSS: バケットの [概要] ページに移動し、[アクセスポート] セクションでエンドポイントを見つけます。また、「OSS リージョンとエンドポイント」を参照して、対応するリージョンのエンドポイントを表示することもできます。例: oss-cn-hangzhou.aliyuncs.com。

        • OSS-HDFS: バケットの [概要] ページに移動し、[アクセスポート] セクションで [HDFS サービス] のエンドポイントを見つけます。たとえば、中国 (杭州) リージョンのエンドポイントは cn-hangzhou.oss-dls.aliyuncs.com です。

          重要

          このパラメーターを構成した後、EMR Serverless StarRocks コンソールの [インスタンス構成] ページに移動する必要もあります。次に、core-site.xml と jindosdk.cfg の [fs.oss.endpoint] パラメーターを aliyun.oss.endpoint の値と一致するように変更します。

    DLF の使用

    • catalog_name: Paimon カタログの名前。このパラメーターは必須です。名前は次の要件を満たす必要があります:

      • 文字で始まり、文字 (a-z または A-Z)、数字 (0-9)、またはアンダースコア (_) のみを含めることができます。

      • 全長は 64 文字を超えることはできません。

    • comment: Paimon カタログの説明。このパラメーターはオプションです。

    • type: データソースの型。このパラメーターを paimon に設定します。

    • CatalogParams: StarRocks が Paimon クラスターのメタデータにアクセスするためのパラメーター。

      重要

      DLF を使用する場合、構成済みの Resource Access Management (RAM) ユーザーを使用して StarRocks Manager で操作を実行する必要があります。詳細については、「DLF カタログの使用」をご参照ください。

      パラメーター

      必須

      説明

      <catalog_name>

      はい

      DLF データカタログの名前。例: dlf_catalog。

      type

      はい

      カタログタイプです。このパラメーターを静的フィールド paimon に設定します。

      uri

      はい

      DLF の REST API アドレス。

      フォーマットは http://<VPC エンドポイント> です。<VPC エンドポイント> は、VPC アクセス用に指定されたリージョンにある DLF サービスのエンドポイントです。

      例: http://cn-hangzhou-vpc.dlf.aliyuncs.com。

      paimon.catalog.type

      はい

      Paimon カタログの型。このパラメーターを静的フィールド rest に設定します。

      paimon.catalog.warehouse

      はい

      Paimon カタログの名前。Data Lake Formation コンソールの [データカタログ] ページから取得できます。

      token.provider

      はい

      REST サービスプロバイダー。このパラメーターを静的フィールド dlf に設定します。

    • StorageCredentialParams: StarRocks が Paimon クラスターのファイルストレージにアクセスするためのパラメーター。

      • ストレージシステムとして HDFS を使用する場合、StorageCredentialParams を構成する必要はありません。

      • OSS または OSS-HDFS を使用する場合、StorageCredentialParams を構成する必要があります。

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

        パラメーターを次の表に示します。

        プロパティ

        説明

        aliyun.oss.endpoint

        OSS または OSS-HDFS のエンドポイント情報は次のとおりです。

        • OSS: バケットの [概要] ページに移動し、[アクセスポート] セクションでエンドポイントを見つけます。また、「OSS リージョンとエンドポイント」を参照して、対応するリージョンのエンドポイントを表示することもできます。例: oss-cn-hangzhou.aliyuncs.com。

        • OSS-HDFS: バケットの [概要] ページに移動し、[アクセスポート] セクションで [HDFS サービス] のエンドポイントを見つけます。たとえば、中国 (杭州) リージョンのエンドポイントは cn-hangzhou.oss-dls.aliyuncs.com です。

          重要

          このパラメーターを構成した後、EMR Serverless StarRocks コンソールの [インスタンス構成] ページに移動する必要もあります。次に、core-site.xml と jindosdk.cfg の [fs.oss.endpoint] パラメーターを aliyun.oss.endpoint の値と一致するように変更します。

    例

    次の例は、paimon_catalog という名前の Paimon カタログを作成して Paimon データソースのデータをクエリする方法を示しています。

    HMS の使用

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

    ファイルシステムの使用

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

    DLF 1.0 (レガシー) の使用

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

    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"
);

    Paimon カタログの表示

    • SHOW CATALOGS を実行して、現在の StarRocks クラスター内のすべてのカタログを表示できます。

      SHOW CATALOGS;

    • SHOW CREATE CATALOG を実行して、外部カタログの作成文を表示できます。

      SHOW CREATE CATALOG paimon_catalog;

    Paimon カタログの削除​

    DROP CATALOG を実行して、外部カタログを削除できます。例えば、paimon_catalog という名前の Paimon カタログを削除するには、次のコマンドを実行します。

    DROP CATALOG paimon_catalog;

    Paimon データベースの作成

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

    Paimon テーブルの作成

    構文

    CREATE TABLE IF NOT EXISTS <catalog_name>.<database_name>.<table_name>
(
   id STRING,
   name STRING,
   day INT
)
PRIMARY KEY (id, day)  -- 追記専用テーブルを作成する場合はオプション --
PARTITION BY (`day`) -- 非パーティションテーブルを作成する場合はオプション --
PROPERTIES (  -- PROPERTIES を指定しない場合はオプション --
  key = value
);

    パラメーター

    一般的な `PROPERTIES` パラメーターを次の表に示します。

    キー

    説明

    file.format

    テーブルのデータストレージフォーマットを定義します。デフォルトは parquet です。

    bucket

    テーブルのバケット数を設定します。データ分布とクエリの最適化に使用されます。デフォルトは -1 で、バケット化が使用されないことを意味します。

    bucket_key

    レコードをバケットに分散するために使用される列を指定します。

    制限事項

    • パーティションテーブルを作成する場合、すべてのパーティションキー列は列定義の最後に配置する必要があります。

    • パーティションテーブルの場合、すべてのパーティションキー列をプライマリキー定義に含める必要があります。

    • 指定された bucket_key は、パーティションキーまたはプライマリキーの一部にすることはできません。

    例

    CREATE TABLE dlf_catalog.sr_dlf_db.ads_age_pvalue_analytics(
    final_gender_code STRING COMMENT '性別',
    age_level STRING COMMENT '年齢レベル',
    pvalue_level STRING COMMENT '消費レベル',
    clicks INT COMMENT 'クリック数',
    total_behaviors INT COMMENT '総行動数'
);

    Paimon テーブルスキーマの表示

    次の方法で Paimon テーブルのスキーマを表示できます。

    • テーブルスキーマの表示

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

    • CREATE TABLE 文からテーブルスキーマとファイルストレージの場所を表示

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

    Paimon テーブル内のデータのクエリ

    • Paimon カタログ内のテーブルのデータをクエリするには、次の手順を実行します。

      1. SHOW DATABASES を実行して、指定された Paimon カタログ内のデータベースを表示します。

        SHOW DATABASES FROM <catalog_name>;

      2. SET CATALOG を実行して、現在のセッションで目的のカタログに切り替えます。

        SET CATALOG <catalog_name>;

        次に、USE を実行して、現在のセッションで目的のデータベースを指定します。

        USE <db_name>;

        または、USE を実行して、セッションをターゲットカタログ内の特定のデータベースに直接切り替えることもできます。

        USE <catalog_name>.<db_name>;

      3. SELECT 文を実行して、ターゲットデータベース内のターゲットテーブルをクエリします。

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

    • SELECT 文でカタログとデータベースを指定して、ターゲットテーブルを直接クエリすることもできます。

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

    Paimon へのデータ書き込み

    Paimon テーブルへの書き込み

    説明

    • StarRocks では、データはバッチ (Batch Write) で Paimon テーブルに書き込まれます。Paimon の制限により、バケットモードが HASH_DYNAMIC または CROSS_PARTITION のテーブルにデータを書き込むことはできません。典型的なシナリオは、プライマリキーテーブルへの書き込みです。テーブル作成文で `bucket` プロパティを指定しない場合、デフォルト値は -1 (動的バケットモード) となり、書き込み操作が妨げられます。

    • Paimon ソフトウェア開発キット (SDK) では、書き込むデータのパーティションキー列またはプライマリキー列を null にすることはできません。StarRocks は Paimon テーブルにデータを書き込む前にデータを事前チェックしません。したがって、null 値を書き込もうとすると例外がスローされます。

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

    たとえば、次のデータを `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);

    Paimon データを内部テーブルにインポートする

    StarRocks に olap_tbl という名前の OLAP テーブルが存在すると仮定します。次のように、Paimon テーブルからデータを変換し、StarRocks テーブル olap_tbl にインポートできます。

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

    参照

    Paimon の詳細については、「Paimon の概要」をご参照ください。