Funções de map | ClickHouse Docs

extractKeyValuePairs

Introduzido em: v23.4.0

Extrai pares chave-valor de qualquer string. A string não precisa estar 100% estruturada no formato de par chave-valor;

Pode conter ruído (por exemplo, arquivos de log). O formato de par chave-valor a ser interpretado deve ser especificado por meio dos argumentos da função.

Um par chave-valor consiste em uma chave seguida de um key_value_delimiter e um valor. Chaves e valores entre aspas também são suportados. Os pares chave-valor devem ser separados por delimitadores de pares.

Sintaxe

extractKeyValuePairs(data, [key_value_delimiter], [pair_delimiter], [quoting_character], [unexpected_quoting_character_strategy])

Argumentos

data - String da qual serão extraídos pares chave-valor. String ou FixedString.
key_value_delimiter - Caractere a ser usado como delimitador entre a chave e o valor. O padrão é :. String ou FixedString.
pair_delimiters - Conjunto de caracteres a ser usado como delimitadores entre pares. O padrão é \space, , e ;. String ou FixedString.
quoting_character - Caractere a ser usado para delimitar aspas. O padrão é ". String ou FixedString.
unexpected_quoting_character_strategy - Estratégia para lidar com caracteres de aspas em posições inesperadas durante a fase read_key e read_value. Valores possíveis: invalid, accept e promote. invalid descartará a chave ou o valor e fará a transição de volta para o estado WAITING_KEY. accept o tratará como um caractere normal. promote fará a transição para o estado READ_QUOTED_{KEY/VALUE} e começará a partir do próximo caractere. O valor padrão é PROMOTE

Valores retornados

Os pares chave-valor extraídos em um Map(String, String).

Exemplos

Consulta:

Caso simples

arthur :) select extractKeyValuePairs('name:neymar, age:31 team:psg,nationality:brazil') as kv

SELECT extractKeyValuePairs('name:neymar, age:31 team:psg,nationality:brazil') as kv

Query id: f9e0ca6f-3178-4ee2-aa2c-a5517abb9cee

┌

Aspas simples como caractere de citação

arthur :) select extractKeyValuePairs('name:\'neymar\';\'age\':31;team:psg;nationality:brazil,last_key:last_value', ':', ';,', '\'') as kv

SELECT extractKeyValuePairs('name:\'neymar\';\'age\':31;team:psg;nationality:brazil,last_key:last_value', ':', ';,', '\'') as kv

Query id: 0e22bf6b-9844-414a-99dc-32bf647abd5e

┌

exemplos de unexpected_quoting_character_strategy:

unexpected_quoting_character_strategy=invalid

SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'INVALID') as kv;

┌─kv────────────────┐
│ {'abc':'5'}       │
└───────────────────┘

SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'INVALID') as kv;

┌─kv──┐
│ {}  │
└─────┘

unexpected_quoting_character_strategy=accept

SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'ACCEPT') as kv;

┌─kv────────────────┐
│ {'name"abc':'5'}  │
└───────────────────┘

SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'ACCEPT') as kv;

┌─kv─────────────────┐
│ {'name"abc"':'5'}  │
└────────────────────┘

unexpected_quoting_character_strategy=promote

SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'PROMOTE') as kv;

┌─kv──┐
│ {}  │
└─────┘

SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'PROMOTE') as kv;

┌─kv───────────┐
│ {'abc':'5'}  │
└──────────────┘

Sequências de escape sem suporte a sequências de escape

arthur :) select extractKeyValuePairs('age:a\\x0A\\n\\0') as kv

SELECT extractKeyValuePairs('age:a\\x0A\\n\\0') AS kv

Query id: e9fd26ee-b41f-4a11-b17f-25af6fd5d356

┌

Sintaxe

extractKeyValuePairs(data, [key_value_delimiter], [pair_delimiter], [quoting_character], [unexpected_quoting_character_strategy])

