Partilhar via

Mapeamentos de ingestão

  • Artigo

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer

Os mapeamentos de ingestão são usados durante a ingestão para mapear dados de entrada para colunas dentro de tabelas.

O Data Explorer suporta diferentes tipos de mapeamentos, orientados a linhas (CSV, JSON, AVRO e W3CLOGFILE) e a colunas (Parquet e ORC).

Os mapeamentos de ingestão podem ser definidos no comando ingest ou podem ser pré-criados e referenciados a partir do comando ingest usando parâmetros ingestionMappingReference. A ingestão é possível sem especificar um mapeamento. Para obter mais informações, consulte mapeamento de identidade.

Cada elemento na lista de mapeamento é construído a partir de três campos:

Propriedade Necessário Descrição
Coluna ✔️ Nome da coluna de destino na tabela.
Tipo de dados Tipo de dados com o qual criar a coluna mapeada se ela ainda não existir na tabela.
Propriedades Property-bag contendo propriedades específicas para cada mapeamento, conforme descrito em cada página de tipo de mapeamento específico.

Importante

Para ingestão em fila:

  • Se a tabela referenciada no mapeamento não existir no banco de dados, ela será criada automaticamente, dado que tipos de dados válidos são especificados para todas as colunas.
  • Se uma coluna referenciada no mapeamento não existir na tabela, ela será adicionada automaticamente à tabela à medida que a última coluna na primeira vez que os dados forem ingeridos para essa coluna, dado que um tipo de dados válido é especificado para a coluna. Para adicionar novas colunas a um mapeamento, use o comando .alter ingestion mapping.
  • Os dados são agrupados em lote usando as propriedades de ingestão. Quanto mais distintas forem as propriedades de mapeamento de ingestão usadas, como diferentes valores de ConstValue, mais fragmentada a ingestão se torna, o que pode levar à degradação do desempenho.

Tipos de mapeamento suportados

A tabela a seguir define os tipos de mapeamento a serem usados ao ingerir ou consultar dados externos de um formato específico.

Formato dos dados Tipo de mapeamento
CSV de mapeamento CSV
TSV de mapeamento CSV
TSVe de mapeamento CSV
PSV de mapeamento CSV
SCSV de mapeamento CSV
SOHsv de mapeamento CSV
TXT de mapeamento CSV
CRU de mapeamento CSV
JSON de mapeamento JSON
AVRO de mapeamento AVRO
APACHEAVRO de mapeamento AVRO
Parquet Parquet Mapping
ORC de mapeamento ORC
W3CLOGFILE W3CLOGFILE Mapeamento

Exemplos de mapeamento de ingestão

Os exemplos a seguir usam a tabela RawEvents com o seguinte esquema:

.create table RawEvents (timestamp: datetime, deviceId: guid, messageId: guid, temperature: decimal, humidity: decimal)

Mapeamento simples

O exemplo a seguir mostra a ingestão onde o mapeamento é definido no comando ingest. O comando ingere um arquivo JSON de uma URL na tabela RawEvents. O mapeamento especifica o caminho para cada campo no arquivo JSON.

.ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') 
    with (
            format = "json",
            ingestionMapping =
            ```
            [ 
              {"column":"timestamp","Properties":{"path":"$.timestamp"}},
              {"column":"deviceId","Properties":{"path":"$.deviceId"}},
              {"column":"messageId","Properties":{"path":"$.messageId"}},
              {"column":"temperature","Properties":{"path":"$.temperature"}},
              {"column":"humidity","Properties":{"path":"$.humidity"}}
            ]
            ```
          )

Mapeando com ingestionMappingReference

Para mapear o mesmo arquivo JSON usando um mapeamento pré-criado, crie a referência de mapeamento de ingestão de RawEventMapping com o seguinte comando:

.create table RawEvents ingestion json mapping 'RawEventMapping' 
  ```
  [ 
    {"column":"timestamp","Properties":{"path":"$.timestamp"}},
    {"column":"deviceId","Properties":{"path":"$.deviceId"}},
    {"column":"messageId","Properties":{"path":"$.messageId"}},
    {"column":"temperature","Properties":{"path":"$.temperature"}},
    {"column":"humidity","Properties":{"path":"$.humidity"}}
  ]
  ```

Ingerir o arquivo JSON usando a referência de mapeamento de ingestão RawEventMapping com o seguinte comando:

.ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') 
  with (
          format="json",
          ingestionMappingReference="RawEventMapping"
        )

Mapeamento de identidade

A ingestão é possível sem especificar ingestionMapping ou ingestionMappingReference propriedades. Os dados são mapeados usando um mapeamento de dados de identidade derivado do esquema da tabela. O esquema da tabela permanece o mesmo. format propriedade deve ser especificada. Consulte formatos de ingestão.

