MySQL :: MySQL Shell 9.0 :: 11.2.1 執行工具程式

版本 9.0

8.4 目前版本
8.0

MySQL Shell 9.0 / ... / 執行工具程式

11.2.1 執行工具程式

JSON 匯入工具程式需要與伺服器建立現有的 X Protocol 連線。此工具程式無法透過傳統 MySQL Protocol 連線運作。

在 MySQL Shell API 中，JSON 匯入工具程式是 util 全域物件的函式，並具有以下簽名

importJSON (path, options)

path 是字串，指定包含要匯入之 JSON 檔案的文件路徑。這可以是寫入磁碟的檔案，或是 FIFO 特殊檔案 (具名管道)。

options 是匯入選項的字典，如果為空則可以省略。下列選項可指定 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 資料類型的對應和轉換；如需這些控制選項和預設類型轉換的清單，請參閱第 11.2.4 節，「BSON 資料類型表示法的轉換」。convertBsonOid 選項也必須設定為 true，這是當您指定 convertBsonTypes: true 時該選項的預設設定。如果您匯入具有 BSON 類型 JSON 擴充功能的文件，且未使用 convertBsonTypes: true，則文件會以與輸入檔案中表示相同的方式匯入，作為內嵌 JSON 文件。
convertBsonOid: true: 辨識並轉換 MongoDB ObjectIDs，這是 12 位元組的 BSON 類型，用於作為文件的 _id 值，以 MongoDB Extended JSON 嚴格模式表示。此選項的預設值為 convertBsonTypes 選項的值，因此如果該選項設定為 true，也會自動轉換 MongoDB ObjectIDs。從 MongoDB 匯入資料時，如果您不轉換 BSON 類型，則必須始終將 convertBsonOid 設定為 true，因為 MySQL Server 要求將 _id 值轉換為 varbinary(32) 類型。
extractOidTime: "field_name": 辨識並擷取 MongoDB ObjectID 中包含的時間戳記值，該值位於文件的 _id 欄位中，並將其放置在匯入資料中的個別欄位中。extractOidTime 會在文件中命名包含時間戳記的欄位。時間戳記是 ObjectID 的前 4 個位元組，保持不變。convertBsonOid: true 必須設定才能使用此選項，這是當 convertBsonTypes 設定為 true 時的預設值。

以下範例，第一個範例在 MySQL Shell 的 JavaScript 模式中，第二個範例在 MySQL Shell 的 Python 模式中，會將 /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 Shell JavaScript 模式中的以下範例會將 /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 Shell JavaScript 模式中的以下範例會執行相同的匯入，但不將 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 匯入工具程式。命令列叫用有兩種替代格式可用。您可以使用 mysqlsh 命令介面，該介面僅接受來自檔案 (或 FIFO 特殊檔案) 的輸入，或 --import 命令，該命令接受來自標準輸入或檔案的輸入。如需指示，請參閱第 11.2.2 節，「使用 Mysqlsh 命令介面匯入 JSON 文件」或第 11.2.3 節，「使用 --import 命令匯入 JSON 文件」。