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
_id
varbinary(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
集合:
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 节,“使用--import
命令导入 JSON 文档”。