Documentation Home

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"

目标集合的名称。这是指定表和列的替代方法。如果该集合不存在,实用程序会创建它。如果您未指定 、 或 选项中的任何一个collectiontabletableColumn实用程序默认使用或创建具有提供的导入文件名称(不带文件扩展名)的目标集合。

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 文档”