Exportar dados para uma tabela externa

Você pode exportar dados definindo uma tabela externa e exportando dados para ela. As propriedades da tabela são especificadas ao criar a tabela externa. O comando export faz referência à tabela externa por nome.

Permissões

Você deve ter pelo menos permissões de Administração de Tabela para executar esse comando.

Syntax

.export [async] totableexternalTableName
[with(propertyName=propertyValue [, ...])] <|Consulta

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
externalTableName	string	✔️	O nome da tabela externa para a qual exportar.
propertyName, propertyValue	string		Uma lista separada por vírgulas de propriedades opcionais.
consulta	string	✔️	A consulta de exportação.

Propriedades com suporte

As propriedades a seguir têm suporte como parte do comando exportar para a tabela externa.

Propriedade	Tipo	Descrição	Padrão
sizeLimit	long	O limite de tamanho em bytes de um único artefato de armazenamento que está sendo gravado (antes da compactação). Um grupo de linhas completo de tamanho parquetRowGroupSize será gravado antes de verificar se esse grupo de linhas atingiu o limite de tamanho e deve iniciar um novo artefato. Intervalo válido: 100 MB (padrão) a 1 GB.
distributed	bool	Desabilitar/habilitar a exportação distribuída. A configuração como false é equivalente à single dica de distribuição.	O padrão é true.
distribution	string	Dica de distribuição (single, per_node, per_shard). Veja mais detalhes em Configurações de distribuição	O padrão é per_node.
distributionKind	string	Opcionalmente, alterna para distribuição uniforme quando a tabela externa é particionada por partição de cadeia de caracteres. Os valores válidos são uniform ou default. Veja mais detalhes em Configurações de distribuição
concurrency	Número	Sugere ao sistema quantas partições executar em paralelo. Veja mais detalhes em Configurações de distribuição	O valor padrão é 16.
spread	Número	Sugere ao sistema como distribuir as partições entre nós de cluster. Veja mais detalhes em Configurações de distribuição	O valor padrão é Min(64, number-of-nodes).
parquetRowGroupSize	int	Relevante somente quando o formato de dados é Parquet. Controla o tamanho do grupo de linhas nos arquivos exportados. Esse valor tem precedência sobre sizeLimit, o que significa que um grupo de linhas completo será exportado antes de verificar se esse grupo de linhas atingiu o limite de tamanho e deve iniciar um novo artefato.	O tamanho padrão do grupo de linhas é de 100.000 registros.

Configurações de distribuição

A distribuição de uma operação de exportação para tabela externa indica o número de nós e threads que estão sendo gravados no armazenamento simultaneamente. A distribuição padrão depende do particionamento de tabela externa:

Particionamento de tabela externa	Distribuição padrão
A tabela externa não é particionada ou particionada apenas por datetime coluna	A exportação é distribuída per_node – todos os nós no cluster estão exportando simultaneamente. Cada nó grava os dados atribuídos a esse nó. O número de arquivos exportados por um nó será maior que um, somente se o tamanho dos dados desse nó exceder sizeLimit.
A tabela externa é particionada por uma coluna de cadeia de caracteres	Os dados a serem exportados são movidos entre os nós, de modo que cada nó grave um subconjunto dos valores de partição. Uma única partição é sempre escrita por um único nó. O número de arquivos gravados por partição deve ser maior que um somente se os dados excederem sizeLimit. Se a tabela externa incluir várias partições de cadeia de caracteres, os dados serão particionados entre o nó com base na primeira partição. Portanto, é recomendável definir a partição com a distribuição mais uniforme como a primeira.

Alterar as configurações de distribuição padrão

Alterar as configurações de distribuição padrão pode ser útil nos seguintes casos:

Caso de uso	Descrição	Recomendação
Reduzir o número de arquivos exportados	A exportação está criando muitos arquivos pequenos e você gostaria que ele criasse um número menor de arquivos maiores.	Definir distribution=single ou distributed=false (ambos são equivalentes) nas propriedades de comando. Apenas um único thread executa a exportação. A desvantagem disso é que a operação de exportação pode ser mais lenta, pois a simultaneidade é muito reduzida.
Reduzir a duração da exportação	Aumentando a simultaneidade da operação de exportação, para reduzir sua duração.	Defina distribution=per_shard nas propriedades de comando. Isso significa que a simultaneidade das operações de gravação é por fragmento de dados, em vez de por nó. Isso só é relevante ao exportar para uma tabela externa que não é particionada por partição de cadeia de caracteres. Isso pode criar muita carga no armazenamento, potencialmente resultando em limitação. Confira Falhas de armazenamento.
Reduzir a duração da exportação para tabelas externas particionadas por uma partição de cadeia de caracteres	Se as partições não forem distribuídas uniformemente entre os nós, a exportação poderá levar mais tempo para ser executada. Por exemplo, se houver uma única partição muito maior do que outras, a maior parte do trabalho de exportação será feita pelo único nó atribuído a essa partição, enquanto outros nós ficarão ociosos. Confira Configurações de distribuição.	Há várias configurações que você pode alterar: * Se houver mais de uma partição de cadeia de caracteres, defina a com a melhor distribuição primeiro. * Defina distributionKind=uniform nas propriedades de comando. Essa configuração desabilita as configurações de distribuição padrão para tabelas externas particionadas por cadeia de caracteres. A exportação será executada com per-node distribuição e cada nó exportará os dados atribuídos ao nó. Uma única partição pode ser gravada por vários nós e o número de arquivos aumenta adequadamente. Para aumentar ainda mais a simultaneidade, defina distributionKind=uniform junto com distribution=per_shard para maior simultaneidade (ao custo de potencialmente muitos mais arquivos gravados) * Se a causa da exportação lenta não for exceções nos dados, reduza a duração aumentando a simultaneidade, sem alterar as configurações de particionamento. Use as hint.spread propriedades e hint.concurrency , que determinam a simultaneidade do particionamento. Consulte operador de partição. Por padrão, o número de nós exportando simultaneamente (o spread) será o valor mínimo entre 64 e o número de nós de cluster. A configuração spread para um número maior do que o número de nós aumenta a simultaneidade em cada nó (o valor máximo para spread é 64).