Tipo de formato Formato Lógica de mapeamento
Formatos de dados tabulares com ordem definida de colunas, como formatos separados por delimitadores ou de linha única. CSV, TSV, TSVe, PSV, SCSV, Txt, SOHsv, Raw Todas as colunas da tabela são mapeadas em sua respetiva ordem para colunas de dados na ordem em que aparecem na fonte de dados. O tipo de dados de coluna é retirado do esquema da tabela.
Formatos com colunas nomeadas ou registros com campos nomeados. JSON, Parquet, Avro, ApacheAvro, Orc, W3CLOGFILE Todas as colunas da tabela são mapeadas para colunas de dados ou campos de registro com o mesmo nome (diferenciam maiúsculas de minúsculas). O tipo de dados de coluna é retirado do esquema da tabela.

Advertência

Qualquer incompatibilidade entre o esquema da tabela e a estrutura dos dados, como tipos de dados de coluna ou campo, nomes de colunas ou campos ou seu número, pode resultar em dados vazios ou incorretos ingeridos.

Mapeando transformações

Alguns dos mapeamentos de formato de dados (Parquet, JSON e AVRO) suportam transformações de tempo de ingestão simples e úteis. Quando o cenário exigir um processamento mais complexo no momento da ingestão, use política de atualização, que permite definir o processamento leve usando a expressão KQL.

Transformação dependente do caminho Descrição Condições
PropertyBagArrayToDictionary Transforma a matriz JSON de propriedades, como {events:[{"n1":"v1"},{"n2":"v2"}]}, em dicionário e a serializa em documento JSON válido, como {"n1":"v1","n2":"v2"}. Disponível para JSON, Parquet, AVROe ORC tipos de mapeamento.
Localização da fonte Nome do artefato de armazenamento que forneceu os dados, digite string (por exemplo, o campo "BaseUri" do blob). Disponível para CSV, JSON, Parquet, AVRO, ORCe W3CLOGFILE tipos de mapeamento.
SourceLineNumber Deslocamento em relação a esse artefato de armazenamento, digite long (começando com '1' e incrementando por novo registro). Disponível para CSV, JSON, Parquet, AVRO, ORCe W3CLOGFILE tipos de mapeamento.
DateTimeFromUnixSeconds Converte o número que representa unix-time (segundos desde 1970-01-01) em string datetime UTC. Disponível para CSV, JSON, Parquet, AVROe ORC tipos de mapeamento.
DateTimeFromUnixMilliseconds Converte o número que representa unix-time (milissegundos desde 1970-01-01) em string datetime UTC. Disponível para CSV, JSON, Parquet, AVROe ORC tipos de mapeamento.
DateTimeFromUnixMicroseconds Converte o número que representa unix-time (microssegundos desde 1970-01-01) em string datetime UTC. Disponível para CSV, JSON, Parquet, AVROe ORC tipos de mapeamento.
DateTimeFromUnixNanoseconds Converte o número que representa unix-time (nanossegundos desde 1970-01-01) em string datetime UTC. Disponível para CSV, JSON, Parquet, AVROe ORC tipos de mapeamento.
DropMappedFields Mapeia um objeto no documento JSON para uma coluna e remove todos os campos aninhados já referenciados por outros mapeamentos de coluna. Disponível para JSON, Parquet, AVROe ORC tipos de mapeamento.
BytesAsBase64 Trata os dados como matriz de bytes e os converte em uma cadeia de caracteres codificada em base64. Disponível para AVRO tipo de mapeamento. Para ApacheAvro formato, o tipo de esquema do campo de dados mapeados deve ser bytes ou fixed tipo Avro. Para Avro formato, o campo deve ser uma matriz contendo valores de bytes do intervalo [0-255]. null será ingerida se os dados não representarem uma matriz de bytes válida.

Mapeando exemplos de transformação

DropMappedFields transformação:

Dado o seguinte conteúdo JSON:

{
    "Time": "2012-01-15T10:45",
    "Props": {
        "EventName": "CustomEvent",
        "Revenue": 0.456
    }
}

O mapeamento de dados a seguir mapeia todo Props objeto em Props de coluna dinâmica, excluindo colunas já mapeadas (Props.EventName já está mapeada na coluna EventName, portanto, é excluída).

[
    { "Column": "Time", "Properties": { "Path": "$.Time" } },
    { "Column": "EventName", "Properties": { "Path": "$.Props.EventName" } },
    { "Column": "Props", "Properties": { "Path": "$.Props", "Transform":"DropMappedFields" } },
]

Os dados ingeridos têm a seguinte aparência:

Hora Nome do Evento Adereços
2012-01-15T10:45 CustomEvent {"Revenue": 0.456}

BytesAsBase64 transformação

Dado o seguinte conteúdo do arquivo AVRO:

{
    "Time": "2012-01-15T10:45",
    "Props": {
        "id": [227,131,34,92,28,91,65,72,134,138,9,133,51,45,104,52]
    }
}

O mapeamento de dados a seguir mapeia a coluna ID duas vezes, com e sem a transformação.

[
    { "Column": "ID", "Properties": { "Path": "$.props.id" } },
    { "Column": "Base64EncodedId", "Properties": { "Path": "$.props.id", "Transform":"BytesAsBase64" } },
]

Os dados ingeridos têm a seguinte aparência:

Identificação Base64EncodedId
[227,131,34,92,28,91,65,72,134,138,9,133,51,45,104,52] 44MiXBxbQUiGigmFMy1oNA==