11.2.1 运行实用程序_MySQL 外壳 8.0

MySQL 外壳 8.0 / 第 11 章 MySQL Shell 实用程序 / 11.2 JSON 导入实用程序 / 11.2.1 运行实用程序

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-like 连接字符串、\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 服务器要求将值转换为类型。 true_idvarbinary(32)
extractOidTime: "field_name": 识别并提取文档字段中 MongoDB ObjectID 中包含的时间戳值 _id，并将其放入导入数据的单独字段中。 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集合： storesmydb

mysql-js> \use mydb
mysql-js> util.importJson("/tmp/stores.json")

以下示例在 MySQL Shell 的 JavaScript 模式下将文件中的 JSON 文档导入到数据库中命名的关系表 /europe/regions.json的列中。在文档中由 JSON 扩展表示的 BSON 数据类型被转换为 MySQL 表示： jsondataregionsmydb

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 节，“使用--import命令导入 JSON 文档”。