STREAM LOAD

ストリームロード

説明

StarRocksでは、HTTPベースのストリームロードというデータローディングメソッドを提供しています。このメソッドを使用すると、ローカルファイルシステムまたはストリーミングデータソースからデータをロードすることができます。ロードジョブを送信した後、StarRocksは同期的にジョブを実行し、ジョブの結果をジョブが完了した後に返します。ジョブ結果に基づいて、ジョブが成功したかどうかを判断することができます。ストリームロードのアプリケーションシナリオ、制限事項、原則、およびサポートされているデータファイル形式についての詳細は、HTTP PUTを使用してローカルファイルシステムまたはストリーミングデータソースからデータをロードするを参照してください。

注記

• Stream Loadを使用してデータをStarRocksテーブルにロードした後、そのテーブルに作成されたマテリアライズドビューのデータも更新されます。
• Stream Loadを使用してStarRocksテーブルにデータをロードするには、StarRocksテーブルにINSERT権限を持つユーザーとしてのみロードすることができます。INSERT権限がない場合は、GRANTで説明されている手順に従って、StarRocksクラスタに接続するユーザーにINSERT権限を付与する必要があります。

構文

curl --location-trusted -u <username>:<password> -XPUT <url>
(
    data_desc
)
[opt_properties]

このトピックでは、curlを例に、Stream Loadのデータロード方法を説明します。curl以外にも、他のHTTP互換のツールや言語を使用してStream Loadを実行することもできます。ロードに関連するパラメータは、HTTPリクエストヘッダのフィールドに含まれています。これらのパラメータを入力する際には、以下の点に注意してください。

• このトピックでは、デモンストレーションのためにチャンク転送エンコードを使用しています。チャンク転送エンコードを選択しない場合は、転送されるコンテンツのサイズを示す Content-Length ヘッダフィールドを入力する必要があります。これにより、データの整合性が確保されます。

  注記

  Stream Loadの実行にcurlを使用する場合、StarRocksは自動的に Content-Length ヘッダフィールドを追加するため、手動で入力する必要はありません。

• Expect ヘッダフィールドを追加し、「100-continue」という値を指定します。これにより、ジョブリクエストが拒否された場合に不要なデータ転送とリソースのオーバーヘッドを防ぐことができます。

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

パラメータ

usernameとpassword

StarRocksクラスタに接続するために使用するアカウントのユーザー名とパスワードを指定します。このパラメータは必須です。パスワードを設定していないアカウントを使用する場合は、<username>:のみを入力する必要があります。

XPUT

HTTPリクエストメソッドを指定します。このパラメータは必須です。Stream LoadではPUTメソッドのみがサポートされています。

url

StarRocksテーブルのURLを指定します。構文:

http://<fe_host>:<fe_http_port>/api/<database_name>/<table_name>/_stream_load

以下の表はURLのパラメータについて説明しています。

パラメータ	必須	説明
fe_host	Yes	StarRocksクラスタのFEノードのIPアドレス。 注記 ロードジョブを特定のBEノードに送信する場合は、BEノードのIPアドレスを入力する必要があります。
fe_http_port	Yes	StarRocksクラスタのFEノードのHTTPポート番号。デフォルトのポート番号は8030です。 注記 ロードジョブを特定のBEノードに送信する場合は、BEノードのHTTPポート番号を入力する必要があります。デフォルトのポート番号は8030です。
database_name	Yes	StarRocksテーブルが属するデータベースの名前。
table_name	Yes	StarRocksテーブルの名前。

注記

SHOW FRONTENDSを使用して、FEノードのIPアドレスとHTTPポート番号を表示することができます。

data_desc

ロードしたいデータファイルを記述します。data_desc ディスクリプタには、データファイルの名前、形式、列区切り文字、行区切り文字、宛先パーティション、およびStarRocksテーブルに対する列マッピングを含めることができます。構文:

