> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentação das funções de tuple e map

# Funções de map

{/*AUTOGENERATED_START*/}

<div id="extractKeyValuePairs">
  ## extractKeyValuePairs
</div>

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**

```sql theme={null}
extractKeyValuePairs(data, [key_value_delimiter], [pair_delimiter], [quoting_character])
```

**Argumentos**

* `data` - String da qual serão extraídos pares chave-valor. [String](/pt-BR/reference/data-types/string) ou [FixedString](/pt-BR/reference/data-types/fixedstring).
  * `key_value_delimiter` - Caractere a ser usado como delimitador entre a chave e o valor. O padrão é `:`. [String](/pt-BR/reference/data-types/string) ou [FixedString](/pt-BR/reference/data-types/fixedstring).
  * `pair_delimiters` - Conjunto de caracteres a ser usado como delimitadores entre pares. O padrão é `\space`, `,` e `;`. [String](/pt-BR/reference/data-types/string) ou [FixedString](/pt-BR/reference/data-types/fixedstring).
  * `quoting_character` - Caractere a ser usado para delimitar aspas. O padrão é `"`. [String](/pt-BR/reference/data-types/string) ou [FixedString](/pt-BR/reference/data-types/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 é `INVALID`

**Valores retornados**

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

**Exemplos**

Consulta:

**Caso simples**

```sql theme={null}
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

            ┌─kv──────────────────────────────────────────────────────────────────────┐
            │ {'name':'neymar','age':'31','team':'psg','nationality':'brazil'}        │
            └─────────────────────────────────────────────────────────────────────────┘
```

**Aspas simples como caractere de aspas**

```sql theme={null}
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

            ┌─kv───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
            │ {'name':'neymar','age':'31','team':'psg','nationality':'brazil','last_key':'last_value'}                                 │
            └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

exemplos de unexpected\_quoting\_character\_strategy:

unexpected\_quoting\_character\_strategy=invalid

```sql theme={null}
SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'INVALID') as kv;
```

```text theme={null}
┌─kv────────────────┐
            │ {'abc':'5'}  │
            └───────────────────┘
```

```sql theme={null}
SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'INVALID') as kv;
```

```text theme={null}
┌─kv──┐
            │ {}  │
            └─────┘
```

unexpected\_quoting\_character\_strategy=accept

```sql theme={null}
SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'ACCEPT') as kv;
```

```text theme={null}
┌─kv────────────────┐
            │ {'name"abc':'5'}  │
            └───────────────────┘
```

```sql theme={null}
            SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'ACCEPT') as kv;
```

```text theme={null}
            ┌─kv─────────────────┐
            │ {'name"abc"':'5'}  │
            └────────────────────┘
```

unexpected\_quoting\_character\_strategy=promote

```sql theme={null}
            SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'PROMOTE') as kv;
```

```text theme={null}
            ┌─kv──┐
            │ {}  │
            └─────┘
```

```sql theme={null}
            SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'PROMOTE') as kv;
```

```text theme={null}
            ┌─kv───────────┐
            │ {'abc':'5'}  │
            └──────────────┘
```

**Sequências de escape sem suporte a escapes**

```sql theme={null}
            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

            ┌─kv────────────────────┐
            │ {'age':'a\\x0A\\n\\0'} │
            └───────────────────────┘
```

**Sintaxe**

```sql theme={null}
extractKeyValuePairs(input)
```

**Aliases**: `str_to_map`, `mapFromString`

**Argumentos**

* Nenhum.

**Valor retornado**

**Exemplos**

<div id="extractKeyValuePairsWithEscaping">
  ## extractKeyValuePairsWithEscaping
</div>

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**

```sql theme={null}
            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

            ┌─kv───────────────┐
            │ {'age':'a\n\n\0'} │
            └──────────────────┘
