Exportar dados para uma tabela externa
Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer
Você pode exportar dados definindo um de tabela externa e exportando dados para ele. As propriedades da tabela são especificadas quando criando a tabela externa. O comando export faz referência à tabela externa pelo nome.
Permissões
Você deve ter pelo menos permissões de de administrador de tabela para executar esse comando.
Sintaxe
.export [async] totableexternalTableName
[with(propertyName=propertyValue [, ...])] <|consulta
Saiba mais sobre convenções de sintaxe.
Parâmetros
| Designação | Tipo | Necessá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 suportadas
As propriedades a seguir são suportadas como parte do comando export to external table.
| Propriedade | Tipo | Descrição | Inadimplência |
|---|---|---|---|
sizeLimit |
long |
O limite de tamanho em bytes de um único artefato de armazenamento gravado antes da compactação. Um grupo de linhas completas de tamanho parquetRowGroupSize é escrito 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 |
Desative ou habilite a exportação distribuída. Definir como false é equivalente a 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 uma distribuição uniforme quando a tabela externa é particionada por partição string. 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 | Dicas ao sistema como distribuir as partições entre nós. Veja mais detalhes em Configurações de distribuição | O valor padrão é Min(64, number-of-nodes). |
parquetRowGroupSize |
int |
Relevante apenas 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 é 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 tabelas externas | 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 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, a recomendação é definir a partição com 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 | Exportar é criar muitos arquivos pequenos, e você gostaria que ele 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, já que a simultaneidade é muito reduzida. |
| Reduzir a duração da exportação | Aumentar a simultaneidade da operação de exportação, para reduzir a sua duração. | Defina distribution=per_shard nas propriedades do 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. 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 estiverem uniformemente distribuídas 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 string, defina primeiro aquela com melhor distribuição. * Defina distributionKind=uniform nas 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 escrita por vários nós, e o número de arquivos aumenta de acordo. Para aumentar ainda mais a simultaneidade, defina distributionKind=uniform juntamente com distribution=per_shard para simultaneidade mais alta (ao custo de potencialmente muito mais arquivos gravados)* Se a causa para a exportação lenta não for outliers nos dados, reduza a duração aumentando a simultaneidade, sem alterar as configurações de particionamento. Use as propriedades hint.spread 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) é o valor mínimo entre 64 e o número de nós. Definir 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 o de permissões de Gravação
Realização
| 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. Este 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, não é possível 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 respetivos 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 os comandos de exportação, consulte falhas durante os comandos de exportação.
As colunas da tabela externa são mapeadas para tipos de dados de formato de destino adequados, de acordo com tipos de dados mapeando regras.
A exportação nativa de parquet é um mecanismo de exportação mais eficiente e leve de recursos. Uma coluna
datetimeexportada não é suportada atualmente pelo Synapse SQLCOPY.
Número de ficheiros
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 partições
datetime, ou nenhuma partição, o número de arquivos gravados para cada partição existente deve 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 desativar a distribuição, para 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 atingida). 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. Definirdistributedcomo 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 da tabela T para a tabela ExternalBlob.
ExternalBlob é uma tabela externa não particionada.
.export to table ExternalBlob <| T
Output
| ExternalTableName | Caminho | NumRecords |
|---|---|---|
| Blob Externo | http://storage1.blob.core.windows.net/externaltable1cont1/1_58017c550b384c0db0fea61a8661333e.csv | 10 |
Exemplo de tabela externa particionada
O exemplo a seguir cria primeiro uma tabela externa particionada, PartitionedExternalBlob com um local de armazenamento de blob especificado. Os dados são armazenados em 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 da tabela T para a tabela externa PartitionedExternalBlob.
.export to table PartitionedExternalBlob <| T
Output
| ExternalTableName | 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 show operation details.
Conteúdo relacionado
- Exportação contínua de dados
- Visão geral dos comandos de gerenciamento de
- Tabelas externas
- Exportar dados para o SQL
- Exportar dados para de armazenamento em nuvem