Aliases: str_to_map, mapFromString

Argumentos

Nenhum.

Valor retornado

Exemplos

extractKeyValuePairsWithEscaping

Introduzido em: v23.4.0

Igual a extractKeyValuePairs, mas com suporte a sequências de escape.

Sequências de escape aceitas: \x, \N, \a, \b, \e, \f, \n, \r, \t, \v e \0. Sequências de escape fora do padrão são retornadas como estão (incluindo a barra invertida), a menos que sejam uma das seguintes: \\, ', ", backtick, /, = ou caracteres de controle ASCII (c <= 31).

Esta função atende ao caso de uso em que pre-escaping e post-escaping não são adequados. Por exemplo, considere a seguinte string de entrada: a: "aaaa\"bbb". A saída esperada é: a: aaaa\"bbbb.

Pre-escaping: ao aplicar pre-escaping, a saída será: a: "aaaa"bbb" e extractKeyValuePairs então produzirá: a: aaaa
Post-escaping: extractKeyValuePairs produzirá a: aaaa\ e o post-escaping o manterá como está.

As sequências de escape iniciais serão ignoradas nas chaves e consideradas inválidas nos valores.

Sequências de escape com suporte a sequências de escape habilitado

arthur :) select extractKeyValuePairsWithEscaping('age:a\\x0A\\n\\0') as kv

SELECT extractKeyValuePairsWithEscaping('age:a\\x0A\\n\\0') AS kv

Query id: 44c114f0-5658-4c75-ab87-4574de3a1645

┌

Sintaxe

extractKeyValuePairsWithEscaping(data, [key_value_delimiter], [pair_delimiter], [quoting_character], [unexpected_quoting_character_strategy])

Argumentos

Nenhum.

Valor retornado

Exemplos

map

Introduzido em: v21.1.0

Cria um valor do tipo Map(key, value) a partir de pares chave-valor.

Sintaxe

map(key1, value1[, key2, value2, ...])

Argumentos

key_n — As chaves das entradas do map. Any
value_n — Os valores das entradas do map. Any

Valor retornado

Retorna um map que contém pares chave:valor. Map(Any, Any)

Exemplos

Exemplo de uso

SELECT map('key1', number, 'key2', number * 2) FROM numbers(3)

{'key1':0,'key2':0}
{'key1':1,'key2':2}
{'key1':2,'key2':4}

mapAdd

Introduzido em: v20.7.0

Coleta todas as chaves e soma os valores correspondentes.

Sintaxe

mapAdd(arg1[, arg2, ...])

Argumentos

arg1[, arg2, ...] — maps ou tuplas de dois arrays, nos quais os itens do primeiro array representam chaves, e o segundo array contém os valores de cada chave. Map(K, V) ou Tuple(Array(T), Array(T))

Valor retornado

Retorna um map ou uma tupla, em que o primeiro array contém as chaves ordenadas e o segundo array contém os valores. Map(K, V) ou Tuple(Array(T), Array(T))

Exemplos

Com o tipo Map

SELECT mapAdd(map(1, 1), map(1, 1))

{1:2}

Com tupla

SELECT mapAdd(([toUInt8(1), 2], [1, 1]), ([toUInt8(1), 2], [1, 1]))

([1,2],[2,2])

mapAll

Introduzido em: v23.4.0

Verifica se uma condição é satisfeita para todos os pares chave-valor em um map. mapAll é uma função de ordem superior. Você pode passar uma função lambda como primeiro argumento.

Sintaxe

mapAll([func,] map)

Argumentos

func — Função lambda. Função lambda
map — map a ser verificado. Map(K, V)

Valor retornado

Retorna 1 se todos os pares chave-valor satisfizerem a condição, 0 caso contrário. UInt8

Exemplos

Exemplo de uso

SELECT mapAll((k, v) -> v = 1, map('k1', 1, 'k2', 2))

mapApply

