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 のいずれのオプションも指定しない場 合、ユーティリティはデフォルトで、指定されたインポートファイルの名前 (ファ イル拡張子なし) でターゲットコレクションを使用または作成します。このページは機械翻訳したものです。
JSON インポートユーティリティ
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"});
mysqlsh コマンドインタフェースを使用した JSON ドキュメントのインポート
インポートが完了するか、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 インポート ユーティリティの場合は、次のようにパラメータを指定します:
user
JSON インポートユーティリティの実行に使用されるユーザーアカウントのユーザー名。ホスト
MySQL サーバーのホスト名。port
MySQL サーバーへの MySQL Shell 接続のポート番号。 この接続のデフォルトポートは 33060 です。mydb
ターゲットデータベースの名前。 コマンドラインから JSON インポートユーティリティを起動する場 合は、ターゲットデータベースを指定する必要があります。 URI のような接続文字列に指定すること も、追加の --schema コマンドラインオプションを使用することもできます。パス
インポートする JSON ドキュメントを含むファイル (または FIFO 特殊ファイル) のファイルパス。options --collection、--table および --tableColumn オプションでは、ターゲットコレクションまたはターゲット
テーブルとカラムを指定します。 mysqlsh コマンドインタフェースを使用して JSON インポートユー ティリティを起動した場合の関係およびデフォルトは、対応するオプションが MySQL Shell セッショ ンで使用された場合と同じです。 これらのオプションのいずれも指定しない場合、ユーティリティは デフォルトで、指定されたインポートファイルの名前 (ファイル拡張子なし) でターゲットコレクション を使用または作成します。--convertBsonTypes オプションは、拡張機能を使用して表される BSON データ型を JSON 形式に変換
します。 特定の BSON データ型の追加の制御オプションも指定できます。これらの制御オプションお よびデフォルトの型変換のリストは、セクション8.2.3「BSON データ型の表現の変換」 を参照してく ださい。 --convertBsonTypes を指定すると、--convertBsonOid オプションが自動的にオンに設定され ます。 MySQL Server では_id 値を varbinary(32) タイプに変換する必要があるため、MongoDB から データをインポートする際に BSON タイプを変換しない場合は、--convertBsonOid を指定する必要が あります。--extractOidTime=field_name を使用すると、_id 値から別のフィールドにタイムスタンプを 抽出できます。次の例では、ファイル products.json の JSON ドキュメントを mydb データベースの products コレクションにイン ポートします:
mysqlsh user@localhost/mydb -- util importJson products.json --collection=products
8.2.2 --import コマンドを使用した JSON ドキュメントのインポート
--import コマンドは、JSON インポートユーティリティのコマンドライン起動用の mysqlsh コマンドインタフェー
スのかわりに使用できます。 このコマンドは、オプション名を使用せずに短い形式の構文を提供し、標準入力から JSON ドキュメントを受け入れます。 構文は次のとおりです:mysqlsh user@host:port/mydb --import <path> [target] [tableColumn] [options]