Autenticação e autorização

Para exportar para uma tabela externa, você deve configurar permissões de gravação. Para obter mais informações, consulte As permissões de gravação para a tabela externa do Armazenamento do Azure ou SQL Server tabela externa.

Saída

Parâmetro de saída	Tipo	Descrição
ExternalTableName	string	O nome da tabela externa.
Caminho	string	Caminho de saída.
NumRecords	string	Número de registros exportados para o caminho.

Observações

• O esquema de saída da consulta de exportação deve corresponder ao esquema da tabela externa, incluindo todas as colunas definidas pelas partições. Por exemplo, se a tabela for particionada por DateTime, o esquema de saída da consulta deverá ter uma coluna Timestamp correspondente ao TimestampColumnName. Esse nome de coluna é definido na definição de particionamento de tabela externa.

• Não é possível substituir as propriedades da tabela externa usando o comando export. Por exemplo, você não pode exportar dados no formato Parquet para uma tabela externa cujo formato de dados é CSV.

• Se a tabela externa for particionada, os artefatos exportados serão gravados em seus respectivos diretórios de acordo com as definições de partição, como visto no exemplo de tabela externa particionada.

  • Se um valor de partição for nulo/vazio ou for um valor de diretório inválido, de acordo com as definições do armazenamento de destino, o valor da partição será substituído por um valor padrão de __DEFAULT_PARTITION__.

• Para obter sugestões para superar erros de armazenamento durante os comandos de exportação, consulte falhas durante os comandos de exportação.

• As colunas de tabela externa são mapeadas para tipos de dados de formato de destino adequados, de acordo com regras de mapeamento de tipos de dados .

• A exportação nativa parquet é um mecanismo de exportação de luz de recurso mais eficaz. No momento, uma coluna "datetime" exportada não tem suporte do SQL do Synapse 'COPY'.

Número de arquivos

O número de arquivos gravados por partição depende das configurações de distribuição da operação de exportação:

• Se a tabela externa incluir somente partições datetime ou nenhuma partição, o número de arquivos gravados (para cada partição, se existir) deverá ser semelhante ao número de nós no cluster (ou mais, se sizeLimit for atingido). Quando a operação de exportação é distribuída, todos os nós no cluster são exportados simultaneamente. Para desabilitar a distribuição, para que apenas um único nó faça as gravações, defina distributed como false. Esse processo cria menos arquivos, mas reduzirá o desempenho de exportação.

• Se a tabela externa incluir uma partição por uma coluna de cadeia de caracteres, o número de arquivos exportados deverá ser um único arquivo por partição (ou mais, se sizeLimit for atingido). Todos os nós ainda participam da exportação (a operação é distribuída), mas cada partição é atribuída a um nó específico. Definir distributed como false fará com que apenas um único nó faça a exportação, mas o comportamento permanecerá o mesmo (um único arquivo gravado por partição).

Exemplos

Exemplo de tabela externa não particionada

ExternalBlob é uma tabela externa não particionada.

.export to table ExternalBlob <| T

ExternalTableName	Caminho	NumRecords
ExternalBlob	http://storage1.blob.core.windows.net/externaltable1cont1/1_58017c550b384c0db0fea61a8661333e.csv	10

Exemplo de tabela externa particionada

PartitionedExternalBlob é uma tabela externa, definida da seguinte maneira:

.create external table PartitionedExternalBlob (Timestamp:datetime, CustomerName:string) 
kind=blob
partition by (CustomerName:string=CustomerName, Date:datetime=startofday(Timestamp))   
pathformat = ("CustomerName=" CustomerName "/" datetime_pattern("yyyy/MM/dd", Date))   
dataformat=csv
( 
   h@'http://storageaccount.blob.core.windows.net/container1;secretKey'
)

.export to table PartitionedExternalBlob <| T

ExternalTableName	Caminho	NumRecords
ExternalBlob	http://storageaccount.blob.core.windows.net/container1/CustomerName=customer1/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_1_58017c550b384c0db0fea61a8661333e.csv	10
ExternalBlob	http://storageaccount.blob.core.windows.net/container1/CustomerName=customer2/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_2_b785beec2c004d93b7cd531208424dc9.csv	10

Se o comando for executado de forma assíncrona (usando o async palavra-chave), a saída estará disponível usando o comando mostrar detalhes da operação.