MySQL :: MySQL Shell 9.0 :: 11.2.1 运行实用程序

版本 9.0

8.4 当前
8.0

MySQL Shell 9.0 / ... / 运行实用程序

11.2.1 运行实用程序

JSON 导入实用程序需要与服务器建立现有的 X 协议连接。该实用程序无法通过经典 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 数据类型表示的转换”。如果指定了 convertBsonTypes: true，则 convertBsonOid 选项也必须设置为 true，这是该选项在您指定 convertBsonTypes: true 时的默认设置。如果您导入使用 BSON 类型 JSON 扩展的文档，但未使用 convertBsonTypes: true，则文档将以与输入文件中的表示方式相同的方式导入，即作为嵌入的 JSON 文档。
convertBsonOid: true: 识别并转换 MongoDB 对象 ID，这是用作文档 _id 值的 12 字节 BSON 类型，在 MongoDB 扩展 JSON 严格模式下表示。此选项的默认值为 convertBsonTypes 选项的值，因此如果该选项设置为 true，则 MongoDB 对象 ID 也会自动转换。在从 MongoDB 导入数据时，如果未转换 BSON 类型，则 convertBsonOid 必须始终设置为 true，因为 MySQL 服务器要求将 _id 值转换为 varbinary(32) 类型。
extractOidTime: "field_name": 识别并提取包含在文档 _id 字段中 MongoDB 对象 ID 中的时间戳值，并将其放置到导入数据中的单独字段中。 extractOidTime 为包含时间戳的文档中的字段命名。时间戳是对象 ID 的前 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 对象 ID 会根据 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 文档”。

PREV HOME UP NEXT