.export para armazenamento

Alterne os serviços usando a lista suspensa De versão . Saiba mais sobre navegação.
Aplica-se a: ✅ Microsoft Fabric ✅ Azure Data Explorer

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 do Visualizador de Banco de Dados para executar esse comando.

Sintaxe

.export[async] [compressed] toOutputDataFormat ( StorageConnectionString [, ...] ) [ PropertyNamewith [( ...] ] =Consulta

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Tipo	Obrigatória	Descrição
assíncrono	string		Se especificado, o comando é executado no modo assíncrono. Consulte modo assíncrono.
compactado	bool		Se especificado, os artefatos de armazenamento de saída são compactados no formato especificado pelo compressionTypepropriedade com suporte.
OutputDataFormat	string	✔️	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 especificam 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 especificar 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 SAS (chave de acesso compartilhado) com as permissões para ler, gravar e listar blobs. Quando você exporta dados para arquivos CSV usando um ponto de extremidade DFS, os dados passam por um ponto de extremidade privado gerenciado pelo DFS. Quando você exporta dados para arquivos parquet, os dados passam por um ponto de extremidade privado gerenciado por blob.
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 são colocados na mesma região que o próprio banco de dados. 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 acontecer remotamente.

Propriedades aceitas

Propriedade	Tipo	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), none (emitir uma linha de cabeçalho em cada artefato de armazenamento) ou all (emitir uma linha de firstFile cabeçalho apenas no primeiro artefato de armazenamento).
fileExtension	string	A parte "extensão" do artefato de armazenamento (por exemplo, .csv ou .tsv). Se a compactação for usada, .gz também será anexada.
namePrefix	string	O prefixo a ser adicionado a cada nome de artefato de armazenamento gerado. Um prefixo aleatório é usado se não for especificado.
encoding	string	A codificação de texto. Os valores possíveis incluem: UTF8NoBOM (padrão) ou UTF8BOM.
compressionType	string	O tipo de compactação a ser usado. Para arquivos não Parquet, somente gzip é permitido. Para arquivos Parquet, os valores possíveis incluem gzip, snappy, lz4_raw, brotlie zstd. O padrão é gzip.
distribution	string	Dica de distribuição (single, per_node, per_shard). Se o valor for singleigual a , um único thread gravará no armazenamento. Caso contrário, exporte gravações de todos os nós que executam a consulta em paralelo. Consulte avaliar o operador do plug-in. Assume o padrão de per_shard.
persistDetails	bool	Se true, o comando 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. O padrão é false em execuções síncronas, mas pode ser ativado.
sizeLimit	long	O limite de tamanho em bytes de um único artefato de armazenamento 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	Desabilite ou habilite a exportação distribuída. Definir como false é equivalente a dica de single distribuição. O padrão é verdadeiro.
parquetDatetimePrecision	string	A precisão a ser usada ao exportar valores datetime 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 do Storage Blob	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. 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 comandos de exportação

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

• Quando o comando de exportação falha, os artefatos já 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 rastrear 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 gravam no 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.

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 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 o definição de tabela externa. A carga é 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 propriedadesolicitação do cliente como a simultaneidade 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 que gravam no armazenamento simultaneamente a 50% dos nós:

  .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 propriedadecliente 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 gravando no armazenamento simultaneamente a 50% em cada um dos nós:

  .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, a configuração das propriedades poderá reduzir a spread/concurrency simultaneidade (consulte os detalhes nas propriedades do comando.

• Se nenhuma das recomendações anteriores funcionar, você poderá desabilitar completamente a distribuição definindo a propriedade distributed 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 na cadeia de conexão de armazenamento não têm permissão para gravar no armazenamento. Se você estiver usando impersonate um token SAS delegado pelo usuário para o comando de exportação, a função Colaborador de Dados do Blob de Armazenamento será necessária para gravar na conta de armazenamento. Para saber mais, confira a página Cadeias de conexão.

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 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		Armazenado como contagem de tiques (unidades de 100 nanossegundos)
decimal	FIXED_LENGTH_BYTE_ARRAY	DECIMAL

Conteúdo relacionado

• Visão geral dos comandos de Gerenciamento de
• de exportação de dados .continuous
• .ingestão em
• .export para a tabela
• .export para o SQL