Como ingerir dados históricos no Azure Data Explorer

Um cenário comum ao integrar ao Azure Data Explorer é ingerir dados históricos, às vezes chamados de backfill. O processo envolve a ingestão de dados de um sistema de armazenamento existente em uma tabela, que é uma coleção de extensões.

Ingerir dados históricos utilizando a propriedade de ingestão 'creationTime' para definir o tempo de criação dos extents como o momento em que os dados foram criados. Usar o tempo de criação como critério de particionamento de ingestão pode envelhecer seus dados de acordo com suas políticas de cache e retenção e tornar os filtros de tempo mais eficientes.

Por padrão, o tempo de criação de extensões é definido como o momento em que você ingere os dados, o que pode não produzir o comportamento esperado. Por exemplo, suponha que você tenha uma tabela que tenha um período de cache de 30 dias e um período de retenção de dois anos. No fluxo normal, os dados ingeridos à medida que são produzidos são armazenados em cache por 30 dias e, em seguida, movidos para armazenamento refrigerado. Após dois anos, com base no seu tempo de criação, os dados mais antigos são removidos um dia de cada vez. No entanto, se você ingerir dois anos de dados históricos, onde, por padrão, os dados são marcados com tempo de criação como a hora em que os dados são ingeridos. Esse comportamento pode não produzir o resultado desejado porque:

Todos os dados ficam em cache e permanecem lá por 30 dias, usando mais cache do que você previa.
Os dados mais antigos não são removidos um dia de cada vez; portanto, os dados são retidos no cluster por mais tempo do que o necessário e, após dois anos, são todos removidos de uma só vez.
Os dados, anteriormente agrupados por data no sistema de origem, agora podem ser agrupados em lote na mesma medida, levando a consultas ineficientes.

Diagrama mostrando o resultado esperado versus real da ingestão de dados históricos usando o tempo de criação padrão.

Neste artigo, você aprenderá a particionar dados históricos:

Recomendado: utilizar a propriedade creationTime durante a ingestão.

Sempre que possível, ingira dados históricos usando a creationTime propriedade de ingestão, que permite definir a hora de criação das extensões de dados extraindo-a do ficheiro ou caminho de blob. Se a estrutura de pastas não usar um padrão de data de criação, reestruture o caminho do arquivo ou blob para refletir o tempo de criação. Usando esse método, os dados são ingeridos na tabela com o tempo de criação correto e os períodos de cache e retenção são aplicados corretamente.

Observação

Por padrão, as extensões são particionadas por tempo de criação (ingestão) e, na maioria dos casos, não há necessidade de definir uma política de particionamento de dados.
Usando uma política de particionamento após a ingestão

Se você não puder usar a creationTime propriedade de ingestão, por exemplo, se estiver ingerindo dados usando o conector do Azure Cosmos DB em que não pode controlar o tempo de criação ou se não pode reestruturar sua estrutura de pastas, poderá reparticionar a tabela após ingestão para obter o mesmo efeito usando a política de particionamento. No entanto, esse método pode exigir alguma tentativa e erro para otimizar as propriedades da política e é menos eficiente do que usar a creationTime propriedade de ingestão. Use este método somente quando não for possível usar a creationTime propriedade de ingestão.

Pré-requisitos

Uma conta Microsoft ou uma identidade de utilizador do Microsoft Entra. Você não precisa de uma assinatura do Azure.
Um cluster e um banco de dados do Azure Data Explorer. Crie um cluster e um banco de dados.
Uma conta de armazenamento.
Para o método recomendado de usar a propriedade de ingestão durante a creationTime ingestão, instale LightIngest.

Ingerir dados históricos

Particione dados históricos durante a ingestão usando a propriedade creationTime de ingestão. Se você não pode usar esse método, você pode reparticionar a tabela após a ingestão usando uma política de particionamento.

Durante a ingestão (recomendado)
Pós-ingestão

O LightIngest é útil para carregar dados históricos de um sistema de armazenamento existente para o Azure Data Explorer. Embora você possa criar seu próprio comando usando a lista de argumentos de linha de comando, este artigo mostra como gerar automaticamente esse comando por meio de um assistente de ingestão. Além de criar o comando, você pode usar esse processo para criar uma nova tabela e criar mapeamento de esquema. Esta ferramenta deduz o mapeamento de esquema a partir do seu conjunto de dados.

Destino