Introduzido em: v22.3.0

Aplica uma função a cada elemento de um map.

Sintaxe

mapApply(func, map)

Argumentos

func — Função lambda. Função lambda
map — map ao qual a função será aplicada. Map(K, V)

Valor retornado

Retorna um novo map obtido a partir do map original pela aplicação de func a cada elemento. Map(K, V)

Exemplos

Exemplo de uso

SELECT mapApply((k, v) -> (k, v * 2), map('k1', 1, 'k2', 2))

{'k1':2,'k2':4}

mapConcat

Introduzido em: v23.4.0

Concatena vários maps com base na igualdade entre suas chaves. Se houver elementos com a mesma chave em mais de um map de entrada, todos os elementos serão adicionados ao map resultante, mas apenas o primeiro poderá ser acessado pelo operador [].

Sintaxe

mapConcat(maps)

Argumentos

maps — Uma quantidade arbitrária de maps. Map

Valor retornado

Retorna um map com a concatenação dos maps passados como argumentos. Map

Exemplos

Exemplo de uso

SELECT mapConcat(map('k1', 'v1'), map('k2', 'v2'))

{'k1':'v1','k2':'v2'}

mapContainsKey

Introduzido em: v21.2.0

Determina se uma chave está contida em um map.

Sintaxe

mapContainsKey(map, key)

Aliases: mapContains

Argumentos

map — map em que pesquisar. Map(K, V)
key — chave a ser pesquisada. O tipo deve corresponder ao tipo da chave do map. Any

Valor retornado

Retorna 1 se o map contiver a chave, 0 caso contrário. UInt8

Exemplos

Exemplo de uso

SELECT mapContainsKey(map('k1', 'v1', 'k2', 'v2'), 'k1')

mapContainsKeyLike

Introduzido em: v23.4.0

Verifica se o map contém uma chave correspondente ao padrão especificado com LIKE.

Sintaxe

mapContainsKeyLike(map, pattern)

Argumentos

map — map onde pesquisar. Map(K, V)
pattern — Padrão para correspondência das chaves. const String

Valor retornado

Retorna 1 se map contiver uma chave que corresponda a pattern; caso contrário, 0. UInt8

Exemplos

Exemplo de uso

CREATE TABLE tab (a Map(String, String))
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO tab VALUES ({'abc':'abc','def':'def'}), ({'hij':'hij','klm':'klm'});

SELECT mapContainsKeyLike(a, 'a%') FROM tab;

┌─mapContainsKeyLike(a, 'a%')─┐
│                           1 │
│                           0 │
└─────────────────────────────┘

mapContainsValue

Introduzido em: v25.6.0

Determina se um valor está presente em um map.

Sintaxe

mapContainsValue(map, value)

Argumentos

map — map em que a busca será realizada. Map(K, V)
value — Valor a ser buscado. O tipo deve corresponder ao tipo de valor do map. Any

Valor retornado

Retorna 1 se o map contiver o valor e 0 caso contrário. UInt8

Exemplos

Exemplo de uso

SELECT mapContainsValue(map('k1', 'v1', 'k2', 'v2'), 'v1')

mapContainsValueLike

Introduzido em: v25.5.0

Verifica se um map contém um valor que corresponde ao padrão especificado via LIKE.

Sintaxe

mapContainsValueLike(map, pattern)

Argumentos

map — map em que será feita a busca. Map(K, V)
pattern — Padrão usado para corresponder aos valores. const String

Valor retornado

Retorna 1 se map contiver um valor que corresponda a pattern, 0 caso contrário. UInt8

Exemplos

Exemplo de uso

CREATE TABLE tab (a Map(String, String))
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO tab VALUES ({'abc':'abc','def':'def'}), ({'hij':'hij','klm':'klm'});

SELECT mapContainsValueLike(a, 'a%') FROM tab;

┌─mapContainsValueLike(a, 'a%')─┐
│                             1 │
│                             0 │
└───────────────────────────────┘

