このページは機械翻訳したものです。

8.2 JSON インポートユーティリティ

8.2.1 mysqlsh コマンドインタフェースを使用した JSON ドキュメントのインポート

8.2.2 --import コマンドを使用した JSON ドキュメントのインポート

8.2.3 BSON データ型の表現の変換

MySQL Shell 8.0.13 で導入された MySQL Shell JSON インポートユーティリティ util.importJSON() を使用すると、JSON ドキュメントをファイル (または FIFO 特殊ファイル) または標準入力から MySQL Server コレクションまたはリレーショナルテーブルにインポートできます。 このユーティリティは、指定された JSON ドキュメントが整形式であることをチェックしてターゲットデータベースに挿入するため、複数の INSERT ステートメントを使用したり、スクリプトを記述してこのタスクを実行する必要がなくなります。

MySQL Shell 8.0.14 から、インポートユーティリティは JSON ドキュメントで表される BSON (バイナリ JSON) データ型を処理できます。 BSON ドキュメントで使用されるデータ型はすべて JSON でネイティブにサポートされているわけではありませんが、JSON 形式の拡張機能を使用して表すことができます。 インポートユーティリティでは、JSON 拡張を使用して BSON データ型を表すドキュメントを処理し、それらを同一または互換性のある MySQL 表現に変換し、その表現を使用してデータ値をインポートできます。 変換された結果のデータ値は、式およびインデックスで使用でき、SQL ステートメントおよび X DevAPI 関数で操作できます。

JSON ドキュメントは、既存のテーブルまたはコレクション、またはインポート用に作成された新しいテーブルまたはコレクションにインポートできます。 ターゲットのテーブルまたはコレクションが指定したデータベースに存在しない場合は、デフォルトのコレクションまたはテーブル構造を使用してユーティリティによって自動的に作成されます。 デフォルトのコレクションは、schema オブジェクトから createCollection() 関数をコールすることで作成されます。 デフォルトテーブルは次のように作成されます:

CREATE TABLE `dbname`.`tablename` (
   target_column JSON,
   id INTEGER AUTO_INCREMENT PRIMARY KEY 
) CHARSET utf8mb4 ENGINE=InnoDB;

デフォルトのコレクション名またはテーブル名は、指定されたインポートファイルの名前 (ファイル拡張子なし) で、デフォルトの target_column 名は doc です。

BSON 型の JSON 拡張機能を MySQL 型に変換するには、インポートユーティリティの実行時に convertBsonTypes オプションを指定する必要があります。 特定の BSON データ型のマッピングおよび変換を制御するための追加オプションが使用可能です。 BSON タイプの JSON 拡張子を持つドキュメントをインポートし、このオプションを使用しない場合、ドキュメントは入力ファイルで表されるのと同じ方法でインポートされます。

JSON インポートユーティリティには、サーバーへの既存の X プロトコル 接続が必要です。 ユーティリティは、クラシック MySQL プロトコル 接続を介して動作できません。

MySQL Shell API では、JSON インポートユーティリティは util グローバルオブジェクトの関数であり、次のシグネチャを持ちます:

importJSON (path, options)

path は、インポートする JSON ドキュメントを含むファイルのファイルパスを指定する文字列です。 これには、ディスクに書き込まれたファイルまたは FIFO 特殊ファイル (名前付きパイプ) を指定できます。 標準入力は、ユーティリティの --import コマンドライン起動でのみインポートできます。

options はインポートオプションのディクショナリで、空の場合は省略できます。 (MySQL 8.0.14 より前は、ディクショナリが必要でした。) JSON ドキュメントをインポートする場所と方法を指定するには、次のオプションを使用できます:

schema: "db_name"

ターゲットデータベースの名前。 このオプションを省略すると、MySQL Shell は URI のような接続文字列、\use コマンドまたは MySQL Shell オプションで指定されているように、現在のセッションで使用されているスキーマ名を識別して使用しようとします。 スキーマ名が指定されておらず、セッションから識別できない場合は、エラーが返されます。

collection: "collection_name"

ターゲット収集の名前。 これは、テーブルとカラムを指定するかわりに使用できます。 コレクションが存在しない場合は、ユーティリティによって作成されます。 collection、table または tableColumn のいずれのオプションも指定しない場合、ユーティリティはデフォルトで、指定されたインポートファイルの名前 (ファイル拡張子なし) でターゲットコレクションを使用または作成します。

table: "table_name"

ターゲットテーブルの名前。 これは、コレクションを指定するかわりに使用できます。 テーブルが存在しない場合は、ユーティリティによって作成されます。

tableColumn: "column_name"

