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 ドキュメントは、既存のテーブルまたはコレクション、またはインポート用に作成された新しいテーブル またはコレクションにインポートできます。 ターゲットのテーブルまたはコレクションが指定したデータベース
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 を使用しない場合、ドキュメントは入力ファイルmysqlsh コマンドインタフェースを使用した JSON ドキュメントのインポート
に埋め込まれた 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 コマンドを使用できます。
8.2.1 mysqlsh コマンドインタフェースを使用した JSON ドキュメントのイン ポート
mysqlsh コマンドインタフェースを使用して、次のように JSON インポートユーティリティを起動します:
mysqlsh user@host:port/mydb -- util importJson <path> [options]
ormysqlsh user@host:port/mydb -- util import-json <path> [options]
この構文の詳細は、セクション5.8「API コマンドラインインタフェース」 を参照してください。 JSON インポー トユーティリティの場合は、次のようにパラメータを指定します: