Exportar dados para armazenamento em nuvem

Artigo
07/04/2024

Executa uma consulta e grava o primeiro conjunto de resultados em um armazenamento em nuvem externo, especificado por uma cadeia de conexão de armazenamento.

Permissões

Você deve ter pelo menos permissões de Visualizador de Banco de Dados para executar esse comando.

Sintaxe

.export[async] [compressed] to OutputDataFormat ( StorageConnectionString [, ...] ) [ PropertyName = PropertyValue [, ...] ] <| )with ( Consulta

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Digitar	Obrigatória	Descrição
`async`	`string`		Se especificado, o comando é executado no modo assíncrono. Consulte o modo assíncrono.
`compressed`	`string`		Se especificado, os artefatos de armazenamento de saída são compactados como `.gz` arquivos. Consulte a propriedade suportada `compressionType` para compactar arquivos Parquet como rápido.
OutputDataFormat	`string`	✔️	Indica o formato de dados dos artefatos de armazenamento gravados pelo comando. Os valores compatíveis são: `csv`, `tsv`, `json` e `parquet`.
StorageConnectionString	`string`		Uma ou mais cadeias de conexão de armazenamento que indicam em qual armazenamento gravar os dados. Mais de uma cadeia de conexão de armazenamento pode ser especificada para gravações escalonáveis. Cada cadeia de conexão deve indicar as credenciais a serem usadas ao gravar no armazenamento. Por exemplo, ao gravar no Armazenamento de Blobs do Azure, as credenciais podem ser a chave da conta de armazenamento ou uma chave de acesso compartilhado (SAS) com as permissões para ler, gravar e listar blobs.
PropertyName, PropertyValue	`string`		Uma lista separada por vírgulas de pares de propriedades chave-valor. Consulte as propriedades suportadas.

Observação

É altamente recomendável exportar dados para o armazenamento que está localizado na mesma região que o próprio cluster. Isso inclui dados que são exportados para que possam ser transferidos para outro serviço de nuvem em outras regiões. As gravações devem ser feitas localmente, enquanto as leituras podem acontecer remotamente.

Propriedades com suporte

Propriedade	Type	Descrição
`includeHeaders`	`string`	Para `csv`/`tsv` saída, controla a geração de cabeçalhos de coluna. Pode ser um dos (padrão; nenhuma linha de cabeçalho emitida), `all` (emitir uma linha de cabeçalho em cada artefato de armazenamento) ou `firstFile` (emitir uma linha de `none` cabeçalho apenas no primeiro artefato de armazenamento).
`fileExtension`	`string`	Indica a parte de "extensão" do artefato de armazenamento (por exemplo, `.csv` ou `.tsv`). Se a compactação for usada, `.gz` também será acrescentada.
`namePrefix`	`string`	Indica um prefixo a ser adicionado a cada nome de artefato de armazenamento gerado. Um prefixo aleatório é usado se não for especificado.
`encoding`	`string`	Indica como codificar o texto: `UTF8NoBOM` (padrão) ou `UTF8BOM`.
`compressionType`	`string`	Indica o tipo de compactação a ser usado. Os possíveis valores são `gzip` ou `snappy`. O padrão é `gzip`. `snappy` pode (opcionalmente) ser usado para `parquet` formato.
`distribution`	`string`	Dica de distribuição (`single`, `per_node`, `per_shard`). Se o valor for `single`igual a , um único thread grava no armazenamento. Caso contrário, exporte gravações de todos os nós que executam a consulta em paralelo. Consulte avaliar operador de plugin. Assume o padrão de `per_shard`.
`persistDetails`	`bool`	Indica que o comando deve manter seus resultados (consulte `async` sinalizador). O padrão é `true` em execuções assíncronas, mas pode ser desativado se o chamador não exigir os resultados). O padrão é `false` em execuções síncronas, mas também pode ser ativado nessas execuções.
`sizeLimit`	`long`	O limite de tamanho em bytes de um único artefato de armazenamento sendo gravado (antes da compactação). Intervalo válido: 100 MB (padrão) a 4 GB.
`parquetRowGroupSize`	`int`	Relevante apenas quando o formato de dados é Parquet. Controla o tamanho do grupo de linhas nos arquivos exportados. O tamanho padrão do grupo de linhas é 100.000 registros.
`distributed`	`bool`	Desativar/habilitar exportação distribuída. Definir como false é equivalente a dica de `single` distribuição. O padrão é verdadeiro.
`parquetDatetimePrecision`	`string`	Especifica a precisão a ser usada ao exportar `datetime` valores para Parquet. Os valores possíveis são milissegundo e microssegundo. O padrão é milissegundo.

Autenticação e autorização

O método de autenticação é baseado na cadeia de conexão fornecida e as permissões necessárias variam dependendo do método de autenticação.

A tabela a seguir lista os métodos de autenticação com suporte e as permissões necessárias para exportar dados para armazenamento externo por tipo de armazenamento.

Método de autenticação	Armazenamento de Blobs do Azure / Data Lake Storage Gen2	Data Lake Storage Gen1
Representação	Colaborador de dados de blob de armazenamento	Colaborador
Token de Acesso Compartilhado (SAS)	Gravar	Gravar
Token de acesso do Microsoft Entra	Não são necessárias permissões extras	Não são necessárias permissões extras
Chave de acesso da conta de armazenamento	Não são necessárias permissões extras	Não são necessárias permissões extras

