11.4.3 Result Data Specification — MySQL Shell 9.2

11.4.3 Спецификация данных результата

Определение данных результата состоит из следующих элементов:

Метаданные столбцов: имена столбцов и их типы. Это можно определить автоматически или вручную.
Данные: записи результата.

Автоматически определенные данные столбцов

Первый словарь, определённый в data, используется для автоматического определения метаданных столбцов. Этот словарь включает следующее:

имя: определяется каждым ключом в словаре.
тип: значение каждого ключа.

Примечание

Автоматическое определение метаданных результата имеет следующие ограничения:

Вы не можете определить типы данных, используемые для каждого столбца.
Вы не можете определить порядок столбцов в результате.
Имя и тип — это единственные доступные метаданные столбцов.

Тип столбца и представление значений в результатах отображаются с помощью поддержки языка:

Таблица 11.2 Сопоставление типов значений столбцов и результата JavaScript

Таблица 11.2 Сопоставление типов значений столбцов и результата JavaScript
Значение JavaScript	Тип столбца по умолчанию	Тип значения результата
`null`	`STRING`	`null`
`string`	`STRING`	`string`
`integer`	`BIGINT`	`integer`
`float`	`DOUBLE`	`float`
`boolean`	`TINYINT`	0 или 1
`array`	`JSON`	`string`
`dictionary`	`JSON`	`string`
`array buffer`	`BYTES`	`array buffer`
`date`	DATETIME	`date`

Таблица 11.3 Сопоставление типов значений столбцов и результата Python

Таблица 11.3 Сопоставление типов значений столбцов и результата Python
Значение Python	Тип столбца по умолчанию	Тип значения результата
`None`	`STRING`	`null`
`string`	`STRING`	`string`
`integer`	`BIGINT`	`integer`
`float`	`DOUBLE`	`float`
`boolean`	`TINYINT`	0 или 1
`array`	`JSON`	`string`
`dictionary`	`JSON`	`string`
`binary string`	`BYTES`	`binary string`
`date`	DATE	`date`
`time`	TIME	`time`
`datetime`	DATETIME	`datetime`

Следующий пример демонстрирует автоматическое определение столбцов:

@sql_handler(prefixes=["SHOW FILES"])
def show_files(session, sql):
files = [{'path': file, 'length': os.stat(file).st_size} for file in os.listdir()]
return mysqlsh.globals.shell.create_result({'data': files})

Использование:

SQL> show files;
+---------+----------------+
| length  | path           |
+---------+----------------+
| 420     | sample_file.tx |
| 50      | readme.txt     |
+---------+----------------+
3 rows in set (0.0000 sec)

Вручную определенные данные столбцов

Вы можете определить метаданные с помощью атрибута columns. Этот атрибут определяет порядок столбцов и может использоваться для переопределения типов столбцов по умолчанию.

columns определяется как список, содержащий либо строку, определяющую имя столбца, либо словарь, содержащий одно или несколько из следующих:

name: (обязательно) имя столбца в результате.
type: (необязательно) ожидаемый тип значений столбца. Разрешенные значения — string, integer, float, json, date, time, datetime и bytes.
flags: (необязательно) список дополнительных флагов, разделенных запятыми (строка). blob, timestamp, unsigned, zerofill, binary, enum и set.
length: (необязательно) длина в байтах.

Следующий пример демонстрирует ручное определение столбца:

@sql_handler(prefixes=["SHOW FILES"])
def show_files(session, sql):
files = [{'path': file, 'length': os.stat(file).st_size} for file in os.listdir()]
metadata = [{'name': 'path', 'type': 'string'}, {'name': 'length', 'type': 'integer'}]
return mysqlsh.globals.shell.create_result({'columns', metadata, 'data': files})

Использование:

mysql-sql> show files;
+----------------+---------+
| path           | length  |
+----------------+---------+
| sample_file.tx | 420     |
| readme.txt     | 50      |
+----------------+---------+
3 rows in set (0.0000 sec)