Экспорт в хранилище

Статья
01/06/2025

Область применения: ✅Microsoft Fabric ✅Azure Data Explorer

Выполняет запрос и записывает первый результирующий набор во внешнее облачное хранилище, указанное строка подключения хранилища.

Разрешения

Для выполнения этой команды необходимо иметь по крайней мере разрешения средства просмотра баз данных.

Синтаксис

.export[] [asynccompressed] toOutputDataFormat( StorageConnectionString [, ...] ) [with(PropertyName=PropertyValue [, ...] ] )<|Запрос

Дополнительные сведения о соглашениях синтаксиса.

Параметры

Имя (название)	Type	Обязательно	Описание
`async`	`string`		Если задано, команда выполняется в асинхронном режиме. См . асинхронный режим.
`compressed`	`string`		Если задано, артефакты выходного хранилища сжимаются в виде `.gz` файлов. См. поддерживаемое `compressionType`свойство для сжатия файлов Parquet в виде оснастки.
OutputDataFormat	`string`	✔️	Указывает формат данных артефактов хранилища, написанных командой. Поддерживаются значения `csv`, `tsv`, `json` и `parquet`.
StorageConnectionString	`string`		Один или несколько строка подключения хранилища, указывающие, в какое хранилище записывать данные. Для масштабируемых операций записи может быть указано несколько строк подключения к хранилищу. Каждый такой строка подключения должен указывать учетные данные, используемые при записи в хранилище. Например, при записи в Хранилище BLOB-объектов Azure учетные данные могут быть ключом учетной записи хранения или общим ключом доступа (SAS) с разрешениями на чтение, запись и список БОЛЬШИХ двоичных объектов.
PropertyName, PropertyValue	`string`		Разделенный запятыми список пар свойств "ключ-значение". См . поддерживаемые свойства.

Примечание.

Мы настоятельно рекомендуем экспортировать данные в хранилище, которое находится в том же регионе, что и сама база данных. К ним относятся данные, экспортированные таким образом, чтобы его можно было передать в другую облачную службу в других регионах. Запись должна выполняться локально, а операции чтения могут выполняться удаленно.

Поддерживаемые свойства

Свойство	Type	Описание
`includeHeaders`	`string`	Для `csv`/`tsv` выходных данных управляет созданием заголовков столбцов. Может быть одним из `none` (по умолчанию; строки заголовков не создаются), `all` (выдает строку заголовка в каждый артефакт хранилища) или `firstFile` (выдает строку заголовка только в первый артефакт хранилища).
`fileExtension`	`string`	Указывает часть артефакта хранилища (например, `.csv` расширение).`.tsv` Если используется сжатие, `.gz` также добавляется.
`namePrefix`	`string`	Указывает префикс для добавления в каждое созданное имя артефакта хранилища. Случайный префикс используется, если не указано.
`encoding`	`string`	Указывает, как кодировать текст: `UTF8NoBOM` (по умолчанию) или `UTF8BOM`.
`compressionType`	`string`	Указывает тип используемого сжатия. Возможные значения: `gzip` или `snappy`. По умолчанию — `gzip`. `snappy` можно (необязательно) использовать для `parquet` форматирования.
`distribution`	`string`	Указание распространения (`single`, `per_node`, `per_shard`). Если значение равно `single`, один поток записывается в хранилище. В противном случае экспортирует записи со всех узлов, выполняющих запрос параллельно. См . оценку оператора подключаемого модуля. По умолчанию — `per_shard`.
`persistDetails`	`bool`	Указывает, что команда должна сохранять результаты (см `async` . флаг). По умолчанию в асинхронных запусках `true` , но его можно отключить, если вызывающий объект не требует результатов). `false` По умолчанию в синхронных выполнениях, но их также можно включить.
`sizeLimit`	`long`	Ограничение размера в байтах одного артефакта хранилища, записанного перед сжатием. Допустимый диапазон: 100 МБ (по умолчанию) до 4 ГБ.
`parquetRowGroupSize`	`int`	Относится только к формату данных Parquet. Управляет размером группы строк в экспортированных файлах. По умолчанию размер группы строк составляет 100 000 записей.
`distributed`	`bool`	Отключите или включите распределенный экспорт. Значение false эквивалентно указанию `single` распространения. Значение по умолчанию — "истина".
`parquetDatetimePrecision`	`string`	Указывает точность, используемую при экспорте `datetime` значений в Parquet. Возможные значения: миллисекунда и микросекунды. Значение по умолчанию — миллисекунда.

Проверка подлинности и авторизация

Метод проверки подлинности основан на предоставленном строка подключения, а необходимые разрешения зависят от метода проверки подлинности.

В следующей таблице перечислены поддерживаемые методы проверки подлинности и разрешения, необходимые для экспорта данных во внешнее хранилище по типу хранилища.

Authentication method	Хранилище BLOB-объектов Azure / Data Lake Storage 2-го поколения	Azure Data Lake Storage 1-го поколения
Олицетворение	Участник данных хранилища BLOB-объектов	Участник
Маркер общего доступа (SAS)	Write	Write
Маркер доступа Microsoft Entra	Дополнительные разрешения не требуются	Дополнительные разрешения не требуются
Ключ доступа к учетной записи хранения	Дополнительные разрешения не требуются	Дополнительные разрешения не требуются

Возвраты

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

Путь	NumRecords
http://storage1.blob.core.windows.net/containerName/export_1_d08afcae2f044c1092b279412dcb571b.csv	10
http://storage1.blob.core.windows.net/containerName/export_2_454c0f1359e24795b6529da8a0101330.csv	15

Асинхронный режим