Devoluções

Os comandos retornam uma tabela que descreve os artefatos de armazenamento gerados. Cada registro descreve um único artefato e inclui o caminho de armazenamento para o artefato e quantos registros ele contém.

Caminho	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

Modo assíncrono

Se o async sinalizador for especificado, o comando será executado no modo assíncrono. Nesse modo, o comando retorna imediatamente com uma ID de operação e a exportação de dados continua em segundo plano até a conclusão. O ID da operação retornado pelo comando pode ser usado para acompanhar seu progresso e, finalmente, seus resultados por meio dos seguintes comandos:

.show operations: Acompanhe o progresso.
.show operation details: Obtenha resultados de conclusão.

Por exemplo, após uma conclusão bem-sucedida, você pode recuperar os resultados usando:

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

Exemplos

Neste exemplo, o Kusto executa a consulta e, em seguida, exporta o primeiro conjunto de registros produzido pela consulta para um ou mais blobs CSV compactados, até 1 GB antes da compactação. Os rótulos de nome de coluna são adicionados como a primeira linha de cada blob.

.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"

Falhas durante os comandos de exportação

Os comandos de exportação podem falhar transitoriamente durante a execução. A exportação contínua repetirá automaticamente o comando. Os comandos de exportação regulares (exportar para armazenamento, exportar para tabela externa) não executam nenhuma tentativa.

Quando o comando export falha, os artefatos que já foram gravados no armazenamento não são excluídos. Esses artefatos permanecem armazenados. Se o comando falhar, suponha que a exportação esteja incompleta, mesmo que alguns artefatos tenham sido gravados.
A melhor maneira de controlar a conclusão do comando e os artefatos exportados após a conclusão bem-sucedida é usando os .show operations comandos e .show operation details .

Falhas de armazenamento

Por padrão, os comandos de exportação são distribuídos de forma que possa haver muitas gravações simultâneas no armazenamento. O nível de distribuição depende do tipo de comando export:

A distribuição padrão para o comando regular .export é per_shard, o que significa todas as extensões que contêm dados para exportar gravação para armazenamento simultaneamente.
A distribuição padrão para comandos de exportação para tabela externa é per_node, o que significa que a simultaneidade é o número de nós no cluster.

Quando o número de extensões/nós é grande, isso pode levar a uma alta carga no armazenamento que resulta em limitação de armazenamento ou erros transitórios de armazenamento. As seguintes sugestões podem superar esses erros (por ordem de prioridade):

Aumente o número de contas de armazenamento fornecidas ao comando export ou à definição de tabela externa (a carga será distribuída uniformemente entre as contas).
Reduza a simultaneidade definindo a dica de distribuição como per_node (consulte propriedades do comando).
Reduza a simultaneidade do número de nós exportados definindo a propriedade de solicitação do cliente para a simultaneidade query_fanout_nodes_percent desejada (porcentagem de nós). A propriedade pode ser definida como parte da consulta de exportação. Por exemplo, o comando a seguir limita o número de nós gravando no armazenamento simultaneamente a 50% dos nós do cluster:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
Reduza a simultaneidade do número de threads exportados em cada nó ao usar a exportação por estilhaço, definindo a propriedade de solicitação do cliente para a simultaneidade query_fanout_threads_percent desejada (porcentagem de threads). A propriedade pode ser definida como parte da consulta de exportação. Por exemplo, o comando a seguir limita o número de threads gravando no armazenamento simultaneamente a 50% em cada um dos nós do cluster:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery
```
Se exportar para uma tabela externa particionada, definir as propriedades pode reduzir a spread/concurrency simultaneidade (consulte os detalhes nas propriedades do comando.
Se nenhum dos itens acima funcionar, você poderá desabilitar completamente a distribuição definindo a distributed propriedade como false. No entanto, não recomendamos fazê-lo, pois pode afetar significativamente o desempenho do comando.

Falhas de autorização

Falhas de autenticação ou autorização durante os comandos de exportação podem ocorrer quando as credenciais fornecidas na cadeia de conexão de armazenamento não têm permissão para gravar no armazenamento. Se você estiver usando impersonate ou um token SAS delegado pelo usuário para o comando exportar, a função Colaborador de Dados de Blob de Armazenamento será necessária para gravar na conta de armazenamento. Para obter mais informações, consulte Cadeias de conexão de armazenamento.

Mapeamento de tipos de dados

Mapeamento de tipos de dados Parquet

Na exportação, os tipos de dados Kusto são mapeados para tipos de dados Parquet usando as seguintes regras:

Tipo de dados do Kusto	Tipo de Dados Parquet	Anotação de Parquet	Comentários
`bool`	`BOOLEAN`
`datetime`	`INT64`	TIMESTAMP_MICROS
`dynamic`	`BYTE_ARRAY`	UTF-8	Serializado como cadeia de caracteres JSON
`guid`	`BYTE_ARRAY`	UTF-8
`int`	`INT32`
`long`	`INT64`
`real`	`DOUBLE`
`string`	`BYTE_ARRAY`	UTF-8
`timespan`	`INT64`		Armazenados como contagem de carrapatos (unidades de 100 nanossegundos)
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DECIMAL

Compartilhar via