Na interface do usuário da Web do Azure Data Explorer, no menu à esquerda, selecione Consulta.
Clique com o botão direito do rato na base de dados onde pretende ingerir os dados e, em seguida, selecione LightIngest.

A janela Ingerir dados é aberta com a guia Destino selecionada. Os campos Cluster e Banco de Dados são preenchidos automaticamente.
Selecione uma tabela de destino. Para ingerir dados numa nova tabela, selecione Nova tabela e, em seguida, introduza um nome de tabela.

Observação

Os nomes das tabelas podem ter até 1.024 caracteres, incluindo espaços, caracteres alfanuméricos, hífenes e sublinhados. Não há suporte para caracteres especiais.
Selecione Next: Source.

Fonte

Em Selecionar origem, selecione Adicionar URL ou Selecionar contêiner.
- Ao adicionar uma URL, em Vincular à origem, especifique a chave da conta ou a URL SAS para um contêiner. Você pode criar a URL SAS manualmente ou automaticamente.
- Ao escolher um contentor da sua conta de armazenamento, selecione a sua assinatura de armazenamento, conta de armazenamento e contentor nos menus suspensos.
Observação

A ingestão suporta um tamanho máximo de ficheiro de 6 GB. A recomendação é ingerir arquivos entre 100 MB e 1 GB.
Selecione Configurações avançadas para definir configurações adicionais para o processo de ingestão usando LightIngest.

No painel Configuração avançada , defina as configurações do LightIngest de acordo com a tabela a seguir.

Captura de tela do painel de configuração avançada mostrando as configurações adicionais para o processamento de ingestão envolvendo a ferramenta LightIngest.

Propriedade	Description
Padrão de tempo de criação	Especifique para substituir a propriedade de tempo de ingestão da extensão criada por um padrão, por exemplo, para aplicar uma data com base na estrutura de pastas do contentor. Consulte também Padrão de tempo de criação.
Padrão de nome de blob	Especifique o padrão usado para identificar os arquivos a serem ingeridos. Ingerir todos os ficheiros que correspondem ao padrão de nome de blob no contentor dado. Suporta curingas. Recomendamos colocar entre aspas duplas.
Etiqueta	Uma tag atribuída aos dados ingeridos. A tag pode ser qualquer sequência de caracteres.
Limitar a quantidade de ficheiros	Especifique o número de arquivos a serem ingeridos. Ingere os primeiros `n` ficheiros que correspondam ao padrão de nome de blob, até ao número especificado.
Não espere que a ingestão termine	Se definido, enfileira as bolhas para ingestão sem monitorar o processo de ingestão. Se não estiver definido, LightIngest continuará a sondar o estado de ingestão até que a ingestão esteja completa.
Exibir apenas itens selecionados	Liste os arquivos no contêiner, mas não os ingere.

Selecione Concluído para retornar à guia Origem .
1. Opcionalmente, selecione Filtros de arquivo para filtrar os dados para ingerir apenas arquivos em um caminho de pasta específico ou com uma extensão de arquivo específica.
  
  Por padrão, um dos arquivos no contêiner é selecionado aleatoriamente e usado para gerar o esquema para a tabela.
2. Opcionalmente, em Esquema definindo arquivo, especifique o arquivo a ser usado.
Selecione Next: Schema para visualizar e editar a configuração da coluna da tabela.

Schema

O separador esquema fornece uma pré-visualização dos dados.

Para gerar o comando LightIngest, selecione Next: Start Ingestion.

Opcionalmente:

Altere o formato de dados inferido automaticamente selecionando o formato desejado no menu suspenso.
Altere o nome do mapeamento inferido automaticamente. Você pode usar caracteres alfanuméricos e sublinhados. Espaços, caracteres especiais e hífenes não são suportados.
Ao usar uma tabela existente, você pode Manter o esquema de tabela atual se o esquema de tabela corresponder ao formato selecionado.
Selecione Visualizador de comandos para visualizar e copiar os comandos automáticos gerados a partir de suas entradas.
Editar colunas. Em Visualização parcial de dados, selecione os menus suspensos de coluna para alterar vários aspetos da tabela.

As alterações que você pode fazer em uma tabela dependem dos seguintes parâmetros:

O tipo de tabela é novo ou existente
Tipo de mapeamento é novo ou existente

