メインコンテンツまでスキップ
バージョン: Stable-3.3

BROKER LOAD

説明​

StarRocks は、MySQL ベースのロード方法である Broker Load を提供します。ロードジョブを送信すると、StarRocks は非同期でジョブを実行します。SELECT * FROM information_schema.loads を使用してジョブの結果を照会できます。この機能は v3.1 以降でサポートされています。背景情報、原則、サポートされているデータファイル形式、単一テーブルロードと複数テーブルロードの実行方法、ジョブ結果の表示方法についての詳細は、loading overview を参照してください。

StarRocks テーブルにデータを ロード するには、その StarRocks テーブルに対して INSERT 権限を持つユーザーである必要があります。INSERT 権限を持っていない場合は、 GRANT に記載されている手順に従って、StarRocks クラスターに接続するために使用するユーザーに INSERT 権限を付与してください。構文は GRANT INSERT ON TABLE <table_name> IN DATABASE <database_name> TO { ROLE <role_name> | USER <user_identity>} です。

構文​

LOAD LABEL [<database_name>.]<label_name>
(
    data_desc[, data_desc ...]
)
WITH BROKER
(
    StorageCredentialParams
)
[PROPERTIES
(
    opt_properties
)
]

StarRocks では、いくつかのリテラルが SQL 言語によって予約キーワードとして使用されていることに注意してください。これらのキーワードを SQL ステートメントで直接使用しないでください。SQL ステートメントでそのようなキーワードを使用する場合は、バッククォート (`) で囲んでください。Keywords を参照してください。

パラメーター​

database_name と label_name​

label_name はロードジョブのラベルを指定します。命名規則については、System limits を参照してください。

database_name は、オプションで、宛先テーブルが属するデータベースの名前を指定します。

各ロードジョブには、データベース全体で一意のラベルがあります。ロードジョブのラベルを使用して、ロードジョブの実行ステータスを表示し、同じデータを繰り返しロードするのを防ぐことができます。ロードジョブが FINISHED 状態になると、そのラベルは再利用できません。CANCELLED 状態になったロードジョブのラベルのみが再利用可能です。ほとんどの場合、ロードジョブのラベルは、そのロードジョブを再試行して同じデータをロードするために再利用され、Exactly-Once セマンティクスを実装します。

ラベルの命名規則については、System limits を参照してください。

data_desc​

ロードするデータのバッチの説明です。各 data_desc ディスクリプタは、データソース、ETL 関数、宛先 StarRocks テーブル、および宛先パーティションなどの情報を宣言します。

Broker Load は、一度に複数のデータファイルをロードすることをサポートしています。1 つのロードジョブで、複数の data_desc ディスクリプタを使用してロードしたい複数のデータファイルを宣言するか、1 つの data_desc ディスクリプタを使用して、すべてのデータファイルをロードしたいファイルパスを宣言することができます。Broker Load は、複数のデータファイルをロードする各ロードジョブのトランザクションの原子性を保証することもできます。原子性とは、1 つのロードジョブで複数のデータファイルをロードする際に、すべて成功または失敗しなければならないことを意味します。いくつかのデータファイルのロードが成功し、他のファイルのロードが失敗することはありません。

data_desc は次の構文をサポートしています：

DATA INFILE ("<file_path>"[, "<file_path>" ...])
[NEGATIVE]
INTO TABLE <table_name>
[PARTITION (<partition1_name>[, <partition2_name> ...])]
[TEMPORARY PARTITION (<temporary_partition1_name>[, <temporary_partition2_name> ...])]
[COLUMNS TERMINATED BY "<column_separator>"]
[ROWS TERMINATED BY "<row_separator>"]
[FORMAT AS "CSV | Parquet | ORC"]
[(format_type_options)]
[(column_list)]
[COLUMNS FROM PATH AS (<partition_field_name>[, <partition_field_name> ...])]
[SET <k1=f1(v1)>[, <k2=f2(v2)> ...]]
[WHERE predicate]

data_desc には次のパラメーターが含まれている必要があります：

  • file_path

    ロードしたい 1 つ以上のデータファイルの保存パスを指定します。

    このパラメーターを 1 つのデータファイルの保存パスとして指定できます。たとえば、HDFS サーバー上のパス /user/data/tablename から 20210411 という名前のデータファイルをロードするために、このパラメーターを "hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/20210411" として指定できます。

    また、ワイルドカード ?、*、[]、{}、または ^ を使用して複数のデータファイルの保存パスとしてこのパラメーターを指定することもできます。Wildcard reference を参照してください。たとえば、HDFS サーバー上のパス /user/data/tablename のすべてのパーティションまたは 202104 パーティションのみからデータファイルをロードするために、このパラメーターを "hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/*/*" または "hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/dt=202104*/*" として指定できます。

    注意

    ワイルドカードは中間パスを指定するためにも使用できます。

    前述の例では、hdfs_host と hdfs_port パラメーターは次のように説明されています：

    • hdfs_host: HDFS クラスター内の NameNode ホストの IP アドレス。

    • hdfs_port: HDFS クラスター内の NameNode ホストの FS ポート。デフォルトのポート番号は 9000 です。

    注意

    • Broker Load は、S3 または S3A プロトコルに従って AWS S3 にアクセスすることをサポートしています。したがって、AWS S3 からデータをロードする場合、ファイルパスとして渡す S3 URI のプレフィックスに s3:// または s3a:// を含めることができます。
    • Broker Load は、gs プロトコルに従ってのみ Google GCS にアクセスすることをサポートしています。したがって、Google GCS からデータをロードする場合、ファイルパスとして渡す GCS URI のプレフィックスに gs:// を含める必要があります。
    • Blob Storage からデータをロードする場合、wasb または wasbs プロトコルを使用してデータにアクセスする必要があります：
      • ストレージアカウントが HTTP 経由でのアクセスを許可している場合、wasb プロトコルを使用し、ファイルパスを wasb://<container_name>@<storage_account_name>.blob.core.windows.net/<path>/<file_name>/* として記述します。
      • ストレージアカウントが HTTPS 経由でのアクセスを許可している場合、wasbs プロトコルを使用し、ファイルパスを wasbs://<container_name>@<storage_account_name>.blob.core.windows.net/<path>/<file_name>/* として記述します。
    • Data Lake Storage Gen2 からデータをロードする場合、abfs または abfss プロトコルを使用してデータにアクセスする必要があります：
      • ストレージアカウントが HTTP 経由でのアクセスを許可している場合、abfs プロトコルを使用し、ファイルパスを abfs://<container_name>@<storage_account_name>.dfs.core.windows.net/<file_name> として記述します。
      • ストレージアカウントが HTTPS 経由でのアクセスを許可している場合、abfss プロトコルを使用し、ファイルパスを abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<file_name> として記述します。
    • Data Lake Storage Gen1 からデータをロードする場合、adl プロトコルを使用してデータにアクセスし、ファイルパスを adl://<data_lake_storage_gen1_name>.azuredatalakestore.net/<path>/<file_name> として記述します。

  • INTO TABLE

    宛先 StarRocks テーブルの名前を指定します。

data_desc には、次のパラメーターをオプションで含めることができます：

  • NEGATIVE

    特定のデータバッチのロードを取り消します。これを実現するには、NEGATIVE キーワードを指定して同じデータバッチをロードする必要があります。

    注意

    このパラメーターは、StarRocks テーブルが集計テーブルであり、そのすべての値列が sum 関数によって計算される場合にのみ有効です。

  • PARTITION

    データをロードしたいパーティションを指定します。デフォルトでは、このパラメーターを指定しない場合、ソースデータは StarRocks テーブルのすべてのパーティションにロードされます。

  • TEMPORARY PARTITION

    データをロードしたい temporary partition の名前を指定します。複数の一時パーティションを指定することができ、それらはカンマ (,) で区切る必要があります。

  • COLUMNS TERMINATED BY

    データファイルで使用される列区切り文字を指定します。デフォルトでは、このパラメーターを指定しない場合、このパラメーターはタブを示す \t にデフォルト設定されます。このパラメーターを使用して指定する列区切り文字は、データファイルで実際に使用されている列区切り文字と同じでなければなりません。そうでない場合、データ品質が不十分なためロードジョブが失敗し、その State は CANCELLED になります。

    Broker Load ジョブは MySQL プロトコルに従って送信されます。StarRocks と MySQL はどちらもロードリクエストで文字をエスケープします。したがって、列区切り文字がタブのような不可視文字である場合、列区切り文字の前にバックスラッシュ () を追加する必要があります。たとえば、列区切り文字が \t の場合、\\t を入力する必要があり、列区切り文字が \n の場合、\\n を入力する必要があります。Apache Hive™ ファイルは列区切り文字として \x01 を使用するため、データファイルが Hive からのものである場合、\\x01 を入力する必要があります。

    注意

    • CSV データの場合、テキスト区切り文字として長さが 50 バイトを超えない UTF-8 文字列（カンマ (,) やタブ、パイプ (|) など）を使用できます。
    • Null 値は \N を使用して表されます。たとえば、データファイルが 3 つの列で構成され、あるレコードが最初と最後の列にデータを持ち、2 番目の列にデータがない場合、この状況では 2 番目の列に Null 値を示すために \N を使用する必要があります。つまり、レコードは a,\N,b としてコンパイルされる必要があり、a,,b ではありません。a,,b はレコードの 2 番目の列が空の文字列を持っていることを示します。

  • ROWS TERMINATED BY

    データファイルで使用される行区切り文字を指定します。デフォルトでは、このパラメーターを指定しない場合、このパラメーターは改行を示す \n にデフォルト設定されます。このパラメーターを使用して指定する行区切り文字は、データファイルで実際に使用されている行区切り文字と同じでなければなりません。そうでない場合、データ品質が不十分なためロードジョブが失敗し、その State は CANCELLED になります。このパラメーターは v2.5.4 以降でサポートされています。

    行区切り文字の使用に関する注意事項については、前述の COLUMNS TERMINATED BY パラメーターの使用に関する注意事項を参照してください。

  • FORMAT AS

    データファイルの形式を指定します。有効な値は CSV、Parquet、および ORC です。デフォルトでは、このパラメーターを指定しない場合、StarRocks は file_path パラメーターで指定されたファイル名拡張子 .csv、.parquet、または .orc に基づいてデータファイル形式を決定します。

  • format_type_options

    FORMAT AS が CSV に設定されている場合の CSV 形式オプションを指定します。構文：

    (
        key = value
        key = value
        ...
    )

    注意

    format_type_options は v3.0 以降でサポートされています。

    次の表は、オプションを説明しています。

ParameterDescription
skip_headerCSV 形式のデータファイルの最初の行をスキップするかどうかを指定します。タイプ: INTEGER。デフォルト値: 0。
一部の CSV 形式のデータファイルでは、最初の行は列名や列データ型などのメタデータを定義するために使用されます。skip_header パラメーターを設定することで、StarRocks がデータロード中にデータファイルの最初の行をスキップするようにできます。たとえば、このパラメーターを 1 に設定すると、StarRocks はデータロード中にデータファイルの最初の行をスキップします。
データファイルの最初の行は、ロードステートメントで指定した行区切り文字で区切られている必要があります。
trim_spaceCSV 形式のデータファイルの列区切り文字の前後のスペースを削除するかどうかを指定します。タイプ: BOOLEAN。デフォルト値: false。
一部のデータベースでは、データを CSV 形式のデータファイルとしてエクスポートする際に列区切り文字にスペースが追加されます。これらのスペースは、先行スペースまたは後続スペースと呼ばれます。trim_space パラメーターを設定することで、StarRocks がデータロード中にこれらの不要なスペースを削除するようにできます。
StarRocks は、enclose で指定された文字で囲まれたフィールド内のスペース（先行スペースおよび後続スペースを含む）を削除しないことに注意してください。たとえば、次のフィールド値は、列区切り文字としてパイプ (|) を使用し、enclose で指定された文字として二重引用符 (") を使用しています:
|"Love StarRocks"|
|" Love StarRocks "|
| "Love StarRocks" |
trim_space を true に設定すると、StarRocks は前述のフィールド値を次のように処理します:
|"Love StarRocks"|
|" Love StarRocks "|
|"Love StarRocks"|
encloseCSV 形式のデータファイルでフィールド値を RFC4180 に従って囲むために使用される文字を指定します。タイプ: 単一バイト文字。デフォルト値: NONE。最も一般的な文字は、単一引用符 (') および二重引用符 (") です。
enclose で指定された文字で囲まれたすべての特殊文字（行区切り文字や列区切り文字を含む）は通常の記号と見なされます。StarRocks は、enclose で指定された文字として任意の単一バイト文字を指定できるようにすることで、RFC4180 よりも多くのことを行うことができます。
フィールド値に enclose で指定された文字が含まれている場合、同じ文字を使用してその enclose で指定された文字をエスケープできます。たとえば、enclose を " に設定し、フィールド値が a "quoted" c の場合、このフィールド値をデータファイルに "a ""quoted"" c" として入力できます。
escape行区切り文字、列区切り文字、エスケープ文字、および enclose で指定された文字などのさまざまな特殊文字をエスケープするために使用される文字を指定します。これらの文字は、StarRocks によって通常の文字と見なされ、フィールド値の一部として解析されます。タイプ: 単一バイト文字。デフォルト値: NONE。最も一般的な文字はスラッシュ (\) で、SQL ステートメントではダブルスラッシュ (\\) として記述する必要があります。
注意
escape で指定された文字は、各ペアの enclose で指定された文字の内側と外側の両方に適用されます。
次の 2 つの例があります:
  • enclose を " に設定し、escape を \ に設定すると、StarRocks は "say \"Hello world\"" を say "Hello world" に解析します。
  • 列区切り文字がカンマ (,) であると仮定します。escape を \ に設定すると、StarRocks は a, b\, c を 2 つの別々のフィールド値に解析します: a と b, c。

  • column_list

    データファイルと StarRocks テーブル間の列マッピングを指定します。構文: (<column_name>[, <column_name> ...])。column_list で宣言された列は、名前によって StarRocks テーブルの列にマッピングされます。

    注意

    データファイルの列が StarRocks テーブルの列に順番にマッピングされる場合、column_list を指定する必要はありません。

    データファイルの特定の列をスキップしたい場合、その列を一時的に StarRocks テーブルの列とは異なる名前にするだけで済みます。詳細については、loading overview を参照してください。

  • COLUMNS FROM PATH AS

    指定したファイルパスから 1 つ以上のパーティションフィールドに関する情報を抽出します。このパラメーターは、ファイルパスにパーティションフィールドが含まれている場合にのみ有効です。

    たとえば、データファイルが col_name がパーティションフィールドであり、StarRocks テーブルの列にマッピングできるパス /path/col_name=col_value/file1 に保存されている場合、このパラメーターを col_name として指定できます。このようにして、StarRocks はパスから col_value 値を抽出し、それらを col_name にマッピングされた StarRocks テーブル列にロードします。

    注意

    このパラメーターは、HDFS からデータをロードする場合にのみ使用できます。

  • SET

    データファイルの列を変換するために使用したい 1 つ以上の関数を指定します。例:

    • StarRocks テーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。データファイルは 4 つの列で構成されており、そのうち最初の 2 つの列は StarRocks テーブルの col1 および col2 に順番にマッピングされ、最後の 2 つの列の合計は StarRocks テーブルの col3 にマッピングされます。この場合、column_list を (col1,col2,tmp_col3,tmp_col4) として指定し、SET 句で (col3=tmp_col3+tmp_col4) を指定してデータ変換を実装する必要があります。
    • StarRocks テーブルは、順番に year、month、および day の 3 つの列で構成されています。データファイルは、yyyy-mm-dd hh:mm:ss 形式の日付と時刻の値を収容する 1 つの列のみで構成されています。この場合、column_list を (tmp_time) として指定し、SET 句で (year = year(tmp_time), month=month(tmp_time), day=day(tmp_time)) を指定してデータ変換を実装する必要があります。

  • WHERE

    ソースデータをフィルタリングするために使用したい条件を指定します。StarRocks は、WHERE 句で指定されたフィルタ条件を満たすソースデータのみをロードします。

WITH BROKER​

v2.3 以前では、使用したいブローカーを指定するために WITH BROKER "<broker_name>" を入力します。v2.5 以降では、ブローカーを指定する必要はありませんが、WITH BROKER キーワードを保持する必要があります。

StorageCredentialParams​

StarRocks がストレージシステムにアクセスするために使用する認証情報。

HDFS​

オープンソースの HDFS は、シンプル認証と Kerberos 認証の 2 つの認証方法をサポートしています。Broker Load はデフォルトでシンプル認証を使用します。オープンソースの HDFS は、NameNode の HA メカニズムの構成もサポートしています。ストレージシステムとしてオープンソースの HDFS を選択する場合、認証構成と HA 構成を次のように指定できます：

  • 認証構成

    • シンプル認証を使用する場合、StorageCredentialParams を次のように構成します：

      "hadoop.security.authentication" = "simple",
      "username" = "<hdfs_username>",
      "password" = "<hdfs_password>"

      StorageCredentialParams のパラメーターは次のように説明されています。

      ParameterDescription
      hadoop.security.authentication認証方法。有効な値: simple および kerberos。デフォルト値: simple。simple はシンプル認証を表し、認証なしを意味し、kerberos は Kerberos 認証を表します。
      usernameHDFS クラスターの NameNode にアクセスするために使用するアカウントのユーザー名。
      passwordHDFS クラスターの NameNode にアクセスするために使用するアカウントのパスワード。

    • Kerberos 認証を使用する場合、StorageCredentialParams を次のように構成します：

      "hadoop.security.authentication" = "kerberos",
      "kerberos_principal" = "nn/zelda1@ZELDA.COM",
      "kerberos_keytab" = "/keytab/hive.keytab",
      "kerberos_keytab_content" = "YWFhYWFh"

      StorageCredentialParams のパラメーターは次のように説明されています。

      ParameterDescription
      hadoop.security.authentication認証方法。有効な値: simple および kerberos。デフォルト値: simple。simple はシンプル認証を表し、認証なしを意味し、kerberos は Kerberos 認証を表します。
      kerberos_principal認証される Kerberos プリンシパル。各プリンシパルは、HDFS クラスター全体で一意であることを保証するために、次の 3 つの部分で構成されています:
      • username または servicename: プリンシパルの名前。
      • instance: HDFS クラスター内の認証されるノードをホストするサーバーの名前。サーバー名は、HDFS クラスターが独立して認証される複数の DataNode で構成されている場合などに、プリンシパルが一意であることを保証するのに役立ちます。
      • realm: レルムの名前。レルム名は大文字でなければなりません。
      例: nn/zelda1@ZELDA.COM。
      kerberos_keytabKerberos キータブファイルの保存パス。
      kerberos_keytab_contentKerberos キータブファイルの Base64 エンコードされた内容。kerberos_keytab または kerberos_keytab_content のいずれかを指定できます。

  • HA 構成

    HDFS クラスターの NameNode に HA メカニズムを構成できます。これにより、NameNode が別のノードに切り替わった場合、StarRocks は自動的に新しい NameNode を識別できます。これには次のシナリオが含まれます：

    • Kerberos ユーザーが 1 つ構成された単一の HDFS クラスターからデータをロードする場合、ブローカーを使用したロードとブローカーを使用しないロードの両方がサポートされています。

      • ブローカーを使用したロードを実行するには、少なくとも 1 つの独立したブローカーグループがデプロイされ、HDFS クラスターをサービスするブローカーノードの {deploy}/conf パスに hdfs-site.xml ファイルを配置する必要があります。StarRocks はブローカーの起動時に {deploy}/conf パスを環境変数 CLASSPATH に追加し、ブローカーが HDFS クラスターのノード情報を読み取れるようにします。

      • ブローカーを使用しないロードを実行するには、クラスター内のすべての FE、BE、および CN ノードのデプロイメントディレクトリの conf/core-site.xml に hadoop.security.authentication = kerberos を設定し、kinit コマンドを使用して Kerberos アカウントを構成するだけで済みます。

    • 複数の Kerberos ユーザーが構成された単一の HDFS クラスターからデータをロードする場合、ブローカーを使用したロードのみがサポートされています。少なくとも 1 つの独立したブローカーグループがデプロイされ、HDFS クラスターをサービスするブローカーノードの {deploy}/conf パスに hdfs-site.xml ファイルを配置する必要があります。StarRocks はブローカーの起動時に {deploy}/conf パスを環境変数 CLASSPATH に追加し、ブローカーが HDFS クラスターのノード情報を読み取れるようにします。

    • 複数の HDFS クラスターからデータをロードする場合（1 つまたは複数の Kerberos ユーザーが構成されているかどうかに関係なく）、ブローカーを使用したロードのみがサポートされています。これらの HDFS クラスターのそれぞれに対して少なくとも 1 つの独立したブローカーグループがデプロイされ、ブローカーが HDFS クラスターのノード情報を読み取れるようにするために次のいずれかのアクションを実行します：

      • HDFS クラスターをサービスするブローカーノードの {deploy}/conf パスに hdfs-site.xml ファイルを配置します。StarRocks はブローカーの起動時に {deploy}/conf パスを環境変数 CLASSPATH に追加し、その HDFS クラスターのノード情報を読み取れるようにします。

      • ジョブ作成時に次の HA 構成を追加します：

        "dfs.nameservices" = "ha_cluster",
        "dfs.ha.namenodes.ha_cluster" = "ha_n1,ha_n2",
        "dfs.namenode.rpc-address.ha_cluster.ha_n1" = "<hdfs_host>:<hdfs_port>",
        "dfs.namenode.rpc-address.ha_cluster.ha_n2" = "<hdfs_host>:<hdfs_port>",
        "dfs.client.failover.proxy.provider" = "org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider"

        HA 構成のパラメーターは次のように説明されています。

ParameterDescription
dfs.nameservicesHDFS クラスターの名前。
dfs.ha.namenodes.XXXHDFS クラスター内の NameNode の名前。複数の NameNode 名を指定する場合は、カンマ (,) で区切ります。xxx は dfs.nameservices で指定した HDFS クラスター名です。
dfs.namenode.rpc-address.XXX.NNHDFS クラスター内の NameNode の RPC アドレス。NN は dfs.ha.namenodes.XXX で指定した NameNode 名です。
dfs.client.failover.proxy.providerクライアントが接続する NameNode のプロバイダー。デフォルト値: org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider。

注意

StarRocks クラスターにデプロイされているブローカーを確認するには、SHOW BROKER ステートメントを使用できます。

AWS S3​

AWS S3 をストレージシステムとして選択する場合、次のいずれかのアクションを実行します：

  • インスタンスプロファイルベースの認証方法を選択するには、StorageCredentialParams を次のように構成します：

    "aws.s3.use_instance_profile" = "true",
    "aws.s3.region" = "<aws_s3_region>"

  • アサインされたロールベースの認証方法を選択するには、StorageCredentialParams を次のように構成します：

    "aws.s3.use_instance_profile" = "true",
    "aws.s3.iam_role_arn" = "<iam_role_arn>",
    "aws.s3.region" = "<aws_s3_region>"

  • IAM ユーザーベースの認証方法を選択するには、StorageCredentialParams を次のように構成します：

    "aws.s3.use_instance_profile" = "false",
    "aws.s3.access_key" = "<iam_user_access_key>",
    "aws.s3.secret_key" = "<iam_user_secret_key>",
    "aws.s3.region" = "<aws_s3_region>"

StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

ParameterRequiredDescription
aws.s3.use_instance_profileYes資格情報メソッドのインスタンスプロファイルとアサインされたロールを有効にするかどうかを指定します。有効な値: true および false。デフォルト値: false。
aws.s3.iam_role_arnNoAWS S3 バケットに対する権限を持つ IAM ロールの ARN。AWS S3 にアクセスするための資格情報メソッドとしてアサインされたロールを選択する場合、このパラメーターを指定する必要があります。
aws.s3.regionYesAWS S3 バケットが存在するリージョン。例: us-west-1。
aws.s3.access_keyNoIAM ユーザーのアクセスキー。AWS S3 にアクセスするための資格情報メソッドとして IAM ユーザーを選択する場合、このパラメーターを指定する必要があります。
aws.s3.secret_keyNoIAM ユーザーのシークレットキー。AWS S3 にアクセスするための資格情報メソッドとして IAM ユーザーを選択する場合、このパラメーターを指定する必要があります。

AWS S3 にアクセスするための認証方法の選択方法と AWS IAM コンソールでのアクセス制御ポリシーの構成方法については、Authentication parameters for accessing AWS S3 を参照してください。

Google GCS​

Google GCS をストレージシステムとして選択する場合、次のいずれかのアクションを実行します：

  • VM ベースの認証方法を選択するには、StorageCredentialParams を次のように構成します：

    "gcp.gcs.use_compute_engine_service_account" = "true"

    StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

    ParameterDefault valueValue exampleDescription
    gcp.gcs.use_compute_engine_service_accountfalsetrueCompute Engine にバインドされているサービスアカウントを直接使用するかどうかを指定します。

  • サービスアカウントベースの認証方法を選択するには、StorageCredentialParams を次のように構成します：

    "gcp.gcs.service_account_email" = "<google_service_account_email>",
    "gcp.gcs.service_account_private_key_id" = "<google_service_private_key_id>",
    "gcp.gcs.service_account_private_key" = "<google_service_private_key>"

    StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

    ParameterDefault valueValue exampleDescription
    gcp.gcs.service_account_email"""user@hello.iam.gserviceaccount.com"サービスアカウントの作成時に生成された JSON ファイルのメールアドレス。
    gcp.gcs.service_account_private_key_id"""61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"サービスアカウントの作成時に生成された JSON ファイルのプライベートキー ID。
    gcp.gcs.service_account_private_key"""-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"サービスアカウントの作成時に生成された JSON ファイルのプライベートキー。

  • インパーソネーションベースの認証方法を選択するには、StorageCredentialParams を次のように構成します：

    • VM インスタンスにサービスアカウントをインパーソネートさせる：

      "gcp.gcs.use_compute_engine_service_account" = "true",
      "gcp.gcs.impersonation_service_account" = "<assumed_google_service_account_email>"

      StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

      ParameterDefault valueValue exampleDescription
      gcp.gcs.use_compute_engine_service_accountfalsetrueCompute Engine にバインドされているサービスアカウントを直接使用するかどうかを指定します。
      gcp.gcs.impersonation_service_account"""hello"インパーソネートしたいサービスアカウント。

    • サービスアカウント（メタサービスアカウントと呼ばれる）に別のサービスアカウント（データサービスアカウントと呼ばれる）をインパーソネートさせる：

      "gcp.gcs.service_account_email" = "<google_service_account_email>",
      "gcp.gcs.service_account_private_key_id" = "<meta_google_service_account_email>",
      "gcp.gcs.service_account_private_key" = "<meta_google_service_account_email>",
      "gcp.gcs.impersonation_service_account" = "<data_google_service_account_email>"

      StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

      ParameterDefault valueValue exampleDescription
      gcp.gcs.service_account_email"""user@hello.iam.gserviceaccount.com"メタサービスアカウントの作成時に生成された JSON ファイルのメールアドレス。
      gcp.gcs.service_account_private_key_id"""61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"メタサービスアカウントの作成時に生成された JSON ファイルのプライベートキー ID。
      gcp.gcs.service_account_private_key"""-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"メタサービスアカウントの作成時に生成された JSON ファイルのプライベートキー。
      gcp.gcs.impersonation_service_account"""hello"インパーソネートしたいデータサービスアカウント。

その他の S3 互換ストレージシステム​

MinIO などの他の S3 互換ストレージシステムを選択する場合、StorageCredentialParams を次のように構成します：

"aws.s3.enable_ssl" = "false",
"aws.s3.enable_path_style_access" = "true",
"aws.s3.endpoint" = "<s3_endpoint>",
"aws.s3.access_key" = "<iam_user_access_key>",
"aws.s3.secret_key" = "<iam_user_secret_key>"

StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

ParameterRequiredDescription
aws.s3.enable_sslYesSSL 接続を有効にするかどうかを指定します。有効な値: true および false。デフォルト値: true。
aws.s3.enable_path_style_accessYesパススタイルの URL アクセスを有効にするかどうかを指定します。有効な値: true および false。デフォルト値: false。MinIO の場合、値を true に設定する必要があります。
aws.s3.endpointYesAWS S3 の代わりに S3 互換ストレージシステムに接続するために使用されるエンドポイント。
aws.s3.access_keyYesIAM ユーザーのアクセスキー。
aws.s3.secret_keyYesIAM ユーザーのシークレットキー。

Microsoft Azure Storage​

Azure Blob Storage​

Blob Storage をストレージシステムとして選択する場合、次のいずれかのアクションを実行します：

  • 共有キー認証方法を選択するには、StorageCredentialParams を次のように構成します：

    "azure.blob.storage_account" = "<storage_account_name>",
    "azure.blob.shared_key" = "<storage_account_shared_key>"

    StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

    ParameterRequiredDescription
    azure.blob.storage_accountYesBlob Storage アカウントのユーザー名。
    azure.blob.shared_keyYesBlob Storage アカウントの共有キー。

  • SAS トークン認証方法を選択するには、StorageCredentialParams を次のように構成します：

    "azure.blob.storage_account" = "<storage_account_name>",
    "azure.blob.container" = "<container_name>",
    "azure.blob.sas_token" = "<storage_account_SAS_token>"

    StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

    ParameterRequiredDescription
    azure.blob.storage_accountYesBlob Storage アカウントのユーザー名。
    azure.blob.containerYesデータを格納する Blob コンテナの名前。
    azure.blob.sas_tokenYesBlob Storage アカウントにアクセスするために使用される SAS トークン。
Azure Data Lake Storage Gen2​

Data Lake Storage Gen2 をストレージシステムとして選択する場合、次のいずれかのアクションを実行します：

  • マネージド ID 認証方法を選択するには、StorageCredentialParams を次のように構成します：

    "azure.adls2.oauth2_use_managed_identity" = "true",
    "azure.adls2.oauth2_tenant_id" = "<service_principal_tenant_id>",
    "azure.adls2.oauth2_client_id" = "<service_client_id>"

    StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

    ParameterRequiredDescription
    azure.adls2.oauth2_use_managed_identityYesマネージド ID 認証方法を有効にするかどうかを指定します。値を true に設定します。
    azure.adls2.oauth2_tenant_idYesアクセスしたいデータのテナント ID。
    azure.adls2.oauth2_client_idYesマネージド ID のクライアント（アプリケーション）ID。

  • 共有キー認証方法を選択するには、StorageCredentialParams を次のように構成します：

    "azure.adls2.storage_account" = "<storage_account_name>",
    "azure.adls2.shared_key" = "<storage_account_shared_key>"

    StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

    ParameterRequiredDescription
    azure.adls2.storage_accountYesData Lake Storage Gen2 ストレージアカウントのユーザー名。
    azure.adls2.shared_keyYesData Lake Storage Gen2 ストレージアカウントの共有キー。

  • サービスプリンシパル認証方法を選択するには、StorageCredentialParams を次のように構成します：

    "azure.adls2.oauth2_client_id" = "<service_client_id>",
    "azure.adls2.oauth2_client_secret" = "<service_principal_client_secret>",
    "azure.adls2.oauth2_client_endpoint" = "<service_principal_client_endpoint>"

    StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

    ParameterRequiredDescription
    azure.adls2.oauth2_client_idYesサービスプリンシパルのクライアント（アプリケーション）ID。
    azure.adls2.oauth2_client_secretYes作成された新しいクライアント（アプリケーション）シークレットの値。
    azure.adls2.oauth2_client_endpointYesサービスプリンシパルまたはアプリケーションの OAuth 2.0 トークンエンドポイント（v1）。
Azure Data Lake Storage Gen1​

Data Lake Storage Gen1 をストレージシステムとして選択する場合、次のいずれかのアクションを実行します：

  • マネージドサービス ID 認証方法を選択するには、StorageCredentialParams を次のように構成します：

    "azure.adls1.use_managed_service_identity" = "true"

    StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

    ParameterRequiredDescription
    azure.adls1.use_managed_service_identityYesマネージドサービス ID 認証方法を有効にするかどうかを指定します。値を true に設定します。

  • サービスプリンシパル認証方法を選択するには、StorageCredentialParams を次のように構成します：

    "azure.adls1.oauth2_client_id" = "<application_client_id>",
    "azure.adls1.oauth2_credential" = "<application_client_credential>",
    "azure.adls1.oauth2_endpoint" = "<OAuth_2.0_authorization_endpoint_v2>"

    StorageCredentialParams で構成する必要があるパラメーターは次のとおりです。

ParameterRequiredDescription
azure.adls1.oauth2_client_idYesクライアント（アプリケーション）ID。
azure.adls1.oauth2_credentialYes作成された新しいクライアント（アプリケーション）シークレットの値。
azure.adls1.oauth2_endpointYesサービスプリンシパルまたはアプリケーションの OAuth 2.0 トークンエンドポイント（v1）。

opt_properties​

ロードジョブ全体に適用されるオプションのパラメーターを指定します。構文：

PROPERTIES ("<key1>" = "<value1>"[, "<key2>" = "<value2>" ...])

次のパラメーターがサポートされています：

  • timeout

    ロードジョブのタイムアウト期間を指定します。単位: 秒。デフォルトのタイムアウト期間は 4 時間です。タイムアウト期間を 6 時間未満に指定することをお勧めします。ロードジョブがタイムアウト期間内に終了しない場合、StarRocks はロードジョブをキャンセルし、ロードジョブのステータスは CANCELLED になります。

    注意

    ほとんどの場合、タイムアウト期間を設定する必要はありません。ロードジョブがデフォルトのタイムアウト期間内に終了しない場合にのみ、タイムアウト期間を設定することをお勧めします。

    タイムアウト期間を推測するための式を使用します：

    Timeout period > (ロードするデータファイルの合計サイズ x ロードするデータファイルの合計数とデータファイルに作成されたマテリアライズドビュー)/平均ロード速度

    注意

    "平均ロード速度" は、StarRocks クラスター全体の平均ロード速度です。平均ロード速度は、サーバー構成とクラスターで許可される最大同時クエリタスク数に応じてクラスターごとに異なります。過去のロードジョブのロード速度に基づいて平均ロード速度を推測できます。

    1 GB のデータファイルをロードし、2 つのマテリアライズドビューが作成されている StarRocks クラスターにロードする場合、平均ロード速度が 10 MB/s の場合、データロードに必要な時間は約 102 秒です。

    (1 x 1024 x 3)/10 = 307.2 (秒)

    この例では、タイムアウト期間を 308 秒以上に設定することをお勧めします。

  • max_filter_ratio

    ロードジョブの最大エラー許容度を指定します。最大エラー許容度は、データ品質が不十分なためにフィルタリングされる行の最大割合です。有効な値: 0~1。デフォルト値: 0。

    • このパラメーターを 0 に設定すると、StarRocks はロード中に不適格な行を無視しません。そのため、ソースデータに不適格な行が含まれている場合、ロードジョブは失敗します。これにより、StarRocks にロードされるデータの正確性が保証されます。

    • このパラメーターを 0 より大きい値に設定すると、StarRocks はロード中に不適格な行を無視できます。そのため、ソースデータに不適格な行が含まれていても、ロードジョブは成功することがあります。

      注意

      データ品質が不十分なためにフィルタリングされる行には、WHERE 句によってフィルタリングされる行は含まれません。

    最大エラー許容度が 0 に設定されているためにロードジョブが失敗した場合、SHOW LOAD を使用してジョブ結果を表示できます。その後、不適格な行をフィルタリングできるかどうかを判断します。不適格な行をフィルタリングできる場合、ジョブ結果で返される dpp.abnorm.ALL と dpp.norm.ALL の値に基づいて最大エラー許容度を計算し、最大エラー許容度を調整してロードジョブを再送信します。最大エラー許容度を計算するための式は次のとおりです：

    max_filter_ratio = [dpp.abnorm.ALL/(dpp.abnorm.ALL + dpp.norm.ALL)]

    dpp.abnorm.ALL と dpp.norm.ALL の値の合計は、ロードされる行の総数です。

  • log_rejected_record_num

    ログに記録できる不適格なデータ行の最大数を指定します。このパラメーターは v3.1 以降でサポートされています。有効な値: 0、-1、および任意の非ゼロの正の整数。デフォルト値: 0。

    • 値 0 は、フィルタリングされたデータ行がログに記録されないことを指定します。
    • 値 -1 は、フィルタリングされたすべてのデータ行がログに記録されることを指定します。
    • 非ゼロの正の整数 n は、フィルタリングされたデータ行が各 BE に最大 n 行までログに記録されることを指定します。

  • load_mem_limit

    ロードジョブに提供できるメモリの最大量を指定します。このパラメーターの値は、各 BE または CN ノードでサポートされる上限メモリを超えることはできません。単位: バイト。デフォルトのメモリ制限は 2 GB です。

  • strict_mode

    strict mode を有効にするかどうかを指定します。有効な値: true および false。デフォルト値: false。true は strict mode を有効にし、false は strict mode を無効にします。

  • timezone

    ロードジョブのタイムゾーンを指定します。デフォルト値: Asia/Shanghai。タイムゾーン設定は、strftime、alignment_timestamp、from_unixtime などの関数によって返される結果に影響を与えます。詳細については、Configure a time zone を参照してください。timezone パラメーターで指定されたタイムゾーンは、セッションレベルのタイムゾーンです。

  • priority

    ロードジョブの優先度を指定します。有効な値: LOWEST、LOW、NORMAL、HIGH、および HIGHEST。デフォルト値: NORMAL。Broker Load は、FE パラメーター max_broker_load_job_concurrency を提供し、StarRocks クラスター内で同時に実行できる Broker Load ジョブの最大数を決定します。指定された時間内に送信された Broker Load ジョブの数が最大数を超える場合、過剰なジョブは優先度に基づいてスケジュールされるまで待機します。

    ALTER LOAD ステートメントを使用して、QUEUEING または LOADING 状態にある既存のロードジョブの優先度を変更できます。

    StarRocks は v2.5 以降、Broker Load ジョブの priority パラメーターを設定することを許可しています。

  • partial_update

    部分更新を使用するかどうかを指定します。有効な値: TRUE および FALSE。デフォルト値: FALSE、この機能を無効にすることを示します。

  • partial_update_mode

    部分更新のモードを指定します。有効な値: row および column。

    • 値 row（デフォルト）は、行モードでの部分更新を意味し、多くの列と小さなバッチでのリアルタイム更新により適しています。
    • 値 column は、列モードでの部分更新を意味し、少数の列と多数の行でのバッチ更新により適しています。このようなシナリオでは、列モードを有効にすると更新速度が速くなります。たとえば、100 列のテーブルで、すべての行に対して 10 列（全体の 10%）のみが更新される場合、列モードの更新速度は 10 倍速くなります。

  • merge_condition

    更新が有効になるかどうかを判断するための条件として使用したい列の名前を指定します。ソースレコードから宛先レコードへの更新は、指定された列でソースデータレコードが宛先データレコードよりも大きいまたは等しい値を持つ場合にのみ有効になります。

    注意

    指定する列は主キー列であってはなりません。また、主キーテーブルを使用するテーブルのみが条件付き更新をサポートしています。

StarRocks は v3.2.3 以降、JSON データのロードをサポートしています。パラメーターは次のとおりです：

  • jsonpaths

    JSON データファイルからロードしたいキーの名前。マッチモードを使用して JSON データをロードする場合にのみ、このパラメーターを指定する必要があります。このパラメーターの値は JSON 形式です。Configure column mapping for JSON data loading を参照してください。

  • strip_outer_array

    最外部の配列構造を削除するかどうかを指定します。有効な値: true および false。デフォルト値: false。

    実際のビジネスシナリオでは、JSON データは [] で示される最外部の配列構造を持つことがあります。このような場合、このパラメーターを true に設定することをお勧めします。StarRocks は最外部の角括弧 [] を削除し、各内部配列を個別のデータレコードとしてロードします。このパラメーターを false に設定すると、StarRocks は JSON データファイル全体を 1 つの配列として解析し、その配列を 1 つのデータレコードとしてロードします。たとえば、JSON データが [ {"category" : 1, "author" : 2}, {"category" : 3, "author" : 4} ] の場合、このパラメーターを true に設定すると、{"category" : 1, "author" : 2} と {"category" : 3, "author" : 4} は個別のデータレコードとして解析され、個別の StarRocks テーブル行にロードされます。

  • json_root

    JSON データファイルからロードしたい JSON データのルート要素。マッチモードを使用して JSON データをロードする場合にのみ、このパラメーターを指定する必要があります。このパラメーターの値は有効な JsonPath 文字列です。デフォルトでは、このパラメーターの値は空であり、JSON データファイルのすべてのデータがロードされることを示します。詳細については、このトピックの「Load JSON data using matched mode with root element specified」セクションを参照してください。

JSON データをロードする際、各 JSON オブジェクトのサイズが 4 GB を超えないことにも注意してください。JSON データファイル内の個々の JSON オブジェクトが 4 GB を超える場合、「This parser can't support a document that big.」というエラーが報告されます。

列マッピング​

CSV データロードの列マッピングの設定​

データファイルの列が StarRocks テーブルの列に順番に 1 対 1 でマッピングできる場合、データファイルと StarRocks テーブル間の列マッピングを設定する必要はありません。

データファイルの列が StarRocks テーブルの列に順番に 1 対 1 でマッピングできない場合、columns パラメーターを使用してデータファイルと StarRocks テーブル間の列マッピングを設定する必要があります。これには次の 2 つのユースケースが含まれます：

  • 同じ数の列だが異なる列順序。データファイルからのデータは、StarRocks テーブルの対応する列にロードされる前に関数によって計算される必要はありません。

    columns パラメーターでは、データファイルの列が配置されている順序と同じ順序で StarRocks テーブルの列名を指定する必要があります。

    たとえば、StarRocks テーブルは順番に col1、col2、および col3 の 3 つの列で構成されており、データファイルも 3 つの列で構成されており、順番に StarRocks テーブルの col3、col2、および col1 にマッピングできます。この場合、"columns: col3, col2, col1" と指定する必要があります。

  • 異なる数の列と異なる列順序。データファイルからのデータは、StarRocks テーブルの対応する列にロードされる前に関数によって計算される必要があります。

    columns パラメーターでは、データファイルの列が配置されている順序と同じ順序で StarRocks テーブルの列名を指定し、データを計算するために使用したい関数を指定する必要があります。次の 2 つの例があります：

    • StarRocks テーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。データファイルは 4 つの列で構成されており、そのうち最初の 3 つの列は順番に StarRocks テーブルの col1、col2、および col3 にマッピングされ、4 番目の列は StarRocks テーブルのいずれの列にもマッピングされません。この場合、データファイルの 4 番目の列に一時的な名前を指定する必要があり、その一時的な名前は StarRocks テーブルのいずれの列名とも異なる必要があります。たとえば、データファイルの 4 番目の列を一時的に temp として指定できます。
    • StarRocks テーブルは、順番に year、month、および day の 3 つの列で構成されています。データファイルは、yyyy-mm-dd hh:mm:ss 形式の日付と時刻の値を収容する 1 つの列のみで構成されています。この場合、"columns: col, year = year(col), month=month(col), day=day(col)" と指定できます。ここで、col はデータファイル列の一時的な名前であり、year = year(col)、month=month(col)、および day=day(col) の関数は、データファイル列 col からデータを抽出し、対応する StarRocks テーブルの列にロードします。たとえば、year = year(col) はデータファイル列 col から yyyy データを抽出し、StarRocks テーブルの列 year にロードします。

詳細な例については、Configure column mapping を参照してください。

JSON データロードの列マッピングの設定​

JSON ドキュメントのキーが StarRocks テーブルの列と同じ名前を持っている場合、シンプルモードを使用して JSON 形式のデータをロードできます。シンプルモードでは、jsonpaths パラメーターを指定する必要はありません。このモードでは、JSON 形式のデータは {} で示されるオブジェクトである必要があります。たとえば、{"category": 1, "author": 2, "price": "3"} です。この例では、category、author、および price はキー名であり、これらのキーは名前によって 1 対 1 で StarRocks テーブルの列 category、author、および price にマッピングできます。

JSON ドキュメントのキーが StarRocks テーブルの列と異なる名前を持っている場合、マッチモードを使用して JSON 形式のデータをロードできます。マッチモードでは、jsonpaths および COLUMNS パラメーターを使用して JSON ドキュメントと StarRocks テーブル間の列マッピングを指定する必要があります：

  • jsonpaths パラメーターでは、JSON ドキュメントに配置されている順序で JSON キーを指定します。
  • COLUMNS パラメーターでは、JSON キーと StarRocks テーブルの列間のマッピングを指定します：
    • COLUMNS パラメーターで指定された列名は、JSON キーに順番に 1 対 1 でマッピングされます。
    • COLUMNS パラメーターで指定された列名は、StarRocks テーブルの列に名前によって 1 対 1 でマッピングされます。

マッチモードを使用して JSON 形式のデータをロードする例については、Load JSON data using matched mode を参照してください。

関連する構成項目​

FE 構成項目 max_broker_load_job_concurrency は、StarRocks クラスター内で同時に実行できる Broker Load ジョブの最大数を指定します。

StarRocks v2.4 以前では、特定の期間内に送信された Broker Load ジョブの総数が最大数を超える場合、過剰なジョブは送信時間に基づいてキューに入れられ、スケジュールされます。

StarRocks v2.5 以降では、特定の期間内に送信された Broker Load ジョブの総数が最大数を超える場合、過剰なジョブは優先度に基づいてキューに入れられ、スケジュールされます。上記の priority パラメーターを使用してジョブの優先度を指定できます。ALTER LOAD を使用して、QUEUEING または LOADING 状態にある既存のジョブの優先度を変更できます。

ジョブの分割と同時実行​

Broker Load ジョブは、1 つ以上のタスクに分割され、同時に実行されることがあります。ロードジョブ内のタスクは単一のトランザクション内で実行されます。すべて成功するか、すべて失敗しなければなりません。StarRocks は、LOAD ステートメントで data_desc をどのように宣言するかに基づいて各ロードジョブを分割します：

  • 複数の data_desc パラメーターを宣言し、それぞれが異なるテーブルを指定する場合、各テーブルのデータをロードするタスクが生成されます。

  • 複数の data_desc パラメーターを宣言し、それぞれが同じテーブルの異なるパーティションを指定する場合、各パーティションのデータをロードするタスクが生成されます。

さらに、各タスクは 1 つ以上のインスタンスにさらに分割され、StarRocks クラスターの BEs または CNs に均等に分散され、同時に実行されます。StarRocks は、FE パラメーター min_bytes_per_broker_scanner と BE または CN ノードの数に基づいて各タスクを分割します。個々のタスク内のインスタンスの数を計算するための式は次のとおりです：

個々のタスク内のインスタンスの数 = min(個々のタスクによってロードされるデータ量/min_bytes_per_broker_scanner, BE/CN ノードの数)

ほとんどの場合、各ロードジョブには 1 つの data_desc のみが宣言され、各ロードジョブは 1 つのタスクにのみ分割され、そのタスクは BE または CN ノードの数と同じ数のインスタンスに分割されます。

例​

このセクションでは、HDFS を例にとってさまざまなロード構成を説明します。

CSV データのロード​

このセクションでは、さまざまなロード要件を満たすために使用できるさまざまなパラメーター構成を説明するために CSV を例にとります。

タイムアウト期間の設定​

StarRocks データベース test_db には table1 という名前のテーブルがあります。このテーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。

データファイル example1.csv も 3 つの列で構成されており、table1 の col1、col2、および col3 に順番にマッピングされています。

example1.csv から table1 に 3600 秒以内にすべてのデータをロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label1
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example1.csv")
    INTO TABLE table1
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
)
PROPERTIES
(
    "timeout" = "3600"
);

最大エラー許容度の設定​

StarRocks データベース test_db には table2 という名前のテーブルがあります。このテーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。

データファイル example2.csv も 3 つの列で構成されており、table2 の col1、col2、および col3 に順番にマッピングされています。

example2.csv から table2 に最大エラー許容度 0.1 でデータをロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label2
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example2.csv")
    INTO TABLE table2

)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
)
PROPERTIES
(
    "max_filter_ratio" = "0.1"
);

ファイルパスからすべてのデータファイルをロード​

StarRocks データベース test_db には table3 という名前のテーブルがあります。このテーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。

HDFS クラスターの /user/starrocks/data/input/ パスに保存されているすべてのデータファイルもそれぞれ 3 つの列で構成されており、table3 の col1、col2、および col3 に順番にマッピングされています。これらのデータファイルで使用される列区切り文字は \x01 です。

HDFS サーバーの /user/starrocks/data/input/ パスに保存されているすべてのデータファイルから table3 にデータをロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label3
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/*")
    INTO TABLE table3
    COLUMNS TERMINATED BY "\\x01"
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

NameNode HA メカニズムの設定​

StarRocks データベース test_db には table4 という名前のテーブルがあります。このテーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。

データファイル example4.csv も 3 つの列で構成されており、table4 の col1、col2、および col3 にマッピングされています。

NameNode に HA メカニズムが構成された状態で example4.csv から table4 にすべてのデータをロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label4
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example4.csv")
    INTO TABLE table4
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>",
    "dfs.nameservices" = "my_ha",
    "dfs.ha.namenodes.my_ha" = "my_namenode1, my_namenode2","dfs.namenode.rpc-address.my_ha.my_namenode1" = "nn1_host:rpc_port",
    "dfs.namenode.rpc-address.my_ha.my_namenode2" = "nn2_host:rpc_port",
    "dfs.client.failover.proxy.provider" = "org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider"
);

Kerberos 認証の設定​

StarRocks データベース test_db には table5 という名前のテーブルがあります。このテーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。

データファイル example5.csv も 3 つの列で構成されており、table5 の col1、col2、および col3 に順番にマッピングされています。

Kerberos 認証が構成され、キータブファイルパスが指定された状態で example5.csv から table5 にすべてのデータをロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label5
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example5.csv")
    INTO TABLE table5
    COLUMNS TERMINATED BY "\t"
)
WITH BROKER
(
    "hadoop.security.authentication" = "kerberos",
    "kerberos_principal" = "starrocks@YOUR.COM",
    "kerberos_keytab" = "/home/starRocks/starRocks.keytab"
);

データロードの取り消し​

StarRocks データベース test_db には table6 という名前のテーブルがあります。このテーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。

データファイル example6.csv も 3 つの列で構成されており、table6 の col1、col2、および col3 に順番にマッピングされています。

Broker Load ジョブを実行して example6.csv から table6 にすべてのデータをロードしました。

ロードしたデータを取り消したい場合、次のコマンドを実行します：

LOAD LABEL test_db.label6
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example6.csv")
    NEGATIVE
    INTO TABLE table6
    COLUMNS TERMINATED BY "\t"
)
WITH BROKER
(
    "hadoop.security.authentication" = "kerberos",
    "kerberos_principal" = "starrocks@YOUR.COM",
    "kerberos_keytab" = "/home/starRocks/starRocks.keytab"
);

宛先パーティションの指定​

StarRocks データベース test_db には table7 という名前のテーブルがあります。このテーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。

データファイル example7.csv も 3 つの列で構成されており、table7 の col1、col2、および col3 に順番にマッピングされています。

example7.csv から table7 の 2 つのパーティション p1 と p2 にすべてのデータをロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label7
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example7.csv")
    INTO TABLE table7
    PARTITION (p1, p2)
    COLUMNS TERMINATED BY ","
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

列マッピングの設定​

StarRocks データベース test_db には table8 という名前のテーブルがあります。このテーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。

データファイル example8.csv も 3 つの列で構成されており、table8 の col2、col1、および col3 に順番にマッピングされています。

example8.csv から table8 にすべてのデータをロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label8
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example8.csv")
    INTO TABLE table8
    COLUMNS TERMINATED BY ","
    (col2, col1, col3)
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

注意

前述の例では、example8.csv の列は、table8 の列が配置されている順序と同じ順序でマッピングできません。そのため、column_list を使用して example8.csv と table8 間の列マッピングを設定する必要があります。

フィルタ条件の設定​

StarRocks データベース test_db には table9 という名前のテーブルがあります。このテーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。

データファイル example9.csv も 3 つの列で構成されており、table9 の col1、col2、および col3 に順番にマッピングされています。

example9.csv から table9 に、最初の列の値が 20180601 より大きいデータレコードのみをロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label9
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example9.csv")
    INTO TABLE table9
    (col1, col2, col3)
    where col1 > 20180601
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

注意

前述の例では、example9.csv の列は、table9 の列が配置されている順序と同じ順序でマッピングできますが、WHERE 句を使用して列ベースのフィルタ条件を指定する必要があります。そのため、column_list を使用して example9.csv と table9 間の列マッピングを設定する必要があります。

HLL 型の列を含むテーブルへのデータロード​

StarRocks データベース test_db には table10 という名前のテーブルがあります。このテーブルは、順番に id、col1、col2、および col3 の 4 つの列で構成されています。col1 と col2 は HLL 型の列として定義されています。

データファイル example10.csv は 3 つの列で構成されており、そのうち最初の列は table10 の id にマッピングされ、2 番目と 3 番目の列は順番に table10 の col1 と col2 にマッピングされています。example10.csv の 2 番目と 3 番目の列の値は、関数を使用して HLL 型のデータに変換され、table10 の col1 と col2 にロードされます。

example10.csv から table10 にすべてのデータをロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label10
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example10.csv")
    INTO TABLE table10
    COLUMNS TERMINATED BY ","
    (id, temp1, temp2)
    SET
    (
        col1 = hll_hash(temp1),
        col2 = hll_hash(temp2),
        col3 = empty_hll()
     )
 )
 WITH BROKER
 (
     "username" = "<hdfs_username>",
     "password" = "<hdfs_password>"
 );

注意

前述の例では、example10.csv の 3 つの列は column_list を使用して順番に id、temp1、および temp2 として名前が付けられています。その後、関数を使用してデータを次のように変換します：

  • hll_hash 関数を使用して、example10.csv の temp1 と temp2 の値を HLL 型のデータに変換し、example10.csv の temp1 と temp2 を table10 の col1 と col2 にマッピングします。

  • hll_empty 関数を使用して、指定されたデフォルト値を table10 の col3 に埋め込みます。

関数 hll_hash および hll_empty の使用については、hll_hash および hll_empty を参照してください。

ファイルパスからパーティションフィールドの値を抽出​

Broker Load は、宛先 StarRocks テーブルの列定義に基づいて、ファイルパスに含まれる特定のパーティションフィールドの値を解析することをサポートしています。この StarRocks の機能は、Apache Spark™ の Partition Discovery 機能に似ています。

StarRocks データベース test_db には table11 という名前のテーブルがあります。このテーブルは、順番に col1、col2、col3、city、および utc_date の 5 つの列で構成されています。

HDFS クラスターのファイルパス /user/starrocks/data/input/dir/city=beijing には、次のデータファイルが含まれています：

  • /user/starrocks/data/input/dir/city=beijing/utc_date=2019-06-26/0000.csv

  • /user/starrocks/data/input/dir/city=beijing/utc_date=2019-06-26/0001.csv

これらのデータファイルはそれぞれ 3 つの列で構成されており、table11 の col1、col2、および col3 に順番にマッピングされています。

ファイルパス /user/starrocks/data/input/dir/city=beijing/utc_date=*/* からすべてのデータファイルを table11 にロードし、同時にファイルパスに含まれるパーティションフィールド city と utc_date の値を抽出し、table11 の city と utc_date にロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label11
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/dir/city=beijing/*/*")
    INTO TABLE table11
    FORMAT AS "csv"
    (col1, col2, col3)
    COLUMNS FROM PATH AS (city, utc_date)
    SET (uniq_id = md5sum(k1, city))
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

%3A を含むファイルパスからパーティションフィールドの値を抽出​

HDFS では、ファイルパスにコロン (:) を含めることはできません。すべてのコロン (:) は %3A に変換されます。

StarRocks データベース test_db には table12 という名前のテーブルがあります。このテーブルは、順番に data_time、col1、および col2 の 3 つの列で構成されています。テーブルスキーマは次のとおりです：

data_time DATETIME,
col1        INT,
col2        INT

HDFS クラスターのファイルパス /user/starrocks/data には、次のデータファイルが含まれています：

  • /user/starrocks/data/data_time=2020-02-17 00%3A00%3A00/example12.csv

  • /user/starrocks/data/data_time=2020-02-18 00%3A00%3A00/example12.csv

example12.csv から table12 にすべてのデータをロードし、同時にファイルパスからパーティションフィールド data_time の値を抽出し、table12 の data_time にロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label12
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/*/example12.csv")
    INTO TABLE table12
    COLUMNS TERMINATED BY ","
    FORMAT AS "csv"
    (col1,col2)
    COLUMNS FROM PATH AS (data_time)
    SET (data_time = str_to_date(data_time, '%Y-%m-%d %H%%3A%i%%3A%s'))
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

注意

前述の例では、パーティションフィールド data_time から抽出された値は %3A を含む文字列であり、2020-02-17 00%3A00%3A00 のような形式です。そのため、str_to_date 関数を使用して、文字列を table8 の data_time にロードする前に DATETIME 型のデータに変換する必要があります。

format_type_options の設定​

StarRocks データベース test_db には table13 という名前のテーブルがあります。このテーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。

データファイル example13.csv も 3 つの列で構成されており、table13 の col2、col1、および col3 に順番にマッピングされています。

example13.csv から table13 にすべてのデータをロードし、example13.csv の最初の 2 行をスキップし、列区切り文字の前後のスペースを削除し、enclose を \ に設定し、escape を \ に設定したい場合、次のコマンドを実行します：

LOAD LABEL test_db.label13
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/*/example13.csv")
    INTO TABLE table13
    COLUMNS TERMINATED BY ","
    FORMAT AS "CSV"
    (
        skip_header = 2
        trim_space = TRUE
        enclose = "\""
        escape = "\\"
    )
    (col2, col1, col3)
)
WITH BROKER
(
    "username" = "hdfs_username",
    "password" = "hdfs_password"
)
PROPERTIES
(
    "timeout" = "3600"
);

Parquet データのロード​

このセクションでは、Parquet データをロードする際に注意が必要なパラメーター設定について説明します。

StarRocks データベース test_db には table13 という名前のテーブルがあります。このテーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。

データファイル example13.parquet も 3 つの列で構成されており、table13 の col1、col2、および col3 に順番にマッピングされています。

example13.parquet から table13 にすべてのデータをロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label13
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example13.parquet")
    INTO TABLE table13
    FORMAT AS "parquet"
    (col1, col2, col3)
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

注意

デフォルトでは、Parquet データをロードする際、StarRocks はファイル名に .parquet 拡張子が含まれているかどうかに基づいてデータファイル形式を決定します。ファイル名に .parquet 拡張子が含まれていない場合、FORMAT AS を使用してデータファイル形式を Parquet として指定する必要があります。

ORC データのロード​

このセクションでは、ORC データをロードする際に注意が必要なパラメーター設定について説明します。

StarRocks データベース test_db には table14 という名前のテーブルがあります。このテーブルは、順番に col1、col2、および col3 の 3 つの列で構成されています。

データファイル example14.orc も 3 つの列で構成されており、table14 の col1、col2、および col3 に順番にマッピングされています。

example14.orc から table14 にすべてのデータをロードしたい場合、次のコマンドを実行します：

LOAD LABEL test_db.label14
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example14.orc")
    INTO TABLE table14
    FORMAT AS "orc"
    (col1, col2, col3)
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

注意

  • デフォルトでは、ORC データをロードする際、StarRocks はファイル名に .orc 拡張子が含まれているかどうかに基づいてデータファイル形式を決定します。ファイル名に .orc 拡張子が含まれていない場合、FORMAT AS を使用してデータファイル形式を ORC として指定する必要があります。

  • StarRocks v2.3 以前では、データファイルに ARRAY 型の列が含まれている場合、ORC データファイルの列が StarRocks テーブルの対応する列と同じ名前であることを確認し、SET 句で指定することはできません。

JSON データのロード​

このセクションでは、JSON データをロードする際に注意が必要なパラメーター設定について説明します。

StarRocks データベース test_db には tbl1 という名前のテーブルがあり、そのスキーマは次のとおりです：

`category` varchar(512) NULL COMMENT "",
`author` varchar(512) NULL COMMENT "",
`title` varchar(512) NULL COMMENT "",
`price` double NULL COMMENT ""

シンプルモードを使用した JSON データのロード​

データファイル example1.json が次のデータで構成されていると仮定します：

{"category":"C++","author":"avc","title":"C++ primer","price":895}

example1.json から tbl1 にすべてのデータをロードするには、次のコマンドを実行します：

LOAD LABEL test_db.label15
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example1.csv")
    INTO TABLE tbl1
    FORMAT AS "json"
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

注意

前述の例では、columns および jsonpaths パラメーターは指定されていません。そのため、example1.json のキーは名前によって tbl1 の列にマッピングされます。

マッチモードを使用した JSON データのロード​

StarRocks は、JSON データをマッチングして処理するために次のステップを実行します：

  1. strip_outer_array パラメーター設定によって指示された最外部の配列構造を削除します（オプション）。

    注意

    このステップは、JSON データの最外部レイヤーが [] で示される配列構造である場合にのみ実行されます。この場合、strip_outer_array を true に設定する必要があります。

  2. json_root パラメーター設定によって指示された JSON データのルート要素をマッチングします（オプション）。

    注意

    このステップは、JSON データにルート要素がある場合にのみ実行されます。この場合、json_root パラメーターを使用してルート要素を指定する必要があります。

  3. jsonpaths パラメーター設定によって指示された JSON データを抽出します。

ルート要素を指定せずにマッチモードを使用して JSON データをロード​

データファイル example2.json が次のデータで構成されていると仮定します：

[
    {"category":"xuxb111","author":"1avc","title":"SayingsoftheCentury","price":895},
    {"category":"xuxb222","author":"2avc","title":"SayingsoftheCentury","price":895},
    {"category":"xuxb333","author":"3avc","title":"SayingsoftheCentury","price":895}
]

example2.json から category、author、および price のみをロードするには、次のコマンドを実行します：

LOAD LABEL test_db.label16
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example2.csv")
    INTO TABLE tbl1
    FORMAT AS "json"
    (category, price, author)
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
)
PROPERTIES
(
    "strip_outer_array" = "true",
    "jsonpaths" = "[\"$.category\",\"$.price\",\"$.author\"]"
);

注意

前述の例では、JSON データの最外部レイヤーは [] で示される配列構造です。この配列構造は、各データレコードを表す複数の JSON オブジェクトで構成されています。そのため、最外部の配列構造を削除するために strip_outer_array を true に設定する必要があります。ロードしたくないキー title はロード中に無視されます。

ルート要素を指定してマッチモードを使用して JSON データをロード​

データファイル example3.json が次のデータで構成されていると仮定します：

{
    "id": 10001,
    "RECORDS":[
        {"category":"11","title":"SayingsoftheCentury","price":895,"timestamp":1589191587},
        {"category":"22","author":"2avc","price":895,"timestamp":1589191487},
        {"category":"33","author":"3avc","title":"SayingsoftheCentury","timestamp":1589191387}
    ],
    "comments": ["3 records", "there will be 3 rows"]
}

example3.json から category、author、および price のみをロードするには、次のコマンドを実行します：

LOAD LABEL test_db.label17
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example3.csv")
    INTO TABLE tbl1
    FORMAT AS "json"
    (category, price, author)
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
)
PROPERTIES
(
    "json_root"="$.RECORDS",
    "strip_outer_array" = "true",
    "jsonpaths" = "[\"$.category\",\"$.price\",\"$.author\"]"
);

注意

前述の例では、JSON データの最外部レイヤーは [] で示される配列構造です。この配列構造は、各データレコードを表す複数の JSON オブジェクトで構成されています。そのため、最外部の配列構造を削除するために strip_outer_array を true に設定する必要があります。ロードしたくないキー title と timestamp はロード中に無視されます。また、json_root パラメーターを使用して、JSON データのルート要素である配列を指定します。