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

版本 8.4

9.0
8.0

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

11.2.1 執行工具程式

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

在 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 伺服器要求將 _id 值轉換為 varbinary(32) 類型。
extractOidTime: "field_name": 識別並擷取 MongoDB ObjectID 中包含的 Timestamp 值，該值位於檔案的 _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 文件」。