JSON ドキュメントがインポートされるターゲットテーブルのカラムの名前。 テーブルがすでに存在する場合は、指定したカラムがテーブルに存在する必要があります。 table オプションを指定して tableColumn オプションを省略すると、デフォルトのカラム名 doc が使用されます。 tableColumn オプションを指定して table オプションを省略した場合、指定したインポートファイルの名前 (ファイル拡張子なし) がテーブル名として使用されます。

convertBsonTypes: true

拡張機能を使用して JSON 形式に表される BSON データ型を認識および変換します。 このオプションのデフォルトは false です。 convertBsonTypes: true を指定すると、表現された BSON タイプはそれぞれ同一または互換性のある MySQL 表現に変換され、その表現を使用してデータ値がインポートされます。 特定の BSON データ型のマッピングおよび変換を制御するための追加オプションが使用可能です。これらの制御オプションおよびデフォルトの型変換のリストは、セクション8.2.3「BSON データ型の表現の変換」 を参照してください。 convertBsonOid オプションも true に設定する必要があります。これは、convertBsonTypes: true を指定した場合のオプションのデフォルト設定です。 BSON 型の JSON 拡張子を持つドキュメントをインポートし、convertBsonTypes: true を使用しない場合、ドキュメントは入力ファイルに埋め込まれた JSON ドキュメントとして表されるのと同じ方法でインポートされます。

convertBsonOid: true

MongoDB 拡張 JSON 厳密モードで表される、ドキュメントの_id 値として使用される 12 バイト BSON 型である MongoDB ObjectIDs を認識および変換します。 このオプションのデフォルトは convertBsonTypes オプションの値であるため、このオプションを true に設定すると、MongoDB ObjectIDs も自動的に変換されます。 MongoDB からデータをインポートする場合、MySQL Server では_id 値を varbinary(32) タイプに変換する必要があるため、BSON タイプを変換しない場合は、convertBsonOid を常に true に設定する必要があります。

extractOidTime: "field_name"

ドキュメントの_id フィールドの MongoDB ObjectID に含まれるタイムスタンプ値を認識して抽出し、インポートされたデータの別のフィールドに配置します。extractOidTime は、タイムスタンプを含むドキュメント内のフィールドに名前を付けます。 タイムスタンプは ObjectID の最初の 4 バイトで、変更されません。このオプションを使用するように convertBsonOid: true を設定する必要があります。これは、convertBsonTypes が true に設定されている場合のデフォルトです。

次の例 ( MySQL ShellJavaScript モードの最初の例と MySQL ShellPython モードの次の例) では、/tmp/products.json ファイルの JSON ドキュメントを mydb データベースの products コレクションにインポートします:

mysql-js> util.importJson("/tmp/products.json", {schema: "mydb", collection: "products"})

mysql-py> util.import_json("/tmp/products.json", {"schema": "mydb", "collection": "products"})

MySQL Shell JavaScript モードの次の例にはオプションが指定されていないため、ディクショナリは省略されます。mydb は、MySQL Shell セッションのアクティブなスキーマです。 したがって、ユーティリティは、ファイル/tmp/stores.json 内の JSON ドキュメントを mydb データベース内の stores という名前のコレクションにインポートします:

mysql-js> \use mydb
mysql-js> util.importJson("/tmp/stores.json")

MySQL ShellJavaScript モードの次の例では、ファイル/europe/regions.json の JSON ドキュメントを mydb データベースの regions というリレーショナルテーブルの jsondata カラムにインポートします。 JSON 拡張によってドキュメントで表される BSON データ型は、MySQL 表現に変換されます:

mysql-js> util.importJson("/europe/regions.json", {schema: "mydb", table: "regions", tableColumn: "jsondata", convertBsonTypes: true});

MySQL ShellJavaScript モードの次の例では、BSON データ型の JSON 表現を MySQL 表現に変換せずに、同じインポートを実行します。 ただし、ドキュメント内の MongoDB ObjectIDs は MySQL の要求に応じて変換され、タイムスタンプも抽出されます:

mysql-js> util.importJson("/europe/regions.json", {schema: "mydb", table: "regions", tableColumn: "jsondata", convertBsonOid: true, extractOidTime: "idTime"});

インポートが完了するか、Ctrl+C を持つユーザーまたはエラーによってインポートが途中で停止されると、正常にインポートされた JSON ドキュメントの数と該当するエラーメッセージを示すメッセージがユーザーに返されます。 関数自体が void を返すか、エラーの場合は例外を返します。

JSON インポートユーティリティは、コマンドラインからも起動できます。 コマンドラインの起動には、2 つの代替形式を使用できます。 ファイル (または FIFO 特殊ファイル) からの入力のみを受け入れる mysqlsh コマンドインタフェース、または標準入力またはファイルからの入力を受け入れる --import コマンドを使用できます。