mapExists

Introduzido em: v23.4.0

Verifica se uma condição é atendida para pelo menos um par chave-valor em um map. mapExists é uma função de ordem superior. Você pode passar uma função lambda como primeiro argumento.

Sintaxe

mapExists([func,] map)

Argumentos

func — Opcional. Função lambda. Função lambda
map — map a ser verificado. Map(K, V)

Valor retornado

Retorna 1 se pelo menos um par chave-valor atender à condição, 0 caso contrário. UInt8

Exemplos

Exemplo de uso

SELECT mapExists((k, v) -> v = 1, map('k1', 1, 'k2', 2))

mapExtractKeyLike

Introduzido em: v23.4.0

Dado um map com chaves do tipo string e um padrão LIKE, esta função retorna um map com os elementos cuja chave corresponde ao padrão.

Sintaxe

mapExtractKeyLike(map, pattern)

Argumentos

map — map do qual extrair. Map(K, V)
pattern — padrão com o qual comparar as chaves. const String

Valor retornado

Retorna um map contendo os elementos cujas chaves correspondem ao padrão especificado. Se nenhum elemento corresponder ao padrão, será retornado um map vazio. Map(K, V)

Exemplos

Exemplo de uso

CREATE TABLE tab (a Map(String, String))
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO tab VALUES ({'abc':'abc','def':'def'}), ({'hij':'hij','klm':'klm'});

SELECT mapExtractKeyLike(a, 'a%') FROM tab;

┌─mapExtractKeyLike(a, 'a%')─┐
│ {'abc':'abc'}              │
│ {}                         │
└────────────────────────────┘

mapExtractValueLike

Introduzido na versão: v25.5.0

Dado um map com valores do tipo string e um padrão LIKE, esta função retorna um map com os elementos cujo valor corresponde ao padrão.

Sintaxe

mapExtractValueLike(map, pattern)

Argumentos

map — Map do qual extrair. Map(K, V)
pattern — Padrão com o qual os valores são comparados. const String

Valor retornado

Retorna um map contendo os elementos cujo valor corresponde ao padrão especificado. Se nenhum elemento corresponder ao padrão, será retornado um map vazio. Map(K, V)

Exemplos

Exemplo de uso

CREATE TABLE tab (a Map(String, String))
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO tab VALUES ({'abc':'abc','def':'def'}), ({'hij':'hij','klm':'klm'});

SELECT mapExtractValueLike(a, 'a%') FROM tab;

┌─mapExtractValueLike(a, 'a%')─┐
│ {'abc':'abc'}                │
│ {}                           │
└──────────────────────────────┘

mapFilter

Introduzido em: v22.3.0

Filtra um map aplicando uma função a cada um de seus elementos.

Sintaxe

mapFilter(func, map)

Argumentos

func — Função lambda. Função lambda
map — map a ser filtrado. Map(K, V)

Valor retornado

Retorna um map que contém apenas os elementos para os quais func retorna um valor diferente de 0. Map(K, V)

Exemplos

Exemplo de uso

SELECT mapFilter((k, v) -> v > 1, map('k1', 1, 'k2', 2))

{'k2':2}

mapFromArrays

Introduzido em: v23.3.0

Cria um map a partir de um array ou map de chaves e de um array ou map de valores. A função é uma alternativa conveniente à sintaxe CAST([...], 'Map(key_type, value_type)').

Sintaxe

mapFromArrays(keys, values)

Aliases: MAP_FROM_ARRAYS

Argumentos

keys — Array ou map de chaves a partir do qual criar o map. Array ou Map
values — Array ou map de valores a partir do qual criar o map. Array ou Map

Valor retornado

Retorna um map com chaves e valores construídos a partir do array de chaves e do array/map de valores. Map

Exemplos

Uso básico

SELECT mapFromArrays(['a', 'b', 'c'], [1, 2, 3])

