11.2.1 Running the Utility — MySQL Shell 8.4

11.2.1 Выполнение утилиты

Утилита импорта JSON требует существующего подключения X Protocol к серверу. Утилита не может работать через обычное подключение MySQL протокола.

В API MySQL Shell утилита импорта 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: Распознаёт и преобразует типы данных BSON, которые представлены с помощью расширений к формату JSON. По умолчанию этот параметр равен false. При указании convertBsonTypes: true каждый представленный тип BSON преобразуется в идентичный или совместимый с MySQL вид, и значение данных импортируется с использованием этого вида. Доступны дополнительные параметры для управления сопоставлением и преобразованием для конкретных типов данных BSON; список этих параметров управления и преобразования типов по умолчанию см. в Разделе 11.2.4, «Преобразования для представлений типов данных BSON». Параметр convertBsonOid также должен быть установлен в true, что является его значением по умолчанию, когда вы указываете convertBsonTypes: true. Если вы импортируете документы с расширениями JSON для типов BSON и не используете convertBsonTypes: true, документы импортируются так же, как они представлены во входном файле, как вложенные JSON-документы.
convertBsonOid: true: Распознаёт и преобразует идентификаторы MongoDB ObjectId, которые являются 12-байтовым типом BSON, используемым в качестве значения _id для документов, представленных в строгом режиме расширенного JSON MongoDB. По умолчанию для этого параметра используется значение параметра convertBsonTypes, поэтому если этот параметр установлен в true, ObjectId MongoDB также автоматически преобразуются. При импорте данных из MongoDB convertBsonOid всегда должен быть установлен в true, если вы не преобразуете типы BSON, так как MySQL Server требует, чтобы значение _id было преобразовано в тип varbinary(32).
extractOidTime: "field_name": Распознаёт и извлекает значение отметки времени, содержащееся в ObjectId MongoDB в поле _id для документа и помещает его в отдельное поле импортированных данных. extractOidTime назначает имя поля в документе, содержащее отметку времени. Отметка времени — это первые 4 байта ObjectId, которые остаются неизменными. convertBsonOid: true должен быть установлен, чтобы использовать этот параметр, что является значением по умолчанию, когда convertBsonTypes установлен в true.

В следующих примерах, первый в режиме JavaScript MySQL Shell, а второй в режиме Python MySQL Shell, импортируются 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"})

В следующем примере в режиме JavaScript MySQL Shell не указано никаких параметров, поэтому словарь опущен. mydb — это активная схема сеанса MySQL Shell. Следовательно, утилита импортирует JSON-документы из файла /tmp/stores.json в коллекцию с именем stores в базе данных mydb:

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

В следующем примере в режиме JavaScript MySQL Shell импортируются JSON-документы из файла /europe/regions.json в столбец jsondata в реляционной таблице с именем regions в базе данных mydb. Типы данных BSON, представленные в документах расширениями JSON, преобразуются в представление MySQL:

mysql-js> util.importJson("/europe/regions.json", {schema: "mydb", table: "regions", tableColumn: "jsondata", convertBsonTypes: true});

Следующий пример в режиме JavaScript MySQL Shell выполняет тот же импорт, но без преобразования представлений JSON типов данных BSON в представления MySQL. Однако ObjectId MongoDB в документах преобразуются в соответствии с требованиями MySQL, а их отметки времени также извлекаются:

mysql-js> util.importJson("/europe/regions.json", {schema: "mydb", table: "regions", tableColumn: "jsondata", convertBsonOid: true, extractOidTime: "idTime"});

По завершении импорта или при его остановке пользователем с помощью Ctrl+C или по ошибке пользователю возвращается сообщение с количеством успешно импортированных JSON-документов и соответствующим сообщением об ошибке. Сама функция возвращает пустое значение или исключение в случае ошибки.

Утилиту импорта JSON также можно вызвать из командной строки. Доступны два альтернативных формата вызова командной строки. Вы можете использовать интерфейс команд mysqlsh, который принимает входные данные только из файла (или специального файла FIFO), или команду --import, которая принимает входные данные со стандартного ввода или из файла. Инструкции см. в Разделе 11.2.2, «Импортирование JSON-документов с помощью интерфейса команд Mysqlsh» или Разделе 11.2.3, «Импортирование JSON-документов с помощью команды --import».