Mapeamentos de ingestão

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 oferece suporte a 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 pré-criados e podem ser referenciados a partir do comando ingest usando ingestionMappingReference parâmetros. No entanto, 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	Obrigatório	Descrição
Coluna	✔️	Nome da coluna de destino na tabela.
Datatype		Tipo de dados com o qual criar a coluna mapeada se ela ainda não existir na tabela.
Propriedades		Conjunto de propriedades que contém 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, uma vez que os 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 como 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 Ingestion. Quanto mais distintas as propriedades de mapeamento de ingestão utilizadas, como diferentes valores de ConstValue, mais fragmentada se torna a ingestão, 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 de Dados	Tipo de Mapeamento
CSV	Mapeamento CSV
TSV	Mapeamento CSV
TSVe	Mapeamento CSV
PSV	Mapeamento CSV
SCSV	Mapeamento CSV
SOHsv	Mapeamento CSV
TXT	Mapeamento CSV
RAW	Mapeamento CSV
JSON	Mapeamento JSON
AVRO	Mapeamento AVRO
APACHEAVRO	Mapeamento AVRO
Parquet	Mapeamento de Parquet
ORC	Mapeamento ORC
W3CLOGFILE	Mapeamento W3CLOGFILE

Mapeamento de identidade

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

Tipo de formato	Formatar	Lógica de mapeamento
Formatos de dados tabulares com ordem definida de colunas, como formatos separados por delimitador ou de linha única.	CSV, TSV, TSVe, PSV, SCSV, Txt, SOHsv, Raw	Todas as colunas da tabela são mapeadas em sua respectiva ordem para colunas de dados na ordem em que aparecem na fonte de dados. O tipo de dados de coluna é retirado do esquema de 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 (diferencia maiúsculas de minúsculas). O tipo de dados de coluna é retirado do esquema de tabela.

Aviso

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.

Transformações de mapeamento

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

Transformação dependente de 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 JSONtipos de mapeamento e ParquetAVROORC , .
SourceLocation	Nome do artefato de armazenamento que forneceu os dados, digite string (por exemplo, o campo "BaseUri" do blob).	Disponível para CSVos tipos , JSON, Parquet, AVROORC e W3CLOGFILE 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 CSVos tipos , JSON, Parquet, AVROORC e W3CLOGFILE mapeamento.
DateTimeFromUnixSeconds	Converte o número que representa unix-time (segundos desde 1970-01-01) em cadeia de caracteres datetime UTC.	Disponível para JSONtipos de mapeamento e ParquetAVROORC , .
DateTimeFromUnixMilliseconds	Converte o número que representa unix-time (milissegundos desde 1970-01-01) em cadeia de caracteres datetime UTC.	Disponível para JSONtipos de mapeamento e ParquetAVROORC , .
DateTimeFromUnixMicroseconds	Converte o número que representa unix-time (microssegundos desde 1970-01-01) em cadeia de caracteres datetime UTC.	Disponível para JSONtipos de mapeamento e ParquetAVROORC , .
DateTimeFromUnixNanoseconds	Converte o número que representa unix-time (nanossegundos desde 1970-01-01) em cadeia de caracteres datetime UTC.	Disponível para JSONtipos de mapeamento e ParquetAVROORC , .
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 JSONtipos de mapeamento e ParquetAVROORC , .
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 format, o tipo de esquema do campo de dados mapeado deve ser bytes ou fixed tipo Avro. Para Avro formatar, o campo deve ser uma matriz contendo valores de bytes do intervalo [0-255]. null será ingerido 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 o objeto inteiro Props em coluna Props dinâmica, excluindo colunas já mapeadas (Props.EventName já está mapeado em coluna EventName, portanto, é excluído).

[
    { "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	EventName	Props
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:

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