{'a':1,'b':2,'c':3}

Com entradas do tipo map

SELECT mapFromArrays([1, 2, 3], map('a', 1, 'b', 2, 'c', 3))

{1:('a',1),2:('b',2),3:('c',3)}

mapKeys

Introduzido em: v21.2.0

Retorna as chaves de um determinado map. Esta função pode ser otimizada ativando a configuração optimize_functions_to_subcolumns. Com a configuração ativada, a função lê apenas a subcoluna keys, em vez do map inteiro. A consulta SELECT mapKeys(m) FROM table é transformada em SELECT m.keys FROM table.

Sintaxe

mapKeys(map)

Argumentos

map — map do qual as chaves serão extraídas. Map(K, V)

Valor retornado

Retorna um array com todas as chaves do map. Array(T)

Exemplos

Exemplo de uso

SELECT mapKeys(map('k1', 'v1', 'k2', 'v2'))

['k1','k2']

mapPartialReverseSort

Introduzido em: v23.4.0

Ordena os elementos de um map em ordem decrescente, com um argumento de limite adicional que permite ordenação parcial. Se a função func for especificada, a ordem de ordenação será determinada pelo resultado da função func aplicada às chaves e aos valores do map.

Sintaxe

mapPartialReverseSort([func,] limit, map)

Argumentos

func — Opcional. Função lambda. Função lambda
limit — Os elementos no intervalo [1..limit] são ordenados. (U)Int*
map — map a ser ordenado. Map(K, V)

Valor retornado

Retorna um map parcialmente ordenado em ordem decrescente. Map(K, V)

Exemplos

Exemplo de uso

SELECT mapPartialReverseSort((k, v) -> v, 2, map('k1', 3, 'k2', 1, 'k3', 2))

{'k1':3,'k3':2,'k2':1}

mapPartialSort

Introduzido em: v23.4.0

Ordena os elementos de um map em ordem crescente, com um argumento adicional de limite que permite ordenação parcial. Se a função func for especificada, a ordem de classificação será determinada pelo resultado da função func aplicada às chaves e aos valores do map.

Sintaxe

mapPartialSort([func,] limit, map)

Argumentos

func — Opcional. Função lambda. Função lambda
limit — Os elementos no intervalo [1..limit] são ordenados. (U)Int*
map — map a ser ordenado. Map(K, V)

Valor retornado

Retorna um map parcialmente ordenado. Map(K, V)

Exemplos

Exemplo de uso

SELECT mapPartialSort((k, v) -> v, 2, map('k1', 3, 'k2', 1, 'k3', 2))

{'k2':1,'k3':2,'k1':3}

mapPopulateSeries

Introduzido em: v20.10.0

Preenche pares chave-valor ausentes em um map com chaves inteiras. Para permitir estender as chaves além do maior valor, é possível especificar uma chave máxima. Mais especificamente, a função retorna um map em que as chaves formam uma série da menor até a maior chave (ou o argumento max, se especificado), com passo 1, e seus valores correspondentes. Se nenhum valor for especificado para uma chave, um valor padrão será usado. Caso haja chaves repetidas, somente o primeiro valor (na ordem de aparição) será associado à chave.

Sintaxe

mapPopulateSeries(map[, max]) | mapPopulateSeries(keys, values[, max])

Argumentos

map — Map com chaves inteiras. Map((U)Int*, V)
keys — Array de chaves. Array(T)
values — Array de valores. Array(T)
max — Opcional. Valor máximo da chave. Int8 ou Int16 ou Int32 ou Int64 ou Int128 ou Int256

Valor retornado

Retorna um map ou uma tupla de dois arrays, em que o primeiro contém as chaves em ordem ordenada e o segundo contém os valores das chaves correspondentes. Map(K, V) ou Tuple(Array(UInt*), Array(Any))

Exemplos

Com o tipo Map

