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>/*
として記述します。
- ストレージアカウントが HTTP 経由でのアクセスを許可している場合、wasb プロトコルを使用し、ファイルパスを
- 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>
として記述します。
- ストレージアカウントが HTTP 経由でのアクセスを許可している場合、abfs プロトコルを使用し、ファイルパスを
- 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 データの場合、UTF-8 文字列(カンマ (,) やタブ、パイプ (|) など)をテキスト区切り文字として使用できますが、その長さは 50 バイトを超えてはなりません。
- Null 値は
\N
を使用して示されます。たとえば、データファイルが 3 列で構成され、そのデータファイルのレコードが最初と最後の列にデータを持ち、2 番目の列にデータがない場合、この状況では 2 番目の列に\N
を使用して null 値を示す必要があり ます。これは、レコードを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 以降でサポートされています。次の表は、オプションを説明しています。
Parameter | Description |
---|---|
skip_header | CSV 形式のデータファイルの最初の行をスキップするかどうかを指定します。タイプ: INTEGER。デフォルト値: 0 。一部の CSV 形式のデータファイルでは、最初の行は列名や列データ型などのメタデータを定義するために使用されます。 skip_header パラメータを設定することで、StarRocks がデータロード中にデータファイルの最初の行をスキップするようにできます。たとえば、このパラメータを 1 に設定すると、StarRocks はデータロード中にデータファイルの最初の行をスキップします。データファイルの最初の行は、ロードステートメントで指定した行区切り文字を使用して区切られている必要があります。 |
trim_space | CSV 形式のデータファイルから列区切り文字の前後のスペースを削除するかどうかを指定します。タイプ: BOOLEAN。デフォルト値: false 。一部のデータベースでは、データを CSV 形式のデータファイルとしてエクスポートする際に列区切り文字にスペースが追加されます。これらのスペースは、先行スペースまたは後続スペースと呼ばれます。 trim_space パラメータを設定することで、StarRocks がデータロード中にこれらの不要なスペースを削除するようにできます。ただし、StarRocks は、 enclose で指定された文字で囲まれたフィールド内のスペース(先行スペースおよび後続スペースを含む)を削除しません。たとえば、次のフィールド値は、パイプ (` |
enclose | CSV 形式のデータファイルでフィールド値を RFC4180 に従って囲むために使用される文字を指定します。タイプ: 単一バイト文字。デフォルト値: NONE 。最も一般的な文字は単一引用符 (' ) および二重引用符 (" ) です。enclose で指定された文字で囲まれたすべての特殊文字(行区切り文 字や列区切り文字を含む)は通常の記号と見なされます。StarRocks は、enclose で指定された文字として任意の単一バイト文字を指定できるため、RFC4180 よりも多くのことができます。フィールド値に enclose で指定された文字が含まれている場合、同じ文字を使用してその enclose で指定された文字をエスケープできます。たとえば、enclose を " に設定し、フィールド値が a "quoted" c の場合、このフィールド値をデータファイルに "a ""quoted"" c" として入力できます。 |
escape | 行区切り文字、列区切り文字、エスケープ文字、enclose で指定された文字などのさまざまな特殊文字をエスケープするために使用される文字を指定します。これらの文字は、StarRocks によって通常の文字と見なされ、それらが存在するフィールド値の一部として解析されます。タイプ: 単一バイト文字。デフォルト値: NONE 。最も一般的な文字はスラッシュ (\ ) で、SQL ステートメントでは二重スラッシュ (\\ ) として記述する必要があります。注意 escape で指定された文字は、enclose で指定された文字のペアの内側と外側の両方に適用されます。次の 2 つの例があります:
|
-
column_list
データファイルと StarRocks テーブルの間の列マッピングを指定します。構文:
(<column_name>[, <column_name> ...])
。column_list
で宣言された列は、名前によって StarRocks テーブルの列にマッピングされます。注意
データファイルの列が StarRocks テーブルの列に順番にマッピングされる場合、
column_list
を指定する必要はありません。データファイルの特定の列をスキップしたい場合、その列を一時的に StarRocks テーブルの列とは異なる名前にするだけで済みます。詳細については、loading overview を参照してください。
-
COLUMNS FROM PATH AS
指定したファイルパスから 1 つ以上のパーティションフィールドに関する情報を抽出します。このパラメータは、ファイルパスにパーティションフィールドが含まれている場合にのみ有効です。
たとえば、データファイルが
/path/col_name=col_value/file1
に保存されている場合、col_name
はパーティションフィールドであり、StarRocks テーブルの列にマッピングできます。このパラメータを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))
を指定してデータ変換を実装する必要があります。
- StarRocks テーブルは、順番に
-
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
のパラメータは次のように説明されています。Parameter Description hadoop.security.authentication 認証方法。有効な値: simple
およびkerberos
。デフォルト値:simple
。simple
はシンプル認証を表し、認証なしを意味し、kerberos
は Kerberos 認証を表します。username HDFS クラスターの NameNode にアクセスするために使用するアカウントのユーザー名。 password HDFS クラスターの NameNode にアクセスするために使用するアカウントのパスワード。 -
Kerberos 認証を使用する場合、
StorageCredentialParams
を次のように構成します:"hadoop.security.authentication" = "kerberos",
"kerberos_principal" = "nn/zelda1@ZELDA.COM",
"kerberos_keytab" = "/keytab/hive.keytab",
"kerberos_keytab_content" = "YWFhYWFh"StorageCredentialParams
のパラメータは次のように説明されています。Parameter Description 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_keytab Kerberos キータブファイルの保存パス。 kerberos_keytab_content Kerberos キータブファイルの Base64 エンコードされた内容。 kerberos_keytab
またはkerberos_keytab_content
のいずれかを指定することができます。
-
-
HA 構成
HDFS クラスターの NameNode に HA メカニズムを構成できます。これにより、NameNode が別のノードに切り替えられた場合でも、StarRocks は自動的に新しい NameNode を識別できます。これには次のシナリオが含まれます:
-
1 つの Kerberos ユーザーが構成された単一の HDFS クラスターからデータをロードする場合、ブローカー ベースのロードとブローカー フリーのロードの両方がサポートされています。
-
ブローカー ベースのロードを実行するには、少なくとも 1 つの独立したブローカー グループがデプロイされていることを確認し、
hdfs-site.xml
ファイルを HDFS クラスターを提供するブローカー ノードの{deploy}/conf
パスに配置します。StarRocks は、ブローカーの起動時に{deploy}/conf
パスを環境変数CLASSPATH
に追加し、ブローカーが HDFS ク ラスター ノードに関する情報を読み取れるようにします。 -
ブローカー フリーのロードを実行するには、クラスター内のすべての FE、BE、および CN ノードのデプロイメント ディレクトリの
conf/core-site.xml
にhadoop.security.authentication = kerberos
を設定し、kinit
コマンドを使用して Kerberos アカウントを構成するだけで済みます。
-
-
複数の Kerberos ユーザーが構成された単一の HDFS クラスターからデータをロードする場合、ブローカー ベースのロードのみがサポートされています。少なくとも 1 つの独立したブローカー グループがデプロイされていることを確認し、
hdfs-site.xml
ファイルを HDFS クラスターを提供するブローカー ノードの{deploy}/conf
パスに配置します。StarRocks は、ブローカーの起動時に{deploy}/conf
パスを環境変数CLASSPATH
に追加し、ブローカーが HDFS クラスター ノードに関する情報を読み取れるようにします。 -
複数の HDFS クラスターからデータをロードする場合(1 つまたは複数の Kerberos ユーザーが構成されているかどうかにかかわらず)、ブローカー ベースのロードのみがサポートされています。これらの HDFS クラスターのそれぞれに対して少なくとも 1 つの独立したブローカー グループがデプロイされていることを確認し、ブローカーが HDFS クラスター ノードに関する情報を読み取れるようにするために次のいずれかのアクションを実行します:
-
hdfs-site.xml
ファイルを HDFS クラスターを提供するブローカー ノードの{deploy}/conf
パスに配置します。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 構成のパラメータは次のように説明されています。
-
-
Parameter | Description |
---|---|
dfs.nameservices | HDFS クラスターの名前。 |
dfs.ha.namenodes.XXX | HDFS クラスター内の NameNode の名前。複数の NameNode 名を指定する場合は、カンマ (, ) で区切ります。xxx は dfs.nameservices で指定した HDFS クラスター名です。 |
dfs.namenode.rpc-address.XXX.NN | HDFS クラスター内の 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
に設定する必要があるパラメータは次のように説明されています。
Parameter | Required | Description |
---|---|---|
aws.s3.use_instance_profile | Yes | 資格情報メソッドのインスタンスプロファイルとアサインドロールを有効にするかどうかを指定します。有効な値: true および false 。デフォルト値: false 。 |
aws.s3.iam_role_arn | No | AWS S3 バケットに対する権限を持つ IAM ロールの ARN。AWS S3 にアクセスするための資格情報メソッドとしてアサインドロールを選択する場合、このパラメータを指定する必要があります。 |
aws.s3.region | Yes | AWS S3 バケットが存在するリージョン。例: us-west-1 。 |
aws.s3.access_key | No | IAM ユーザーのアクセスキー。AWS S3 にアクセスするための資格情報メソッドとして IAM ユーザーを選択する場合、このパラメータを指定する必要があります。 |
aws.s3.secret_key | No | IAM ユーザーのシークレットキー。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
に設定する必要があるパラメータは次のように説明されています。Parameter Default value Value example Description gcp.gcs.use_compute_engine_service_account false true Compute 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
に設定する必要があるパラメータは次のように説明されています。Parameter Default value Value example Description 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
に設定する必要があるパラメータは次のように説明されています。Parameter Default value Value example Description gcp.gcs.use_compute_engine_service_account false true Compute 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
に設定する必要があるパラメータは次のように説明されています。Parameter Default value Value example Description 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
に設定する必要があるパラメータは次のように説明されています。
Parameter | Required | Description |
---|---|---|
aws.s3.enable_ssl | Yes | SSL 接続を有効にするかどうかを指定します。有効な値: true および false 。デフォルト値: true 。 |
aws.s3.enable_path_style_access | Yes | パススタイルの URL アクセスを有効にするかどうかを指定します。有効な値: true および false 。デフォルト値: false 。MinIO の場合、値を true に設定する必要があります。 |
aws.s3.endpoint | Yes | AWS S3 ではなく、S3 互換ストレージシステムに接続するために使用されるエンドポイント。 |
aws.s3.access_key | Yes | IAM ユーザーのアクセスキー。 |
aws.s3.secret_key | Yes | IAM ユーザーのシークレットキー。 |
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
に設定する必要があるパラメータは次のように説明されています。Parameter Required Description azure.blob.storage_account Yes Blob Storage アカウントのユーザー名。 azure.blob.shared_key Yes Blob Storage アカウントの共 有キー。 -
SAS トークン認証方法を選択するには、
StorageCredentialParams
を次のように構成します:"azure.blob.storage_account" = "<storage_account_name>",
"azure.blob.container" = "<container_name>",
"azure.blob.sas_token" = "<storage_account_SAS_token>"StorageCredentialParams
に設定する必要があるパラメータは次のように説明されています。Parameter Required Description azure.blob.storage_account Yes Blob Storage アカウントのユーザー名。 azure.blob.container Yes データを格納する Blob コンテナの名前。 azure.blob.sas_token Yes Blob 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
に設定する必要があるパラメータは次のように説明されています。Parameter Required Description azure.adls2.oauth2_use_managed_identity Yes マネージド ID 認証方法を有効にするかどうかを指定します。値を true
に設定します。azure.adls2.oauth2_tenant_id Yes アクセスしたいデータのテナント ID。 azure.adls2.oauth2_client_id Yes マネージド ID のクライアント(アプリケーション)ID。 -
共有キー認証方法を選択するには、
StorageCredentialParams
を次のように構成します:"azure.adls2.storage_account" = "<storage_account_name>",
"azure.adls2.shared_key" = "<storage_account_shared_key>"StorageCredentialParams
に設定する必要があるパラメータは次のように説明されています。Parameter Required Description azure.adls2.storage_account Yes Data Lake Storage Gen2 ストレージアカウントのユーザー名。 azure.adls2.shared_key Yes Data 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
に設定する必要があるパラメータは次のように説明されています。Parameter Required Description azure.adls2.oauth2_client_id Yes サービスプリンシパルのクライアント(アプリケーション)ID。 azure.adls2.oauth2_client_secret Yes 作成された新しいクライアント(アプリケーション)シークレットの値。 azure.adls2.oauth2_client_endpoint Yes サービスプリンシパルまたはアプリケーションの OAuth 2.0 トークンエンドポイント(v1)。
Azure Data Lake Storage Gen1
ストレージシステムとして Data Lake Storage Gen1 を選択する場合、次のいずれかのアクションを実行します:
-
マネージドサービス ID 認証方法を選択するには、
StorageCredentialParams
を次のように構成します:"azure.adls1.use_managed_service_identity" = "true"
StorageCredentialParams
に設定する必要があるパラメータは次のように説明されています。Parameter Required Description azure.adls1.use_managed_service_identity Yes マネージドサービス 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
に設定する必要があるパラメータは次のように説明されています。
Parameter | Required | Description |
---|---|---|
azure.adls1.oauth2_client_id | Yes | クライアント(アプリケーション)ID。 |
azure.adls1.oauth2_credential | Yes | 作成された新しいクライアント(アプリケーション)シークレットの値。 |
azure.adls1.oauth2_endpoint | Yes | サービスプリンシパルまたはアプリケーションの OAuth 2.0 トークンエンドポイント(v1)。 |
opt_properties
ロードジョブ全体に適用されるオプションのパラメータを指定します。構文:
PROPERTIES ("<key1>" = "<value1>"[, "<key2>" = "<value2>" ...])
サポートされているパラメータは次のとおりです:
-
timeout
ロードジョブのタイムアウト期間を指定します。単位:秒。デフォルトのタイムアウト期間は 4 時間です。6 時間未満のタイムアウト期間を指定することをお勧めします。ロードジョブがタイムアウト期間内に完了しない場合、StarRocks はロードジョブをキャンセルし、ロードジョブのステータスは CANCELLED になります。
注意
ほとんどの場合、タイムアウト期間を設定する必要はありません。ロードジョブがデフォルトのタイムアウト期間内に完了しない場合にのみ、タイムアウト期間を設定することをお勧めします。
タイムアウト期間を推測するには、次の式を使用します:
タイムアウト期間 > (ロードするデータファイルの合計サイズ 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.」というエラーが報告されます。