-T <file_path>
-H "format: CSV | JSON"
-H "column_separator: <column_separator>"
-H "row_delimiter: <row_delimiter>"
-H "columns: <column1_name>[, <column2_name>, ... ]"
-H "partitions: <partition1_name>[, <partition2_name>, ...]"
-H "temporary_partitions: <temporary_partition1_name>[, <temporary_partition2_name>, ...]"
-H "jsonpaths: [ \"<json_path1>\"[, \"<json_path2>\", ...] ]"
-H "strip_outer_array:  true | false"
-H "json_root: <json_path>"

data_descディスクリプタのパラメータは、次の3つのタイプに分類できます: 一般的なパラメータ、CSVパラメータ、およびJSONパラメータ。

一般的なパラメータ

パラメータ	必須	説明
file_path	Yes	データファイルの保存パス。ファイル名の拡張子を省略することもできます。
format	No	データファイルの形式。有効な値: CSV および JSON。デフォルト値: CSV。
partitions	No	データファイルをロードするパーティション。このパラメータを指定しない場合、StarRocksはデフォルトでStarRocksテーブルのすべてのパーティションにデータファイルをロードします。
temporary_partitions	No	データファイルをロードする 一時パーティション の名前。複数の一時パーティションを指定することもできます。複数の一時パーティションはカンマ（,）で区切られている必要があります。
columns	No	データファイルとStarRocksテーブルの間の列マッピング。 データファイルのフィールドがStarRocksテーブルの列に順番通りにマッピングできる場合、このパラメータを指定する必要はありません。代わりに、このパラメータを使用してデータ変換を実装することができます。たとえば、CSVデータファイルをロードし、ファイルに2つの列が含まれており、これらの列が2つのStarRocksテーブルの列 id と city に順番にマッピングできる場合、 "columns: city,tmp_id, id = tmp_id * 100" を指定できます。詳細については、このトピックの「 列マッピング 」のセクションを参照してください。

CSVパラメータ

