12.2.1 Running the Utility — MySQL Shell 9.2

12.2.1 Запуск утилиты

Утилита импорта JSON требует существующего подключения X Protocol к серверу. Утилита не может работать через подключение с протоколом classic 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; список этих контрольных опций и преобразований типов по умолчанию см. в разделе 12.2.4 «Преобразования для представлений типов данных BSON». Опция convertBsonOid также должна быть установлена в значение true, которое является значением по умолчанию для этой опции при указании convertBsonTypes: true. Если вы импортируете документы с расширениями JSON для типов BSON и не используете convertBsonTypes: true, документы импортируются так же, как они представлены в файле входных данных, как вложенные JSON-документы.
convertBsonOid: true: Распознаёт и преобразует ObjectId MongoDB, который представляет собой 12-байтовый тип BSON, используемый в качестве значения _id для документов, представленных в строгом режиме расширенного JSON MongoDB. По умолчанию для этой опции установлено значение опции convertBsonTypes, поэтому, если эта опция установлена в значение true, MongoDB ObjectID также автоматически преобразуются. При импорте данных из 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. Однако MongoDB ObjectID в документах преобразуются в соответствии с требованиями 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, которая принимает входные данные со стандартного ввода или из файла. Инструкции см. в разделе 12.2.2 «Импорт JSON-документов с интерфейсом команд mysqlsh» или разделе 12.2.3 «Импорт JSON-документов с командой --import».