Exportar dados para uma tabela externa
Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer
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 Administrador de Tabela para executar este comando.
Sintaxe
.export [async] totablenome_da_tabela_externa
[ propertyNamewith( [ ...]] =<|consulta
Saiba mais sobre as convenções de sintaxe.
Parâmetros
| Nome | Digitar | Obrigatória | Descrição |
|---|---|---|---|
| nome_da_tabela_externa | 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 aceitas
As propriedades a seguir são suportadas como parte do comando exportar para tabela externa.
| Propriedade | Digitar | Descrição | Padrão |
|---|---|---|---|
sizeLimit |
long |
O limite de tamanho em bytes de um único artefato de armazenamento gravado antes da compactação. Um grupo completo de linhas de tamanho parquetRowGroupSize é gravado antes de verificar se esse grupo de linhas atinge o limite de tamanho e deve iniciar um novo artefato. Intervalo válido: 100 MB (padrão) a 1 GB. |
|
distributed |
bool |
Desabilite ou habilite a exportação distribuída. Definir como false é equivalente a dica de single 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 pela 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 | Indica ao sistema quantas partições devem ser executadas 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 os nós. 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 atinge 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 gravando no armazenamento simultaneamente. A distribuição padrão depende do particionamento da 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 estão exportando simultaneamente. Cada nó grava os dados atribuídos a esse nó. O número de arquivos exportados por um nó é 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ó grava um subconjunto dos valores da partição. Uma única partição é sempre gravada 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, a recomendação é 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 |
|---|---|---|
| Reduza o número de arquivos exportados | A exportação está criando muitos arquivos pequenos e você gostaria que ela criasse um número menor de arquivos maiores. | Defina distribution=single ou distributed=false (ambos são equivalentes) nas propriedades do 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. |
| Reduza a duração da exportação | Aumentar a simultaneidade da operação de exportação, para reduzir sua duração. | Defina distribution=per_shard nas propriedades do comando. Fazer 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 pela partição de cadeia de caracteres. Isso pode criar muita carga no armazenamento, resultando potencialmente em limitação. Consulte 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. Se uma partição for muito maior do que as outras, o nó atribuído a essa partição fará a maior parte do trabalho de exportação, enquanto os outros nós permanecerão praticamente ociosos. Para obter mais informações, consulte 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 que tem a melhor distribuição primeiro. * Defina distributionKind=uniform as propriedades do comando. Essa configuração desabilita as configurações de distribuição padrão para tabelas externas particionadas por cadeia de caracteres. A exportação é executada com per-node distribuição e cada nó exporta 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 de acordo. Para aumentar ainda mais a simultaneidade, defina distributionKind=uniform junto com distribution=per_shard para a simultaneidade mais alta (ao custo de potencialmente muito mais arquivos gravados)* Se a causa da exportação lenta não for discrepância nos dados, reduza a duração aumentando a simultaneidade, sem alterar as configurações de particionamento. Use as hint.spread propriedades and 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) é o valor mínimo entre 64 e o número de nós. Definir spread como 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 a tabela externa Permissões de gravação para o Armazenamento do Azure ou a tabela externa do SQL Server.
Saída
| Parâmetro de saída | Digitar | Descrição |
|---|---|---|
| Nome_da_tabela_externa | 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 seja 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. Para obter um exemplo, consulte 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__.
- 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
Para obter sugestões para superar erros de armazenamento durante comandos de exportação, consulte falhas durante comandos de exportação.
As colunas da tabela externa são mapeadas para tipos de dados de formato de destino adequados, de acordo com as regras de mapeamento de tipos de dados.
A exportação nativa do Parquet é um mecanismo de exportação de recursos leves e de melhor desempenho. Atualmente, uma coluna de
datetimeexportada não tem suporte do SQL do SynapseCOPY.
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 apenas
datetimepartições ou nenhuma partição, o número de arquivos gravados para cada partição existente deverá ser semelhante ao número de nós (ou mais, sesizeLimitfor atingido). Quando a operação de exportação é distribuída, todos os nós são exportados simultaneamente. Para desabilitar a distribuição, de modo que apenas um único nó faça as gravações, definadistributedcomo false. Esse processo cria menos arquivos, mas reduz 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
sizeLimitfor 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. A configuraçãodistributedcomo false, faz com que apenas um único nó faça a exportação, mas o comportamento permanece o mesmo (um único arquivo gravado por partição).
Exemplos
Exemplo de tabela externa não particionada
O exemplo a seguir exporta dados de T de tabela para a tabela ExternalBlob.
ExternalBlob é uma tabela externa não particionada.
.export to table ExternalBlob <| T
de saída
| Nome_da_tabela_externa | Caminho | NumRecords |
|---|---|---|
| Blob externo | http://storage1.blob.core.windows.net/externaltable1cont1/1_58017c550b384c0db0fea61a8661333e.csv | 10 |
Exemplo de tabela externa particionada
O exemplo a seguir primeiro cria uma tabela externa particionada, PartitionedExternalBlob com um local de armazenamento de blobs especificado. Os dados são armazenados no formato CSV com um formato de caminho que organiza os dados por nome e data do cliente.
.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'
)
Em seguida, exporta dados de T de tabela para a tabela externa PartitionedExternalBlob.
.export to table PartitionedExternalBlob <| T
de saída
| Nome_da_tabela_externa | Caminho | NumRecords |
|---|---|---|
| Blob externo | http://storageaccount.blob.core.windows.net/container1/CustomerName=customer1/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_1_58017c550b384c0db0fea61a8661333e.csv | 10 |
| Blob externo | 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 a palavra-chave async, a saída estará disponível usando o comando mostrar detalhes da operação comando.
Conteúdo relacionado
- de exportação contínua de dados
- Visão geral dos comandos de Gerenciamento de
- tabelas externas
- Exportar dados para o SQL
- Exportar dados para o armazenamento em nuvem