Exportar dados para o armazenamento em nuvem

Artigo
01/18/2024

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

Permissões

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

Syntax

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

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`async`	`string`		Se especificado, o comando será executado no modo assíncrono. Consulte modo assíncrono.
`compressed`	`string`		Se especificado, os artefatos de armazenamento de saída são compactados como `.gz` arquivos. Consulte a `compressionType`propriedade com suporte para compactar arquivos Parquet como snappy.
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 em Armazenamento de Blobs do Azure, as credenciais podem ser a chave da conta de armazenamento ou uma SAS (chave de acesso compartilhado) 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 propriedades com suporte.

Observação

É altamente recomendável exportar dados para o armazenamento que estão co-localizados na mesma região que o próprio cluster. Isso inclui dados 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 ocorrer remotamente.

Propriedades com suporte

Propriedade	Tipo	Descrição
`includeHeaders`	`string`	Para `csv`/`tsv` saída, controla a geração de cabeçalhos de coluna. Pode ser um ( `none` padrão; sem linhas de cabeçalho emitidas), `all` (emitir uma linha de cabeçalho em cada artefato de armazenamento) ou `firstFile` (emitir uma linha de cabeçalho somente no primeiro artefato de armazenamento).
`fileExtension`	`string`	Indica a parte "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 será 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 igual `single`a , um único thread será gravado no armazenamento. Caso contrário, exporte gravações de todos os nós executando a consulta em paralelo. Consulte avaliar operador de plug-in. Assume o padrão de `per_shard`.
`persistDetails`	`bool`	Indica que o comando deve persistir 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). `false` O padrão é em execuções síncronas, mas também pode ser ativado nelas.
`sizeLimit`	`long`	O limite de tamanho em bytes de um único artefato de armazenamento que está sendo gravado (antes da compactação). Intervalo válido: 100 MB (padrão) a 4 GB.
`parquetRowGroupSize`	`int`	Relevante somente quando o formato de dados é Parquet. Controla o tamanho do grupo de linhas nos arquivos exportados. O tamanho padrão do grupo de linhas é de 100.000 registros.
`distributed`	`bool`	Desabilitar/habilitar a exportação distribuída. A configuração como false é equivalente à `single` dica de distribuição. O padrão é true.
`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 no cadeia de conexão fornecido 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 o 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 SAS (Acesso Compartilhado)	Gravar	Gravar
token de acesso Microsoft Entra	Nenhuma permissão extra necessária	Nenhuma permissão extra necessária
Chave de acesso da conta de armazenamento	Nenhuma permissão extra necessária	Nenhuma permissão extra necessária

Retornos

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. A ID da operação retornada pelo comando pode ser usada para acompanhar seu progresso e, por fim, seus resultados por meio dos seguintes comandos:

.show operations: acompanhe o progresso.
.show operation details: obter 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 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 para 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 transitóriamente 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 repetição.

Quando o comando de exportação falha, os artefatos que já foram gravados no armazenamento não são excluídos. Esses artefatos permanecem no armazenamento. Se o comando falhar, suponha que a exportação esteja incompleta, mesmo que alguns artefatos tenham sido gravados.
A melhor maneira de acompanhar 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 modo que possa haver muitas gravações simultâneas no armazenamento. O nível de distribuição depende do tipo de comando de exportação:

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 no armazenamento simultaneamente.
A distribuição padrão para exportação para comandos de 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 alta carga no armazenamento que resulta em limitação de armazenamento ou erros transitórios de armazenamento. As sugestões a seguir podem superar esses erros (por ordem de prioridade):

Aumente o número de contas de armazenamento fornecidas para o comando de exportação ou para a 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 de comando).
Reduza a simultaneidade do número de nós exportando definindo a propriedade query_fanout_nodes_percentde solicitação do cliente para a simultaneidade desejada (percentual 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 que gravam no armazenamento simultaneamente para 50% dos nós de 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 fragmento, definindo a propriedade de solicitaçãoquery_fanout_threads_percent do cliente como a simultaneidade 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 que gravam no armazenamento simultaneamente para 50% em cada um dos nós de 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 estiver exportando para uma tabela externa particionada, definir as propriedades poderá reduzir a spread/concurrency simultaneidade (consulte detalhes nas propriedades de comando.
Se nenhum dos trabalhos acima funcionar, você poderá desabilitar completamente a distribuição definindo a distributed propriedade como false. No entanto, não recomendamos fazer isso, pois isso pode afetar significativamente o desempenho do comando.

Falhas de autorização

Falhas de autenticação ou autorização durante comandos de exportação podem ocorrer quando as credenciais fornecidas no armazenamento cadeia de conexão 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 de exportação, 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 do Kusto são mapeados para tipos de dados Parquet usando as seguintes regras:

Tipo de dados Kusto	Tipo de Dados Parquet	Anotação 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`		Contagem armazenada como tiques (unidades de 100 nanossegundos)
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DECIMAL

Compartilhar via