SELECT mapPopulateSeries(map(1, 10, 5, 20), 6)

{1:10,2:0,3:0,4:0,5:20,6:0}

Com arrays mapeados

SELECT mapPopulateSeries([1, 2, 4], [11, 22, 44], 5)

([1,2,3,4,5],[11,22,0,44,0])

mapReverseSort

Introduzido em: v23.4.0

Ordena os elementos de um map em ordem decrescente. Se a função func for especificada, a ordem de classificação será determinada pelo resultado da aplicação da função func às chaves e aos valores do map.

Sintaxe

mapReverseSort([func,] map)

Argumentos

func — Opcional. Função lambda. Função lambda
map — map a ser ordenado. Map(K, V)

Valor retornado

Retorna um map em ordem decrescente. Map(K, V)

Exemplos

Exemplo de uso

SELECT mapReverseSort((k, v) -> v, map('k1', 3, 'k2', 1, 'k3', 2))

{'k1':3,'k3':2,'k2':1}

mapSort

Introduzido em: v23.4.0

Ordena os elementos de um map em ordem crescente. Se a função func for especificada, a ordem de classificação será determinada pelo resultado da função func aplicada às chaves e aos valores do map.

Sintaxe

mapSort([func,] map)

Argumentos

func — Opcional. Função lambda. Função lambda
map — map a ser ordenado. Map(K, V)

Valor retornado

Retorna um map ordenado em ordem crescente. Map(K, V)

Exemplos

Exemplo de uso

SELECT mapSort((k, v) -> v, map('k1', 3, 'k2', 1, 'k3', 2))

{'k2':1,'k3':2,'k1':3}

mapSubtract

Introduzido em: v20.7.0

Coleta todas as chaves e subtrai os valores correspondentes.

Sintaxe

mapSubtract(arg1[, arg2, ...])

Argumentos

arg1[, arg2, ...] — maps ou tuplas de dois arrays, em que os itens do primeiro array representam as chaves, e o segundo array contém os valores de cada chave. Map(K, V) ou Tuple(Array(T), Array(T))

Valor retornado

Retorna um map ou uma tupla, em que o primeiro array contém as chaves ordenadas e o segundo array contém os valores. Map(K, V) ou Tuple(Array(T), Array(T))

Exemplos

Com o tipo Map

SELECT mapSubtract(map(1, 1), map(1, 1))

{1:0}

Com map de tuplas

SELECT mapSubtract(([toUInt8(1), 2], [toInt32(1), 1]), ([toUInt8(1), 2], [toInt32(2), 1]))

([1,2],[-1,0])

mapUpdate

Introduzido em: v22.3.0

Para dois maps, retorna o primeiro map com os valores atualizados com base nos valores das chaves correspondentes no segundo map.

Sintaxe

mapUpdate(map1, map2)

Argumentos

map1 — O map a ser atualizado. Map(K, V)
map2 — O map usado na atualização. Map(K, V)

Valor retornado

Retorna map1 com os valores atualizados com base nos valores das chaves correspondentes em map2. Map(K, V)

Exemplos

Uso básico

SELECT mapUpdate(map('key1', 0, 'key3', 0), map('key1', 10, 'key2', 10))

{'key3':0,'key1':10,'key2':10}

mapValues

Introduzida em: v21.2.0

Retorna os valores de um determinado map. Esta função pode ser otimizada ao ativar a configuração optimize_functions_to_subcolumns. Com a configuração ativada, a função lê apenas a subcoluna values, em vez do map inteiro. A consulta SELECT mapValues(m) FROM table é transformada em SELECT m.values FROM table.

Sintaxe

mapValues(map)

Argumentos

map — Map de onde extrair os valores. Map(K, V)

Valor retornado

Retorna um array contendo todos os valores do map. Array(T)

Exemplos

Exemplo de uso

SELECT mapValues(map('k1', 'v1', 'k2', 'v2'))

['v1','v2']