async Если флаг указан, команда выполняется в асинхронном режиме. В этом режиме команда возвращается немедленно с идентификатором операции, а экспорт данных продолжается в фоновом режиме до завершения. Идентификатор операции, возвращаемый командой, можно использовать для отслеживания хода выполнения и в конечном счете его результатов с помощью следующих команд:

.show operations: отслеживание хода выполнения.
.show operation details: получение результатов завершения.

Например, после успешного завершения можно получить результаты с помощью:

.show operation f008dc1e-2710-47d8-8d34-0d562f5f8615 details

Примеры

В этом примере Kusto запускает запрос, а затем экспортирует первый набор записей, созданный запросом, в один или несколько сжатых BLOB-объектов CSV до 1 ГБ перед сжатием. Метки имени столбца добавляются в качестве первой строки для каждого большого двоичного объекта.

.export
  async compressed
  to csv (
    h@"https://storage1.blob.core.windows.net/containerName;secretKey",
    h@"https://storage1.blob.core.windows.net/containerName2;secretKey"
  ) with (
    sizeLimit=1000000000,
    namePrefix="export",
    includeHeaders="all",
    encoding="UTF8NoBOM"
  )
  <| 
  Logs | where id == "1234"

Сбои во время выполнения команд экспорта

Во время выполнения команды экспорта могут завершиться временным сбоем. непрерывного экспорта автоматически повторяет команду. Обычные команды экспорта (экспорт в хранилище, экспорт в внешнюю таблицу) не выполняют никаких повторных попыток.

При сбое команды экспорта артефакты, которые уже записаны в хранилище, не удаляются. Эти артефакты остаются в хранилище. Если команда завершается ошибкой, предположим, что экспорт неполный, даже если были написаны некоторые артефакты.
Лучший способ отслеживать выполнение команды и артефакты, экспортированные после успешного завершения, — использовать .show operations команды и .show operation details команды.

Сбои хранилища

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

Распределение по умолчанию для обычной .export команды — это per_shardвсе экстенты, содержащие данные для экспорта записи в хранилище одновременно.
Распределение по умолчанию для экспорта во внешние команды таблицы — per_nodeэто число узлов.

Если количество экстентов или узлов большое, это может привести к высокой нагрузке на хранилище, что приводит к регулированию хранилища или временным ошибкам хранилища. Следующие предложения могут преодолеть эти ошибки (по порядку приоритета):

Увеличьте количество учетных записей хранения, предоставленных команде экспорта или в определении внешней таблицы. Нагрузка равномерно распределяется между учетными записями.
Уменьшите параллелизм, задав указание per_node распространения (см. свойства команды).
Уменьшите параллелизм количества узлов, экспортируемых, задав свойству query_fanout_nodes_percent запроса клиента требуемое параллелизм (процент узлов). Свойство можно задать как часть запроса экспорта. Например, следующая команда ограничивает количество узлов, записываемых в хранилище одновременно, до 50 % узлов:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
Уменьшите параллелизм количества потоков, экспортируемых на каждом узле при использовании экспорта сегментов, задав свойствуquery_fanout_threads_percent запроса клиента требуемое параллелизм (процент потоков). Свойство можно задать как часть запроса экспорта. Например, следующая команда ограничивает количество потоков записи в хранилище одновременно до 50 % на каждом узле:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery
```
При экспорте в секционированную внешнюю таблицу параметры spread/concurrency могут снизить параллелизм (см. сведения о свойствах команды.
Если ни из предыдущих рекомендаций не работает, можно полностью отключить распределение, установив для свойства distributed значение false. Однако мы не рекомендуем делать это, так как это может значительно повлиять на производительность команды.

Сбои авторизации

Ошибки проверки подлинности или авторизации во время команд экспорта могут возникать, если учетные данные, предоставленные в строка подключения хранилища, не могут записываться в хранилище. Если вы используете impersonate или маркер SAS, делегированный пользователем для команды экспорта, роль участника данных BLOB-объектов хранилища требуется для записи в учетную запись хранения. Дополнительные сведения см. в строка подключения хранилища.

Сопоставление типов данных

Сопоставление типов данных Parquet

При экспорте типы данных Kusto сопоставляются с типами данных Parquet с помощью следующих правил:

Тип данных Kusto	Тип данных Parquet	Заметка Parquet	Комментарии
`bool`	`BOOLEAN`
`datetime`	`INT64`	TIMESTAMP_MICROS
`dynamic`	`BYTE_ARRAY`	UTF-8	Сериализован как строка JSON
`guid`	`BYTE_ARRAY`	UTF-8
`int`	`INT32`
`long`	`INT64`
`real`	`DOUBLE`
`string`	`BYTE_ARRAY`	UTF-8
`timespan`	`INT64`		Хранящиеся как галочки (100-наносекунд единиц)
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DECIMAL

Общие сведения о командах управления
непрерывный экспорт данных
приема в
.export to table
.export to SQL

Поделиться через

Экспорт в хранилище

Разрешения

Синтаксис

Параметры

Поддерживаемые свойства

Проверка подлинности и авторизация

Возвраты

Асинхронный режим

Примеры

Сбои во время выполнения команд экспорта

Сбои хранилища

Сбои авторизации

Сопоставление типов данных

Сопоставление типов данных Parquet

Обратная связь

Дополнительные ресурсы

Поделиться через

Экспорт в хранилище

Разрешения

Синтаксис

Параметры

Поддерживаемые свойства

Проверка подлинности и авторизация

Возвраты

Асинхронный режим

Примеры

Сбои во время выполнения команд экспорта

Сбои хранилища

Сбои авторизации

Сопоставление типов данных

Сопоставление типов данных Parquet

Связанное содержимое

Обратная связь

Дополнительные ресурсы