```

**Sintaxe**

```sql theme={null}
extractKeyValuePairsWithEscaping(input)
```

**Argumentos**

* Nenhum.

**Valor retornado**

**Exemplos**

<div id="map">
  ## map
</div>

Introduzido em: v21.1.0

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

**Sintaxe**

```sql theme={null}
map(key1, value1[, key2, value2, ...])
```

**Argumentos**

* `key_n` — As chaves das entradas do map. [`Any`](/pt-BR/reference/data-types/index)
* `value_n` — Os valores das entradas do map. [`Any`](/pt-BR/reference/data-types/index)

**Valor retornado**

Retorna um map que contém pares chave:valor. [`Map(Any, Any)`](/pt-BR/reference/data-types/map)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT map('key1', number, 'key2', number * 2) FROM numbers(3)
```

```response title=Response theme={null}
{'key1':0,'key2':0}
{'key1':1,'key2':2}
{'key1':2,'key2':4}
```

<div id="mapAdd">
  ## mapAdd
</div>

Introduzido em: v20.7.0

Coleta todas as chaves e soma os valores correspondentes.

**Sintaxe**

```sql theme={null}
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)`](/pt-BR/reference/data-types/map) ou [`Tuple(Array(T), Array(T))`](/pt-BR/reference/data-types/tuple)

**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)`](/pt-BR/reference/data-types/map) ou [`Tuple(Array(T), Array(T))`](/pt-BR/reference/data-types/tuple)

**Exemplos**

**Com o tipo Map**

```sql title=Query theme={null}
SELECT mapAdd(map(1, 1), map(1, 1))
```

```response title=Response theme={null}
{1:2}
```

**Com tupla**

```sql title=Query theme={null}
SELECT mapAdd(([toUInt8(1), 2], [1, 1]), ([toUInt8(1), 2], [1, 1]))
```

```response title=Response theme={null}
([1, 2], [2, 2])
```

<div id="mapAll">
  ## mapAll
</div>

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**

```sql theme={null}
mapAll([func,] map)
```

**Argumentos**

* `func` — Função lambda. [`Função lambda`](/pt-BR/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — map a ser verificado. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Valor retornado**

Retorna `1` se todos os pares chave-valor satisfizerem a condição, `0` caso contrário. [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapAll((k, v) -> v = 1, map('k1', 1, 'k2', 2))
```

```response title=Response theme={null}
0
```

<div id="mapApply">
  ## mapApply
</div>

Introduzido em: v22.3.0

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

**Sintaxe**

```sql theme={null}
mapApply(func, map)
```

**Argumentos**