パラメータ	必須	説明
column_separator	No	データファイルのフィールドを区切るために使用される文字。このパラメータを指定しない場合、デフォルトで \t が使用されます（タブを意味します）。指定する列区切り文字は、データファイルで使用されている列区切り文字と同じであることを確認してください。 注記 CSVデータの場合、長さが50バイトを超えないUTF-8文字列（カンマ（,）、タブ、またはパイプ（
row_delimiter	No	データファイルのフィールドを区切るために使用される文字。このパラメータを指定しない場合、デフォルトで \n が使用されます。
skip_header	No	データファイルがCSV形式の場合、データロード時にデータファイルの最初の数行をスキップするかどうかを指定します。型: INTEGER。デフォルト値: 0。 CSV形式のデータファイルでは、冒頭の数行が列名や列のデータ型などのメタデータを定義するために使用される場合があります。skip_headerパラメータを設定することで、データロード時にデータファイルの最初の数行をスキップできます。たとえば、このパラメータを 1 に設定すると、データロード時にはデータファイルの最初の行がスキップされます。 データファイルの冒頭の数行は、ロードコマンドで指定した行区切り文字で区切られている必要があります。
trim_space	No	CSV形式のデータファイルの列区切りの前後にあるスペースを除去するかどうかを指定します。型: BOOLEAN。デフォルト値: false。 一部のデータベースでは、CSV形式のデータをエクスポートする際に列区切りの前後にスペースが追加されます。このようなスペースは、場所に応じて先頭スペースまたは末尾スペースと呼ばれます。trim_spaceパラメータを設定することにより、データロード時に不要なスペースを除去できます。 なお、encloseで指定された文字で囲まれたフィールド内のスペース（先頭スペースおよび末尾スペースを含む）はStarRocksによって削除されません。たとえば、次のフィールド値はパイプ（`

|"Love StarRocks"| 
|" Love StarRocks "| 
|"Love StarRocks" |

trim_spaceをtrueに設定すると、StarRocksは先頭のフィールド値を次のように処理します:

|"Love StarRocks"| 
|" Love StarRocks "| 
|"Love StarRocks" |

| encloseクロージャ | No | RFC4180 に従って、CSV形式のデータファイル内のフィールド値をラップするために使用する文字を指定します。パラメータタイプ: シングルバイト文字。デフォルト値: NONE。もっとも一般的な文字はシングルクォーテーション（'）やダブルクォーテーション（"）です。 encloseで指定された文字でラップされた特殊文字（行区切り文字や列区切り文字を含む）は、通常のシンボルとみなされます。StarRocksはRFC4180を超えることができるため、任意のシングルバイト文字を enclose で指定することができます。 フィールド値に encloseで指定された文字が含まれる場合は、同じ文字を使用してその文字をエスケープすることができます。たとえば、encloseを"に設定し、フィールド値が a "quoted" c の場合、"a ""quoted"" c" という形式でフィールド値を入力できます。 | | escape | No | さまざまな特殊文字（行区切り文字、列区切り文字、エスケープ文字、および enclose で指定された文字）をエスケープするために使用される文字を指定します。パラメータタイプ: シングルバイト文字。デフォルト値: NONE。もっとも一般的な文字はスラッシュ（/）ですが、SQL文ではスラッシュをバックスラッシュ（\\）で書く必要があります。 注記 escapeで指定された文字は、encloseで指定された文字の対内外、両方に適用されます。 以下に2つの例を示します:

• encloseを"に設定し、escapeを \に設定した場合、StarRocksは"say \"Hello world\""を say "Hello world"にパースします。
• 列区切りがカンマ（,）の場合を想定します。escapeを\に設定した場合、StarRocksは a, b\, c を2つの別々のフィールド値としてパースします: a と b, c。

|

注記

• CSVデータの場合、長さが50バイトを超えないUTF-8文字列（カンマ（,）、タブ、またはパイプ（|）など）をテキストデリミタとして使用することができます。
• NULL値は\Nと表記します。たとえば、データファイルが3つの列で構成されており、そのデータファイルのレコードには1つ目と3つ目の列にデータが含まれており、2つ目の列にデータが含まれない場合、2つ目の列はNULL値を表すために\Nを使用する必要があります。これは、レコードを a,,b の代わりに a,\N,b のようにコンパイルすることを意味します。a,,b は、レコードの2つ目の列が空文字列を保持することを意味します。
• skip_header、trim_space、enclose、およびescapeを含む形式オプションは、v3.0以降でサポートされています。

JSONパラメータ

パラメータ	必須	説明
jsonpaths	No	JSONデータファイルからロードするキーの名前を指定します。一致モードでJSONデータをロードする場合にのみ、このパラメータを指定する必要があります。このパラメータの値はJSON形式で指定します。詳細については、 JSONデータロードのための列マッピングを設定します を参照してください。
strip_outer_array	No	外部の配列構造を削除するかどうかを指定します。有効な値: true および false。デフォルト値: false。 実世界のビジネスシナリオでは、JSONデータは外部の配列構造を持つ場合があります。この場合、 true に設定することをお勧めします。よって、StarRocksは外部の角括弧 [] を削除し、それぞれの内部配列を別々のデータレコードとしてロードします。false に設定すると、StarRocksはJSONデータ全体を1つの配列としてパースし、その配列を単一のデータレコードとしてロードします。 たとえば、JSONデータが [ {"category" : 1, "author" : 2}, {"category" : 3, "author" : 4} ] の場合、true に設定すると、 {"category" : 1, "author" : 2} と {"category" : 3, "author" : 4} は、別々のデータレコードとしてパースされ、別々のStarRocksテーブルの行にロードされます。
json_root	No	JSONデータファイルからロードするJSONデータのルート要素を指定します。一致モードでJSONデータをロードする場合にのみ、このパラメータを指定する必要があります。このパラメータの値は有効なJsonPath文字列です。デフォルトでは、このパラメータの値は空であり、JSONデータのすべてのデータがロードされます。詳細については、このトピックの「 ルート要素を指定して一致モードでJSONデータをロードする 」のセクションを参照してください。
ignore_json_size	No	HTTPリクエストのJSON本文のサイズをチェックするかどうかを指定します。 注記 デフォルトでは、HTTPリクエストのJSON本文のサイズは100MBを超えることはできません。JSON本文のサイズが100MBを超える場合、「The size of this batch exceed the max size [104857600] of json type data data [8617627793]. Set ignore_json_size to skip check, although it may lead huge memory consuming.」というエラーが報告されます。このエラーを