Tipo de tabela	Tipo de mapeamento	Ajustes disponíveis
Nova tabela	Novo mapeamento	Alterar tipo de dados, Renomear coluna, Nova coluna, Excluir coluna, Atualizar coluna, Classificar crescente, Classificar decrescente
Tabela existente	Novo mapeamento	Nova coluna (na qual você pode alterar o tipo de dados, renomear e atualizar), Coluna Atualizar, Ordenar em ordem crescente, Ordenar em ordem descendente
	Mapeamento existente	Ordenar ascendente, Ordenar descendente

Observação

Ao adicionar uma nova coluna ou atualizar uma coluna, você pode alterar as transformações de mapeamento. Para obter mais informações, consulte Mapeando transformações

Ingerir

Quando a tabela, o mapeamento e o comando LightIngest mostrarem marcas de seleção verdes, selecione o ícone de cópia no canto superior direito da caixa de comando Gerado para copiar o comando LightIngest gerado.

Observação

Se necessário, você pode baixar a ferramenta LightIngest selecionando Download LightIngest.
Para concluir o processo de ingestão, você deve executar LightIngest usando o comando copiado.

Etapa 1: Preparar para o reparticionamento

Ajuste a política de retenção para manter dados antigos. No exemplo a seguir, você define a política de retenção para a tabela MyTable como 10 anos.
```
.alter-merge table MyTable policy retention softdelete = 3650d recoverability = enabled
```
Ajuste a política de cache para que todos os dados estejam em cache quente para a repartição, pois apenas os dados quentes podem ser reparticionados depois da ingestão. No exemplo a seguir, você define o cache para a tabela MyTable como 10 anos.
```
.alter table MyTable policy caching hot = 3650d
```
Importante

Aumentar a política de cache pode usar consideravelmente mais hot cache do que em operações normais e pode resultar em maior custo.

Etapa 2: Iniciar o reparticionamento

Crie uma política de particionamento que particione os dados pela coluna chamada Timestamp. No exemplo a seguir, você define a política de particionamento da tabela MyTable como particionamento pela coluna chamada Timestamp.
```
.alter table MyTable policy partitioning
```
{
  "EffectiveDateTime" : "1970-01-01T00:00:00",
  "PartitionKeys": [
    {
      "ColumnName": "Timestamp",
      "Kind": "UniformRange",
      "Properties": {
        "Reference": "1970-01-01T00:00:00",
        "RangeSize": "1.00:00:00",
        "OverrideCreationTime": true
      }
    }
  ]
}
```
```
Para obter informações sobre as propriedades da política de particionamento, consulte Propriedades da partição. Para ingestão histórica, a forma como você define as seguintes propriedades é importante:
- Defina a propriedade EffectiveDateTime para uma data anterior ao início da ingestão para acionar o reparticionamento.
- Defina o RangeSize para um dia, dessa forma os dados serão reparticionados em partições de um dia. No entanto, você deve definir esse valor para alinhar com seus dados. Por exemplo, se você tiver menos de vários GBs de dados por dia, considere definir um valor maior.
- Defina OverrideCreationTime como true para que, depois de reparticionar os dados em day buckets, as extensões sejam marcadas com esse dia como o tempo de criação.
Defina uma política de mesclagem para permitir a mesclagem de todas as extensões, incluindo extensões com mais de 14 dias. A definição dessa política é importante porque o processo de reparticionamento cria extensões com mais de 14 dias, que por padrão são excluídas pelo processo de mesclagem.
```
.alter table MyTable policy merge
```
{
  "Lookback": {
    "Kind": "HotCache"
  }
}
```
```
Monitore o progresso do reparticionamento usando o comando .show database extents partitioning statistics . Nos resultados retornados, procure a tabela que está a reparticionar e monitore a coluna PercentagemDeLinhasParticionadas. Quando o valor da coluna PartitionedRowPercentage é 100, o reparticionamento está concluído.

Passo 3: Limpeza pós-reparticionamento

Quando o reparticionamento estiver concluído, você poderá limpar as políticas definidas nas etapas anteriores.

Remova a política de particionamento.

.delete table MyTable policy partitioning

Remova a política de mesclagem.
```
.delete table MyTable policy merge
```

Remova ou defina a política de cache.

// Remove the caching policy
.delete table MyTable policy caching
// OR set the caching policy to your desired value
.alter table MyTable policy caching hot = 90d

Remova ou defina a política de retenção.

// Remove the retention policy
.delete table MyTable policy retention
// OR set the retention policy to your desired value
.alter-merge table MyTable policy retention softdelete = 30d recoverability = enabled

Consultar dados no Azure Data Explorer

Feedback

Esta página foi útil?

Last updated on 2025-11-05