O tipo de dados dynamic
Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel
O dynamic tipo de dados escalar pode ser qualquer um dos seguintes valores:
- Uma matriz de valores
dynamic, contendo zero ou mais valores com indexação baseada em zero. - Um recipiente de propriedades que mapeia valores de
stringexclusivos para valoresdynamic. O recipiente de propriedades tem zero ou mais desses mapeamentos (chamados de "slots"), indexados pelos valores destringexclusivos. Os slots não são ordenados. - Um valor de qualquer um dos tipos de dados escalares primitivos:
bool,datetime,guid,int,long,real,stringetimespan. - Nulo. Para obter mais informações, consulte Valores nulos.
Observação
- Os valores do tipo
dynamicsão limitados a 1 MB (2^20), descompactados. Se um valor de célula em um registro exceder 1 MB, o valor será descartado e a ingestão será bem-sucedida. Você pode aumentar oMaxValueSizeda coluna alterando sua política de codificação. - Embora o tipo pareça semelhante ao
dynamicJSON, ele pode conter valores que o modelo JSON não representa porque eles não existem em JSON (por exemplolong, ,real,datetime,timespan, eguid). Portanto, ao serializar valoresdynamicem uma representação de JSON, os valores que JSON não pode representar são serializados em valores destring. Por outro lado, o Azure Data Explorer analisará as cadeias de caracteres como valores fortemente tipados se elas puderem ser analisadas dessa maneira. Isso se aplica adatetime,real,long, eguidtipos. Para obter mais informações sobre o modelo de objeto JSON, consulte json.org. - O Azure Data Explorer não tenta preservar a ordem dos mapeamentos de nome para valor em um recipiente de propriedades e, portanto, você não pode presumir que a ordem será preservada. É perfeitamente possível que dois recipientes de propriedades com o mesmo conjunto de mapeamentos produza resultados diferentes quando são representados como valores de
string, por exemplo.
Literais dinâmicos
Para especificar um dynamic literal, use uma das seguintes opções de sintaxe:
| Sintaxe | Descrição | Exemplo |
|---|---|---|
dynamic([valor [, ...]]) |
Uma matriz de literais dinâmicos ou outros literais escalares. | dynamic([1, 2, "hello"]) |
dynamic({valor da chave = [, ...]}) |
Um recipiente de propriedades ou objeto. O valor de uma chave pode ser um recipiente de propriedades aninhado. | dynamic({"a":1, "b":{"a":2}}) |
dynamic(value) |
Um valor dinâmico que contém o valor do tipo de dados escalar interno. | dynamic(4) |
dynamic(null) |
Representa o valor nulo. |
Saiba mais sobre as convenções de sintaxe.
Acessadores de objeto dinâmico
Para adicionar um subscrito a um dicionário, use a notação de ponto (dict.key) ou de colchetes (dict["key"]). Quando o subscrito é uma constante de cadeia de caracteres, as duas opções são equivalentes.
Observação
Para usar uma expressão como subscrito, use a notação de colchetes. Ao usar expressões aritméticas, a expressão dentro dos colchetes deve ser encapsulada por parênteses.
Nos seguintes exemplos, dict e arr são colunas do tipo dinâmico:
| Expression | Tipo de expressão do acessador | Significado | Comentários |
|---|---|---|---|
| dict[col] | Nome da entidade (coluna) | Adiciona um subscrito a um dicionário usando os valores da coluna col como a chave |
A coluna precisa ser do tipo cadeia de caracteres |
| arr[index] | Índice da entidade (coluna) | Adiciona um subscrito a uma matriz usando os valores da coluna index como o índice |
A coluna precisa ser do tipo inteiro ou booliano |
| arr[-index] | Índice da entidade (coluna) | Recupera o valor 'index'-n do final da matriz | A coluna precisa ser do tipo inteiro ou booliano |
| arr[(-1)] | Índice da entidade | Recupera o último valor na matriz | |
| arr[toint(indexAsString)] | Chamada de função | Converte os valores da coluna indexAsString em int e os utiliza para adicionar um subscrito a uma matriz |
|
| dict[['where']] | Palavra-chave usada como nome da entidade (coluna) | Adiciona um subscrito a um dicionário usando os valores da coluna where como a chave |
Nomes de entidade idênticos a algumas palavras-chave da linguagem de consulta precisam estar entre aspas |
| dict.['where'] ou dict['where'] | Constante | Adiciona um subscrito a um dicionário usando a cadeia de caracteres where como a chave |
Dica
Recomendamos o uso de subscritos constantes quando possível.
Acessar um objeto secundário de um valor dynamic produz outro valor dynamic, mesmo que o objeto secundário tenha um tipo subjacente diferente. Use a função gettype para descobrir o tipo subjacente real do valor e qualquer função de conversão listada abaixo para convertê-lo no tipo real.
Convertendo objetos dinâmicos
Depois de adicionar um subscrito a um objeto dinâmico, você deve converter o valor em um tipo simples.
| Expression | Valor | Tipo |
|---|---|---|
| X | parse_json('[100,101,102]') | matriz |
| X[0] | parse_json('100') | dynamic |
| toint(X[1]) | 101 | int |
| Y | parse_json('{"a1":100, "a b c":"2015-01-01"}') | dicionário |
| Y.a1 | parse_json('100') | dynamic |
| Y["a b c"] | parse_json("2015-01-01") | dynamic |
| todate(Y["a b c"]) | datetime(2015-01-01) | datetime |
As funções de conversão são:
tolong()todouble()todatetime()totimespan()tostring()toguid()parse_json()
Criando objetos dinâmicos
Várias funções permitem que você crie objetos dynamic:
- bag_pack() cria um recipiente de propriedades a partir de pares de nome/valor.
- pack_array() cria um array a partir da lista de valores (pode ser lista de colunas, para cada linha ele criará um array a partir das colunas especificadas).
- range() cria uma matriz com uma série aritmética de números.
- zip() emparelha valores "paralelos" de duas matrizes em uma só matriz.
- repeat() cria uma matriz com um valor repetido.
Além disso, há várias funções de agregação que criam matrizes dynamic para armazenar valores agregados:
- buildschema() retorna o esquema de agregação de vários valores de
dynamic. - make_bag() retorna um recipiente de propriedades de valores dinâmicos dentro do grupo.
- make_bag_if() retorna um recipiente de propriedades de valores dinâmicos dentro do grupo (com um predicado).
- make_list() retorna uma matriz que contém todos os valores, em sequência.
- make_list_if() retorna uma matriz que contém todos os valores, em sequência (com um predicado).
- make_list_with_nulls() retorna uma matriz que contém todos os valores, em sequência, incluindo valores nulos.
- make_set() retorna uma matriz que contém todos os valores exclusivos.
- make_set_if() retorna uma matriz que contém todos os valores exclusivos (com um predicado).
Operadores e funções sobre tipos dinâmicos
Para obter uma lista completa de funções escalares dinâmicas/de matriz, consulte funções dinâmicas/de matriz.
| Operador ou função | Uso com tipos de dados dinâmicos |
|---|---|
Matriz de valor in |
True se houver um elemento de array que == valor where City in ('London', 'Paris', 'Rome') |
Matriz de valor !in |
True se não houver nenhum elemento de array que == valor |
array_length(array) |
Null se não for uma matriz |
bag_has_key(chave do saco,) |
Verifica se uma coluna de repositório dinâmico contém uma determinada chave. |
bag_keys(recipiente) |
Enumera todas as chaves raiz em um objeto de recipiente de propriedades dinâmicas. |
bag_merge(recipiente1,...,recipienteN) |
Mescla recipientes de propriedades dinâmicas em um recipiente de propriedades dinâmicas com todas as propriedades mescladas. |
bag_set_key(saco, chave, valor) |
Define uma determinada chave para um determinado valor em um recipiente de propriedades dinâmico. |
extract_json(caminho, objeto), extract_json(caminho, objeto) |
Use path para navegar no objeto. |
parse_json(source) |
Transforma uma cadeia de caracteres JSON em um objeto dinâmico. |
range(from,to,step) |
Uma matriz de valores . |
mv-expand listColumn |
Replica uma linha para cada valor em uma lista em uma célula especificada. |
summarize buildschema(column) |
Infere o esquema de tipo do conteúdo da coluna. |
summarize make_bag(column) |
Mescla os valores do recipiente de propriedades (dicionário) na coluna em um recipiente de propriedades, sem duplicação da chave. |
summarize make_bag_if(coluna,predicado) |
Mescla os valores do recipiente de propriedades (dicionário) na coluna em um recipiente de propriedades, sem duplicação da chave (com predicado). |
summarize make_list(column) |
Mescla os grupos de linhas e coloca os valores da coluna em uma matriz. |
summarize make_list_if(coluna,predicado) |
Nivela grupos de linhas e coloca os valores da coluna em uma matriz (com predicado). |
summarize make_list_with_nulls(column) |
Nivela grupos de linhas e coloca os valores da coluna em uma matriz, incluindo valores nulos. |
summarize make_set(column) |
Mescla os grupos de linhas e coloca os valores da coluna em uma matriz, sem duplicação. |
Indexação para dados dinâmicos
Cada campo é indexado durante a ingestão de dados. O escopo do índice é um único fragmento de dados.
Para indexar colunas dinâmicas, o processo de ingestão enumera todos os elementos "atômicos" dentro do valor dinâmico (nomes de propriedade, valores, elementos de matriz) e os encaminha para o construtor de índices. Caso contrário, os campos dinâmicos têm o mesmo índice de termo invertido que os campos de cadeia de caracteres.
Exemplos
Recipiente de propriedades dinâmico
A consulta a seguir cria um recipiente de propriedades dinâmicas.
print o=dynamic({"a":123, "b":"hello", "c":[1,2,3], "d":{}})
| extend a=o.a, b=o.b, c=o.c, d=o.d
Por conveniência, literais dynamic que aparecem no texto da consulta também podem incluir outros literais do Azure Data Explorer dos tipos: datetime, timespan, real, long, guid, bool e dynamic.
Essa extensão de JSON não está disponível ao analisar cadeias de caracteres (por exemplo, ao usar a função parse_json ou ao ingerir dados), mas permite que você faça o seguinte:
print d=dynamic({"a": datetime(1970-05-11)})
Para analisar um valor de string que segue as regras de codificação de JSON em um valor dynamic, use a função parse_json. Por exemplo:
parse_json('[43, 21, 65]')- uma matriz de númerosparse_json('{"name":"Alan", "age":21, "address":{"street":432,"postcode":"JLK32P"}}')– um dicionárioparse_json('21')- um único valor de tipo dinâmico que contém um númeroparse_json('"21"')- um único valor de tipo dinâmico que contém uma cadeia de caracteresparse_json('{"a":123, "b":"hello", "c":[1,2,3], "d":{}}')– fornece o mesmo valor queono exemplo acima.
Observação
Ao contrário do JavaScript, o JSON requer o uso de caracteres de aspas duplas (") em torno de cadeias de caracteres e nomes de propriedades do recipiente de propriedades. Portanto, geralmente é mais fácil citar um literal de cadeia de caracteres codificado em JSON usando um caractere de aspas simples (').
Ingerir dados em colunas dinâmicas
O exemplo a seguir mostra como você pode definir uma tabela que contém uma dynamic coluna (bem como uma datetime coluna) e, em seguida, ingerir um único registro nela. Ele também demonstra como você pode codificar cadeias de caracteres JSON em arquivos CSV.
// dynamic is just like any other type:
.create table Logs (Timestamp:datetime, Trace:dynamic)
// Everything between the "[" and "]" is parsed as a CSV line would be:
// 1. Since the JSON string includes double-quotes and commas (two characters
// that have a special meaning in CSV), we must CSV-quote the entire second field.
// 2. CSV-quoting means adding double-quotes (") at the immediate beginning and end
// of the field (no spaces allowed before the first double-quote or after the second
// double-quote!)
// 3. CSV-quoting also means doubling-up every instance of a double-quotes within
// the contents.
.ingest inline into table Logs
[2015-01-01,"{""EventType"":""Demo"", ""EventValue"":""Double-quote love!""}"]
Saída
| Timestamp | Trace |
|---|---|
| 2015-01-01 00:00:00.0000000 | {"EventType":"Demo","EventValue":"Double-quote love!"} |
Conteúdo relacionado
- Para obter um exemplo de como consultar usando objetos dinâmicos e acessadores de objetos, consulte Mapear valores de um conjunto para outro.