- 11.2.1 运行实用程序
- 11.2.2 通过Mysqlsh命令接口导入JSON文档
--import11.2.3 使用命令导入JSON文档- 11.2.4 BSON数据类型表示的转换
MySQL Shell 的 JSON 导入实用程序 util.importJSON()使您能够将 JSON 文档从文件（或 FIFO 特殊文件）或标准输入导入到 MySQL Server 集合或关系表。该实用程序检查提供的 JSON 文档是否格式良好，并将其插入目标数据库，从而无需使用多个 INSERT语句或编写脚本来完成此任务。
您可以将 JSON 文档导入到现有表或集合，或者导入为导入而创建的新表或集合。如果指定数据库中不存在目标表或集合，实用程序将使用默认集合或表结构自动创建目标表或集合。默认集合是通过createCollection()从对象调用该函数来创建的schema。默认表创建如下：
解释CREATE TABLE `dbname`.`tablename` (
target_column JSON,
id INTEGER AUTO_INCREMENT PRIMARY KEY
) CHARSET utf8mb4 ENGINE=InnoDB;
默认集合名称或表名称是提供的导入文件的名称（不带文件扩展名），默认 target_column名称为doc.
JSON 导入实用程序可以处理 JSON 文档中表示的 BSON（二进制 JSON）数据类型。 BSON 文档中使用的数据类型并非全部由 JSON 原生支持，但可以使用 JSON 格式的扩展来表示。导入实用程序可以处理使用 JSON 扩展来表示 BSON 数据类型的文档，将它们转换为相同或兼容的 MySQL 表示形式，并使用该表示形式导入数据值。转换后的数据值可用于表达式和索引，并由 SQL 语句和 X DevAPI 函数进行操作。
要将 BSON 类型的 JSON 扩展转换为 MySQL 类型，您必须convertBsonTypes在运行导入实用程序时指定该选项。其他选项可用于控制特定 BSON 数据类型的映射和转换。如果导入带有 BSON 类型的 JSON 扩展的文档并且不使用此选项，则文档的导入方式与输入文件中的表示方式相同。
11.2.1 运行实用程序
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 数据类型的映射和转换；有关这些控制选项和默认类型转换的列表，请参阅 第 11.2.4 节，“BSON 数据类型表示的转换”。该convertBsonOid选项还必须设置为true，这是您指定 时该选项的默认设置convertBsonTypes: true。如果导入带有 BSON 类型的 JSON 扩展的文档并且不使用convertBsonTypes: true，则文档将以与输入文件中表示的方式相同的方式导入，作为嵌入的 JSON 文档。 -
convertBsonOid: true识别并转换 MongoDB ObjectID，它是用作文档值的 12 字节 BSON 类型
_id，以 MongoDB 扩展 JSON 严格模式表示。该选项的默认值是该选项的值convertBsonTypes，因此如果该选项设置为true，MongoDB ObjectID 也会自动转换。从 MongoDB 导入数据时，如果不转换 BSON 类型，则convertBsonOid必须始终设置为，因为 MySQL Server 需要将值转换为该 类型。true``_id``varbinary(32) -
extractOidTime: "\*field_name\*"_id识别并提取文档字段 中 MongoDB ObjectID 中包含的时间戳值 ，并将其放入导入数据中的单独字段中。extractOidTime命名文档中包含时间戳的字段。时间戳是ObjectID的前4个字节，保持不变。convertBsonOid: true必须设置才能使用此选项，convertBsonTypes设置为 true 时这是默认值。
以下示例，第一个在 MySQL Shell 的 JavaScript 模式下，第二个在 MySQL Shell 的 Python 模式下，将文件中的 JSON 文档导入 /tmp/products.json到 数据库products中的集合中 mydb：
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 会话的活动模式。因此，该实用程序将文件中的 JSON 文档导入到数据库中 /tmp/stores.json指定的集合中： stores``mydb
mysql-js> \use mydb
mysql-js> util.importJson("/tmp/stores.json")
以下示例在 MySQL Shell 的 JavaScript 模式下将文件中的 JSON 文档导入 到数据库中指定的关系表中的 /europe/regions.json列 。文档中通过 JSON 扩展表示的 BSON 数据类型将转换为 MySQL 表示形式： jsondata``regions``mydb
mysql-js> util.importJson("/europe/regions.json", {schema: "mydb", table: "regions", tableColumn: "jsondata", convertBsonTypes: true});
以下示例在 MySQL Shell 的 JavaScript 模式下执行相同的导入，但不将 BSON 数据类型的 JSON 表示形式转换为 MySQL 表示形式。然而，文档中的MongoDB ObjectID会按照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 节，“使用命令导入 JSON 文档--import”。