* `func` — Função lambda. [`Função lambda`](/pt-BR/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — map ao qual a função será aplicada. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Valor retornado**

Retorna um novo map obtido a partir do map original pela aplicação de `func` a cada elemento. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapApply((k, v) -> (k, v * 2), map('k1', 1, 'k2', 2))
```

```response title=Response theme={null}
{'k1':2,'k2':4}
```

<div id="mapConcat">
  ## mapConcat
</div>

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**

```sql theme={null}
mapConcat(maps)
```

**Argumentos**

* `maps` — Uma quantidade arbitrária de maps. [`Map`](/pt-BR/reference/data-types/map)

**Valor retornado**

Retorna um map com a concatenação dos maps passados como argumentos. [`Map`](/pt-BR/reference/data-types/map)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapConcat(map('k1', 'v1'), map('k2', 'v2'))
```

```response title=Response theme={null}
{'k1':'v1','k2':'v2'}
```

<div id="mapContainsKey">
  ## mapContainsKey
</div>

Introduzido em: v21.2.0

Determina se uma chave está contida em um map.

**Sintaxe**

```sql theme={null}
mapContainsKey(map, key)
```

**Aliases**: `mapContains`

**Argumentos**

* `map` — map em que pesquisar. [`Map(K, V)`](/pt-BR/reference/data-types/map)
* `key` — chave a ser pesquisada. O tipo deve corresponder ao tipo da chave do map. [`Any`](/pt-BR/reference/data-types/index)

**Valor retornado**

Retorna 1 se o map contiver a chave, 0 caso contrário. [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapContainsKey(map('k1', 'v1', 'k2', 'v2'), 'k1')
```

```response title=Response theme={null}
1
```

<div id="mapContainsKeyLike">
  ## mapContainsKeyLike
</div>

Introduzido em: v23.4.0

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

**Sintaxe**

```sql theme={null}
mapContainsKeyLike(map, pattern)
```

**Argumentos**

* `map` — map onde pesquisar. [`Map(K, V)`](/pt-BR/reference/data-types/map)
* `pattern` — Padrão para correspondência das chaves. [`const String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna `1` se `map` contiver uma chave que corresponda a `pattern`; caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─mapContainsKeyLike(a, 'a%')─┐
│                           1 │
│                           0 │
└─────────────────────────────┘
```

<div id="mapContainsValue">
  ## mapContainsValue
</div>

Introduzido em: v25.6.0

Determina se um valor está presente em um map.

**Sintaxe**

```sql theme={null}
mapContainsValue(map, value)
```

**Argumentos**

* `map` — map em que a busca será realizada. [`Map(K, V)`](/pt-BR/reference/data-types/map)
* `value` — Valor a ser buscado. O tipo deve corresponder ao tipo de valor do map. [`Any`](/pt-BR/reference/data-types/index)

**Valor retornado**

Retorna `1` se o map contiver o valor e `0` caso contrário. [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapContainsValue(map('k1', 'v1', 'k2', 'v2'), 'v1')
```

```response title=Response theme={null}
1
```

<div id="mapContainsValueLike">
  ## mapContainsValueLike
</div>

Introduzido em: v25.5.0

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

**Sintaxe**

```sql theme={null}
mapContainsValueLike(map, pattern)
```

**Argumentos**

* `map` — map em que será feita a busca. [`Map(K, V)`](/pt-BR/reference/data-types/map)
* `pattern` — Padrão usado para corresponder aos valores. [`const String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna `1` se `map` contiver um valor que corresponda a `pattern`, `0` caso contrário. [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─mapContainsV⋯ke(a, 'a%')─┐
│                        1 │
│                        0 │
└──────────────────────────┘
```

<div id="mapExists">
  ## mapExists
</div>

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**

```sql theme={null}
mapExists([func,] map)
```

**Argumentos**

* `func` — Opcional. Função lambda. [`Função lambda`](/pt-BR/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — map a ser verificado. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Valor retornado**

Retorna `1` se pelo menos um par chave-valor atender à condição, `0` caso contrário. [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapExists((k, v) -> v = 1, map('k1', 1, 'k2', 2))
```

```response title=Response theme={null}
1
```

<div id="mapExtractKeyLike">
  ## mapExtractKeyLike
</div>

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**

```sql theme={null}
mapExtractKeyLike(map, pattern)
```

**Argumentos**

* `map` — map do qual extrair. [`Map(K, V)`](/pt-BR/reference/data-types/map)
* `pattern` — padrão com o qual comparar as chaves. [`const String`](/pt-BR/reference/data-types/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)`](/pt-BR/reference/data-types/map)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─mapExtractKeyLike(a, 'a%')─┐
│ {'abc':'abc'}              │
│ {}                         │
└────────────────────────────┘
```

<div id="mapExtractValueLike">
  ## mapExtractValueLike
</div>

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**

```sql theme={null}
mapExtractValueLike(map, pattern)
```

**Argumentos**

* `map` — Map do qual extrair. [`Map(K, V)`](/pt-BR/reference/data-types/map)
* `pattern` — Padrão com o qual os valores são comparados. [`const String`](/pt-BR/reference/data-types/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)`](/pt-BR/reference/data-types/map)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─mapExtractValueLike(a, 'a%')─┐
│ {'abc':'abc'}                │
│ {}                           │
└──────────────────────────────┘
```

<div id="mapFilter">
  ## mapFilter
</div>

Introduzido em: v22.3.0

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

**Sintaxe**

```sql theme={null}
mapFilter(func, map)
```

**Argumentos**

* `func` — Função lambda. [`Função lambda`](/pt-BR/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — map a ser filtrado. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Valor retornado**

Retorna um map que contém apenas os elementos para os quais `func` retorna um valor diferente de `0`. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapFilter((k, v) -> v > 1, map('k1', 1, 'k2', 2))
```

```response title=Response theme={null}
{'k2':2}
```

<div id="mapFromArrays">
  ## mapFromArrays
</div>

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**

```sql theme={null}
mapFromArrays(keys, values)
```

**Aliases**: `MAP_FROM_ARRAYS`

**Argumentos**

* `keys` — Array ou map de chaves a partir do qual criar o map. [`Array`](/pt-BR/reference/data-types/array) ou [`Map`](/pt-BR/reference/data-types/map)
* `values` — Array ou map de valores a partir do qual criar o map. [`Array`](/pt-BR/reference/data-types/array) ou [`Map`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/map)

**Exemplos**

**Uso básico**

```sql title=Query theme={null}
SELECT mapFromArrays(['a', 'b', 'c'], [1, 2, 3])
```

```response title=Response theme={null}
{'a':1,'b':2,'c':3}
```

**Com entradas do tipo map**

```sql title=Query theme={null}
SELECT mapFromArrays([1, 2, 3], map('a', 1, 'b', 2, 'c', 3))
```

```response title=Response theme={null}
{1:('a', 1), 2:('b', 2), 3:('c', 3)}
```

<div id="mapKeys">
  ## mapKeys
</div>

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`](/pt-BR/reference/settings/session-settings#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**

```sql theme={null}
mapKeys(map)
```

**Argumentos**

* `map` — map do qual as chaves serão extraídas. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Valor retornado**

Retorna um array com todas as chaves do mapa. [`Array(T)`](/pt-BR/reference/data-types/array)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapKeys(map('k1', 'v1', 'k2', 'v2'))
```

```response title=Response theme={null}
['k1','k2']
```

<div id="mapPartialReverseSort">
  ## mapPartialReverseSort
</div>

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**

```sql theme={null}
mapPartialReverseSort([func,] limit, map)
```

**Argumentos**

* `func` — Opcional. Função lambda. [`Função lambda`](/pt-BR/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `limit` — Os elementos no intervalo `[1..limit]` são ordenados. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
* `map` — map a ser ordenado. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Valor retornado**

Retorna um map parcialmente ordenado em ordem decrescente. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapPartialReverseSort((k, v) -> v, 2, map('k1', 3, 'k2', 1, 'k3', 2))
```

```response title=Response theme={null}
{'k1':3,'k3':2,'k2':1}
```

<div id="mapPartialSort">
  ## mapPartialSort
</div>

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**

```sql theme={null}
mapPartialSort([func,] limit, map)
```

**Argumentos**

* `func` — Opcional. Função lambda. [`Função lambda`](/pt-BR/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `limit` — Os elementos no intervalo `[1..limit]` são ordenados. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
* `map` — map a ser ordenado. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Valor retornado**

Retorna um map parcialmente ordenado. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapPartialSort((k, v) -> v, 2, map('k1', 3, 'k2', 1, 'k3', 2))
```

```response title=Response theme={null}
{'k2':1,'k3':2,'k1':3}
```

<div id="mapPopulateSeries">
  ## mapPopulateSeries
</div>

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**

```sql theme={null}
mapPopulateSeries(map[, max]) | mapPopulateSeries(keys, values[, max])
```

**Argumentos**

* `map` — Map com chaves inteiras. [`Map((U)Int*, V)`](/pt-BR/reference/data-types/map)
* `keys` — Array de chaves. [`Array(T)`](/pt-BR/reference/data-types/array)
* `values` — Array de valores. [`Array(T)`](/pt-BR/reference/data-types/array)
* `max` — Opcional. Valor máximo da chave. [`Int8`](/pt-BR/reference/data-types/int-uint) ou [`Int16`](/pt-BR/reference/data-types/int-uint) ou [`Int32`](/pt-BR/reference/data-types/int-uint) ou [`Int64`](/pt-BR/reference/data-types/int-uint) ou [`Int128`](/pt-BR/reference/data-types/int-uint) ou [`Int256`](/pt-BR/reference/data-types/int-uint)

**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)`](/pt-BR/reference/data-types/map) ou [`Tuple(Array(UInt*), Array(Any))`](/pt-BR/reference/data-types/tuple)

**Exemplos**

**Com o tipo Map**

```sql title=Query theme={null}
SELECT mapPopulateSeries(map(1, 10, 5, 20), 6)
```

```response title=Response theme={null}
{1:10, 2:0, 3:0, 4:0, 5:20, 6:0}
```

**Com arrays mapeados**

```sql title=Query theme={null}
SELECT mapPopulateSeries([1, 2, 4], [11, 22, 44], 5)
```

```response title=Response theme={null}
([1, 2, 3, 4, 5], [11, 22, 0, 44, 0])
```

<div id="mapReverseSort">
  ## mapReverseSort
</div>

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**

```sql theme={null}
mapReverseSort([func,] map)
```

**Argumentos**

* `func` — Opcional. Função lambda. [`Função lambda`](/pt-BR/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — map a ser ordenado. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Valor retornado**

Retorna um map em ordem decrescente. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapReverseSort((k, v) -> v, map('k1', 3, 'k2', 1, 'k3', 2))
```

```response title=Response theme={null}
{'k1':3,'k3':2,'k2':1}
```

<div id="mapSort">
  ## mapSort
</div>

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**

```sql theme={null}
mapSort([func,] map)
```

**Argumentos**

* `func` — Opcional. Função lambda. [`Função lambda`](/pt-BR/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — map a ser ordenado. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Valor retornado**

Retorna um map ordenado em ordem crescente. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapSort((k, v) -> v, map('k1', 3, 'k2', 1, 'k3', 2))
```

```response title=Response theme={null}
{'k2':1,'k3':2,'k1':3}
```

<div id="mapSubtract">
  ## mapSubtract
</div>

Introduzido em: v20.7.0

Coleta todas as chaves e subtrai os valores correspondentes.

**Sintaxe**

```sql theme={null}
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)`](/pt-BR/reference/data-types/map) ou [`Tuple(Array(T), Array(T))`](/pt-BR/reference/data-types/tuple)

**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)`](/pt-BR/reference/data-types/map) ou [`Tuple(Array(T), Array(T))`](/pt-BR/reference/data-types/tuple)

**Exemplos**

**Com o tipo Map**

```sql title=Query theme={null}
SELECT mapSubtract(map(1, 1), map(1, 1))
```

```response title=Response theme={null}
{1:0}
```

**Com map de tuplas**

```sql title=Query theme={null}
SELECT mapSubtract(([toUInt8(1), 2], [toInt32(1), 1]), ([toUInt8(1), 2], [toInt32(2), 1]))
```

```response title=Response theme={null}
([1, 2], [-1, 0])
```

<div id="mapUpdate">
  ## mapUpdate
</div>

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**

```sql theme={null}
mapUpdate(map1, map2)
```

**Argumentos**

* `map1` — O map a ser atualizado. [`Map(K, V)`](/pt-BR/reference/data-types/map)
* `map2` — O map usado na atualização. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Valor retornado**

Retorna `map1` com os valores atualizados com base nos valores das chaves correspondentes em `map2`. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Exemplos**

**Uso básico**

```sql title=Query theme={null}
SELECT mapUpdate(map('key1', 0, 'key3', 0), map('key1', 10, 'key2', 10))
```

```response title=Response theme={null}
{'key3':0,'key1':10,'key2':10}
```

<div id="mapValues">
  ## mapValues
</div>

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`](/pt-BR/reference/settings/session-settings#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**

```sql theme={null}
mapValues(map)
```

**Argumentos**

* `map` — Map de onde extrair os valores. [`Map(K, V)`](/pt-BR/reference/data-types/map)

**Valor retornado**

Retorna um array contendo todos os valores do `map`. [`Array(T)`](/pt-BR/reference/data-types/array)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT mapValues(map('k1', 'v1', 'k2', 'v2'))
```

```response title=Response theme={null}
['v1','v2']
```