データのインポート
このページは英語版のページが機械翻訳されたものです。英語版との間に矛盾または不一致がある場合は、英語版を正としてください。
このドキュメントでは、ScalarDB Data Loader のインポート機能について説明します。
機能
- JSON または JSON Lines ファイルからデータをインポート
- ソースフィールド名マッピングに基づく自動データマッピング
- JSON 制御ファイルによるカスタムデータマッピング
- 1つのレコードまたは行から複数のテーブルにデータをインポート
- INSERT、UPDATE、UPSERT のサポート
使用方法
Data Loader のインポート機能は、次の最小限の設定で開始できます:
./scalardb-data-loader import --config scalardb.properties --namespace namespace --table tableName
上記の設定により、制御ファイルが使用されず、データマッピングが自動的に適用されるインポートプロセスが開始されます。
新規または既存のデータを正常にインポートするには、次の手順を実行してください
-
インポートする必要があるデータを含むソースファイルを準備します。
-
適切なインポートモードを選択します。デフォルトでは、インポートは
upsertモードで実行されます。つまり、新しい場合はデータが挿入され、パーティションキーやクラスタリングキーが見つかった場合は更新されます。その他のオプションは、insertモードま たはupdateモードです。 -
データをインポートする正しい
namespaceおよびtable名を見つけます。 -
各データ行に対して
all required columnsチェックを実行するかどうかを決定します。有効にすると、列が欠落しているデータ行は失敗として扱われ、インポートされません。 -
successおよびfailed出力ファイルのパス名を指定します。デフォルトでは、Data Loader は作業ディレクトリにファイルを作成します。 -
JSON データを処理する場合、成功または失敗のログファイルの JSON 出力を
pretty printにするかどうかを決定します。デフォルトでは、このオプションはパフォーマンスのために無効になっています -
必要に応じて
threads引数を指定してパフォーマンスを調整します -
コマンドラインからインポートを実行して、データのインポートを開始します。実行中の ScalarDB インスタンスに応じて、ScalarDB Data Loader を正しい
storageまたはtransactionモードで実行してください。
コマンドラインオプション
ScalarDB Data Loader で使用できるオプションの一覧を次に示します。
| オプション | 説明 | 使用方法 |
|---|---|---|
| --mode | ScalarDB の 実行モード。省略した場合、デフォルト値は storage です。 | scalardb-data-loader --mode transaction |
| --config | 設定ファイルへのパス。省略した場合、ツールは現在のフォルダーで scalardb.properties という名前のファイルを検索します。 | scalardb-data-loader --config scalardb.properties |
| --namespace | テーブルデータをエクスポートする名前空間。制御ファイルが指定されていない場合は必須です。 | scalardb-data-loader --namespace namespace |
| --table | データをエクスポートするテーブルの名前。制御ファイルが指定されていない場合は必須です。 | scalardb-data-loader --table tableName |
| --import-mode | ScalarDB テーブルにデータをインポートするモード。サポートされているモードは insert、update、および upsert です。オプション。デフォルトでは、値は upsert に設定されています。 | scalardb-data-loader --import-mode=upsert |
| --all-columns-required | 設定されている場合、列が欠落しているデータ行はインポートできません。オプションです。デフォルトでは、チェックは実行されません。 | scalardb-data-loader --all-columns-required |
| --file | インポートするファイルへのパスを指定します。必須。 | scalardb-data-loader --file <pathToFile> |
| --success | 成功したインポート結果を書き込むために作成されるファイルへのパス。成功したインポート結果と失敗したインポート結果は、両方とも別のファイルに書き込まれます。 オプシ ョンです。デフォルトでは、現在の作業ディレクトリに新しいファイルが作成されます。 注: ファイルが既に存在する場合は、上書きされます。 | scalardb-data-loader --success <path to file> |
| --failed | 失敗したインポート結果を書き込むために作成されるファイルへのパス。 オプション。デフォルトでは、現在の作業ディレクトリに新しいファイルが作成されます。 注: ファイルがすでに存在する場合は、上書きされます。 | scalardb-data-loader --failed <path to file> |
| --threads | 同時処理のスレッド数。 | scalardb-data-loader --threads 500 |
| --format | インポートファイルの形式。json および jsonl ファイルがサポートされています。オプション。デフォルトでは値 json が選択されます。 | scalardb-data-loader --format json |
| --ignore-null | ソースファイル内の null 値は無視されます。つまり、既存のデータは上書きされません。オプション。デフォルトでは値は false です。 | scalardb-data-loader --ignore-null |
| --pretty | 設定すると、成功ファイルと失敗ファイルへの出力は pretty print モードで行われます。デフォルトでは、このオプションは有効になっていません。 | scalardb-data-loader --pretty |
| --control-file | カスタムデータマッピングやマルチテーブルインポートのルールを指定する JSON 制御ファイルへのパス。 | scalardb-data-loader --control-file control.json |
| --control-file-validation-level | 制御ファイル の検証レベル。MAPPED、KEYS、または FULL。オプションで、デフォルトではレベルは MAPPED に設定されています。 | scalardb-data-loader --control-file-validation-level FULL |
| --log-put-value | ScalarDB PUT 操作で使用された値がログファイルに含まれるかどうか。オプションで、デフォルトでは無効になっています。 | scalardb-data-loader --log-put-value |
| --error-file-required | インポートファイルに CSV データが含まれている場合に、オプションの JSON タイプのエラーファイルをエクスポートします。デフォルトでは、このオプションは無効になっています。 | scalardb-data-loader --error-file-required |
| --error | インポートファイルに CSV データが含まれている場合に、オプションのエラーファイルを指定します。 | scalardb-data-loader --error <pathToFile> |
| --delimiter | インポートファイルに CSV データが含まれている場合に、カスタム区切り文字を指定します。 | scalardb-data-loader --delimiter <value> |
| --header | インポートファイルに CSV データが含まれていて、ヘッダー行がない場合に、ヘッダー行データを指定します。 | scalardb-data-loader --header <value> |
インポートモード
Data Loader は、次のインポートモードをサポートしてい ます:
| モード | 説明 |
|---|---|
| INSERT | 各ソースレコードは新しいデータとして扱われます。パーティションとクラスタリングキーに基づいて、ScalarDB テーブルにデータがすでに存在する場合、このソースデータのインポートは失敗します。 |
| UPDATE | 各ソースレコードは、ScalarDB テーブル内の既存のデータの更新として扱われます。パーティションキーとクラスタリングキーに基づいて、テーブルにデータが存在しない場合、このソースデータのインポートは失敗します。 |
| UPSERT | ターゲット ScalarDB テーブルにすでにデータが含まれている場合、インポートは UPDATE によって行われます。ターゲットデータがない場合は、INSERT として扱われます。 |
注:
INSERT の場合、自動マッピングまたは制御ファイルによるカスタムマッピングによって、各ターゲット列のソースファイル内に一致するフィールドが必要です。これは、INSERT に変わる UPSERT にも適用されます。
データマッピング
自動マッピング
制御ファイルが指定されていない場合、Data Loader はソース JSON データ内のフィールドを ScalarDB テーブル内の使用可能な列に自動的にマッピングします。名前が一致せず、すべての列が必須である場合は、検証エラーとして扱われます。この場合、このレコードのインポートは失敗し、結果は失敗した出力ログに追加されます。
カスタムマッピング
ソースフィールドがターゲット列名と一致しない場合は、制御ファイルを使用する必要があります。この制御ファイルでは、フィールド名のカスタムマッピングルールを指定できます。
たとえば、次の制御ファイルは、ソースファイルのフィールド custom_id をターゲットテーブルの id にマッピングします。
{
"tables": [{
"namespace": "sample",
"table_name": "table1",
"mappings": [{
"source_field": "custom_id",
"target_column": "id"
}]
}
]
}
制御ファイル
カスタムデータマッピングまたは複数テーブルのインポートを可能にするために、Data Loader は JSON 制御ファイルによる設定をサポートしています。このファイルは、Data Loader を起動するときに --control-file 引数で渡す必要があります。
制御ファイルの検証レベル
制御ファイルの検証を強制するために、Data Loader では検証レベルを指定できます。設定されたレベルに基づいて、Data Loader は事前チェックを実行し、レベルルールに基づいて制御ファイルを検証します。
次のレベルがサポートされています。
| レベル | 説明 |
|---|---|
| FULL | この検証では、制御ファイルにターゲット ScalarDB テーブルの各列のマッピングがあることを確認します。 |
| KEYS | この検証では、各 ScalarDB テーブルパーティションのマッピングと、使用可能な場合は制御ファイルマッピングのクラスタリングキー列のマッピングが使用可能であることを確認します。 |
| MAPPED | この検証では、指定されたソースフィールドとターゲット列が、制御ファイルで指定されたマッピングに対してのみ存在することを確認します。 その他のフィールドはチェックされません。 |
検証レベルはオプションであり、Data Loader の起動時に --control-file-validation-level 引数で設定できます。
注:
この検証は事前チェックとして実行されるものであり、インポートプロセスが自動的に成功することを意味するものではありません。
例:レベルがマップ済みに設定されていて、制御ファイルに INSERT の各列のマッピングが含まれていない場合、INSERT にはすべての列をマップする必要があるため、インポートプロセスは失敗します。
複数テーブルのインポート
Data Loader は、複数テーブルのターゲットインポートをサポートしています。
JSON または JSON Lines ファイル内の1つの行を、制御ファイルでテーブルマッピングルールを指定することにより、複数のテーブルにインポートできます。現在、制御ファイルなしでは複数テーブルのインポートはサポートされていません。
ScalarDB トランザクションモードで複数テーブルのインポートを使用する場合、各テーブルのインポートごとにトランザクションが作成されます。例: ソースレコードが制御ファイルで3つのテーブルにマップされている場合、3つの個別のトランザクションが作成されます。
例: 次のソースレコードを table1 と table2 にインポートするには、次の手順を実行します:
| Table1 | Table2 |
|---|---|
| Id | Id |
| price | amount |
ソースレコード
[{
"custom_id": 1,
"custom_price": 1000,
"custom_amount": 100
}]
制御ファイル
{
"tables": [{
"namespace": "sample",
"table_name": "table1",
"mappings": [{
"source_field": "custom_id",
"target_column": "id"
}, {
"source_field": "custom_price",
"target_column": "price"
}]
},
{
"namespace": "sample",
"table_name": "table2",
"mappings": [{
"source_field": "custom_id",
"target_column": "id"
}, {
"source_field": "custom_amount",
"target_column": "amount"
}]
}
]
}
出力ログ
インポートタスクを開始すると、Data Loader はインポート結果を2つのファイルに記録します。1 つのファイルには正常にインポートされたインポートデータが含まれ、もう1つのファイルにはインポートできなかったデータが含まれます。失敗したデータには、データをインポートできなかった理由を説明する追加フィールドが含まれます。このフィールドは data_loader_import_status と呼ばれます。
失敗したインポートを含むファイルは、問題を修正するために編集し、そのまま新しいインポートタスクのソースファイルとして使用できます。エラーを含む data_loader_import_status フィールドを最初に削除する必要はありません。このフィールドはインポートプロセス中に無視され、元の値は成功または失敗した出力ファイルの新しいバージョンには含まれません。
正常にインポートされたデータを含むファイルには data_loader_import_status フィールドも含まれます。このファイルは、インポートされた各データ行に関するステータスメッセージ（新しい行が作成されたか、既存のデータが更新されたか）を含みます。
ログ形式
| フィールド | 説明 |
|---|---|
| action | データレコードのインポートプロセスの結果。UPDATE、INSERT、または FAILED_DURING_VALIDATION。 |
| namespace | データがインポートされるテーブルの名前空間。 |
| tablename | データがインポートされるテーブルの名前。 |
| is_data_mapped | 使用可能な制御ファイルに基づいて、カスタムデータマッピングが適用されたかどうか。 |
| tx_id | トランザクションの ID。Data Loader が transaction モードで実行されている場合にのみ使用できます。 |
| value | オプションのデータマッピング後の最終値。Data Loader が PUT 操作で使用する値。 |
| row_number | ソースデータの行番号またはレコード番号。 |
| Errors | インポートプロセス中に問題が発生した検証エラーまたはその他のエラーのリスト。 |
JSON 形式の成功ログファイルの例:
[{
"column_1": 1,
"column_2": 2,
"column_n": 3,
"data_loader_import_status": {
"results": [{
"action": "UPDATE",
"namespace": "namespace1",
"tableName": "table1",
"is_data_mapped": true,
"tx_id": "value",
"value": "value",
"row_number": "value"
}]
}
}]
JSON 形式の失敗したログファイルの例:
[{
"column_1": 1,
"column_2": 2,
"column_n": 3,
"data_loader_import_status": {
"results": [{
"action": "FAILED_DURING_VALIDATION",
"namespace": "namespace1",
"tableName": "table1",
"is_data_mapped": false,
"value": "value",
"row_number": "value",
"errors": [
"missing columns found during validation"
]
}]
}
}]
データの重複
Data Loader は重複を単独では処理しません。ScalarDB トランザクションモードでは、同じターゲットデータを連続して更新しようと すると No Mutation エラーが発生しますが、これは Data Loader では処理されません。これらの失敗したデータ行は、失敗したインポート結果の出力ファイルに追加され、後でインポートを再試行できます。
ただし、Data Loader では正しい状態を保証できないため、インポートファイルに同じパーティションキーやクラスタリングキーの更新や挿入が含まれていないことを確認することをお勧めします。
ストレージモードとトランザクションモード
ScalarDB はストレージモードとトランザクションモードの両方をサポートしており、このサポートは Data Loader のインポートプロセスに含まれています。
ローダーがストレージモードで起動されると、各インポートは非トランザクション方式で実行されます。
ローダーをトランザクションモードで起動すると、トランザクションを使用してデータがインポートされます。現在、各行は個別のトランザクションを介してインポートされます。1つのレコードを複数のテーブルにインポートする場合、各テーブルのインポートごとに個別のトランザクションが作成されます。