Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

Funções de codificação

bech32Decode

Introduzido em: v25.6.0

Decodifica uma string de endereço Bech32 gerada pelos algoritmos bech32 ou bech32m.

Sintaxe

bech32Decode(address[, 'raw'])

Argumentos

  • address — Uma string Bech32 a ser decodificada. String ou FixedString
  • mode — Opcional. Passe 'raw' para decodificar sem remover o primeiro byte como versão witness. Use essa opção para endereços não SegWit (por exemplo, Cosmos SDK). String

Valor retornado

Retorna uma tupla formada por (hrp, data) usada para codificar a string. Os dados estão em formato binário. Tuple(String, String)

Exemplos

Decodificar endereço

SELECT tup.1 AS hrp, hex(tup.2) AS data FROM (SELECT bech32Decode('bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4') AS tup)
┌─hrp─┬─data─────────────────────────────────────┐
│ bc  │ 751E76E8199196D454941C45D1B3A323F1433BD6 │
└─────┴──────────────────────────────────────────┘

Endereço da rede de teste

SELECT tup.1 AS hrp, hex(tup.2) AS data FROM (SELECT bech32Decode('tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx') AS tup)
┌─hrp─┬─data─────────────────────────────────────┐
│ tb  │ 751E76E8199196D454941C45D1B3A323F1433BD6 │
└─────┴──────────────────────────────────────────┘

bech32Encode

Introduzido em: v25.6.0

Codifica uma string de dados binários, juntamente com uma parte legível por humanos (HRP), usando os algoritmos Bech32 ou Bech32m.

Sintaxe

bech32Encode(hrp, data[, witver | 'bech32' | 'bech32m'])

Argumentos

  • hrp — Uma String de 1 - 83 caracteres minúsculos que especifica a "parte legível por humanos" do código. Geralmente 'bc' ou 'tb'. String ou FixedString
  • data — Uma String de dados binários para codificação. String ou FixedString
  • witver_or_variant — Opcional. Pode ser uma versão witness UInt* (padrão = 1, 0 para Bech32, 1+ para Bech32m) ou uma variante de codificação String: 'bech32' (BIP173) ou 'bech32m' (BIP350). Quando uma variante String é usada, nenhum byte de versão witness é prefixado — isso é necessário para endereços não SegWit, como os do Cosmos SDK. UInt* ou String

Valor retornado

Retorna uma string de endereço Bech32, composta pela parte legível por humanos, um caractere separador que é sempre '1' e uma parte de dados. O comprimento da string nunca excederá 90 caracteres. Se o algoritmo não conseguir gerar um endereço válido a partir da entrada, retornará uma string vazia. String

Exemplos

Bech32m padrão

-- When no witness version is supplied, the default is 1, the updated Bech32m algorithm.
SELECT bech32Encode('bc', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'))
bc1pw508d6qejxtdg4y5r3zarvary0c5xw7kj9wkru

Algoritmo Bech32

-- A witness version of 0 will result in a different address string.
SELECT bech32Encode('bc', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 0)
bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4

HRP personalizado

-- While 'bc' (Mainnet) and 'tb' (Testnet) are the only allowed hrp values for the
-- SegWit address format, Bech32 allows any hrp that satisfies the above requirements.
SELECT bech32Encode('abcdefg', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 10)
abcdefg12w508d6qejxtdg4y5r3zarvary0c5xw7kh526px

Endereço do Cosmos SDK (BIP173, sem versão witness)

-- Using 'bech32' variant encodes raw data without a witness version byte,
-- compatible with Cosmos SDK, Injective, Osmosis, and other non-SegWit chains.
SELECT bech32Encode('inj', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 'bech32')
inj1w508d6qejxtdg4y5r3zarvary0c5xw7ks5q7aq

bin

Introduzido em: v21.8.0

Retorna uma string contendo a representação binária do argumento, de acordo com a lógica a seguir para diferentes tipos:

Tipo Descrição
(U)Int* Exibe os dígitos binários do mais significativo para o menos significativo (ordem big-endian, ou "legível por humanos"). Começa com o byte não zero mais significativo (bytes zero à esquerda são omitidos), mas sempre exibe os oito dígitos de cada byte, mesmo que o dígito inicial seja zero.
Date and DateTime Formatados como os inteiros correspondentes (o número de dias desde a epoch para Date e o valor do Unix timestamp para DateTime).
String and FixedString Todos os bytes são simplesmente codificados como sequências de oito dígitos binários. Bytes zero não são omitidos.
Float* and Decimal Codificados conforme sua representação na memória. Como há suporte para arquitetura little-endian, eles são codificados em little-endian. Bytes zero à esquerda/à direita não são omitidos.
UUID Codificado como string em ordem big-endian.

Sintaxe

bin(arg)

Argumentos

Valor retornado

Retorna uma string com a representação binária do argumento. String

Exemplos

Inteiro simples

SELECT bin(14)
┌─bin(14)──┐
│ 00001110 │
└──────────┘

Números do tipo Float32

SELECT bin(toFloat32(number)) AS bin_presentation FROM numbers(15, 2)
┌─bin_presentation─────────────────┐
│ 00000000000000000111000001000001 │
│ 00000000000000001000000001000001 │
└──────────────────────────────────┘

Números Float64

SELECT bin(toFloat64(number)) AS bin_presentation FROM numbers(15, 2)
┌─bin_presentation─────────────────────────────────────────────────┐
│ 0000000000000000000000000000000000000000000000000010111001000000 │
│ 0000000000000000000000000000000000000000000000000011000001000000 │
└──────────────────────────────────────────────────────────────────┘

Conversão de UUID

SELECT bin(toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0')) AS bin_uuid
┌─bin_uuid─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 01100001111100001100010000000100010111001011001100010001111001111001000001111011101001100000000001101010110100111101101110100000 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

bitPositionsToArray

Introduzido em: v21.7.0

Esta função retorna as posições (em ordem crescente) dos bits definidos como 1 na representação binária de um inteiro sem sinal. Inteiros de entrada com sinal são primeiro convertidos em um inteiro sem sinal.

Sintaxe

bitPositionsToArray(arg)

Argumentos

  • arg — Um valor inteiro. (U)Int*

Valor retornado

Retorna um array com as posições, em ordem crescente, dos bits com valor 1 na representação binária do valor de entrada. Array(UInt64)

Exemplos

Um único bit ativado

SELECT bitPositionsToArray(toInt8(1)) AS bit_positions
┌─bit_positions─┐
│ [0]           │
└───────────────┘

Todos os bits ativados

SELECT bitPositionsToArray(toInt8(-1)) AS bit_positions
┌─bit_positions─────┐
│ [0,1,2,3,4,5,6,7] │
└───────────────────┘

bitmaskToArray

Introduzido em: v1.1.0

Esta função decompõe um inteiro em uma soma de potências de dois. As potências de dois são retornadas em um array ordenado em ordem crescente.

Sintaxe

bitmaskToArray(num)

Argumentos

  • num — Um valor inteiro. (U)Int*

Valor retornado

Retorna um array com as potências de dois em ordem crescente cuja soma corresponde ao número de entrada. Array(UInt64)

Exemplos

Exemplo básico

SELECT bitmaskToArray(50) AS powers_of_two
┌─powers_of_two─┐
│ [2,16,32]     │
└───────────────┘

Uma única potência de 2

SELECT bitmaskToArray(8) AS powers_of_two
┌─powers_of_two─┐
│ [8]           │
└───────────────┘

bitmaskToList

Introduzido em: v1.1.0

Semelhante a bitmaskToArray, mas retorna as potências de dois como uma string separada por vírgula.

Sintaxe

bitmaskToList(num)

Argumentos

  • num — Um valor inteiro. (U)Int*

Valor retornado

Retorna uma string com potências de dois separadas por vírgulas. String

Exemplos

Exemplo básico

SELECT bitmaskToList(50) AS powers_list
┌─powers_list─┐
│ 2,16,32     │
└─────────────┘

char

Introduzido em: v20.1.0

Retorna uma string com comprimento igual ao número de argumentos passados, em que cada byte tem o valor do argumento correspondente. Aceita vários argumentos de tipos numéricos.

Se o valor do argumento estiver fora do intervalo do tipo de dado UInt8, ele será convertido para UInt8, com possível arredondamento e estouro.

Sintaxe

char(num1[, num2[, ...]])

Argumentos

Valor retornado

Retorna uma string a partir dos bytes fornecidos. String

Exemplos

Exemplo básico

SELECT char(104.1, 101, 108.9, 108.9, 111) AS hello;
┌─hello─┐
│ hello │
└───────┘

Criando codificações arbitrárias

-- Você pode construir uma string de codificação arbitrária passando os bytes correspondentes.
-- por exemplo UTF8
SELECT char(0xD0, 0xBF, 0xD1, 0x80, 0xD0, 0xB8, 0xD0, 0xB2, 0xD0, 0xB5, 0xD1, 0x82) AS hello;
┌─hello──┐
│ привет │
└────────┘

hex

Introduzido em: v1.1.0

Retorna uma string contendo a representação hexadecimal do argumento de acordo com a lógica a seguir para diferentes tipos:

Tipo Descrição
(U)Int* Imprime dígitos hexadecimais ("nibbles") do mais significativo para o menos significativo (ordem big-endian ou "legível para humanos"). Começa com o byte não zero mais significativo (bytes zero à esquerda são omitidos), mas sempre imprime ambos os dígitos de cada byte, mesmo que o dígito à esquerda seja zero.
Date e DateTime Formatados como os inteiros correspondentes (o número de dias desde o epoch para Date e o valor do timestamp Unix para DateTime).
String e FixedString Todos os bytes são simplesmente codificados como dois números hexadecimais. Bytes zero não são omitidos.
Float* e Decimal Codificados conforme sua representação na memória. O ClickHouse sempre representa os valores internamente em little-endian, portanto eles são codificados dessa forma. Bytes zero à esquerda/à direita não são omitidos.
UUID Codificado como string em ordem big-endian.

A função usa letras maiúsculas A-F e não usa prefixos (como 0x) nem sufixos (como h).

Sintaxe

hex(arg)

Argumentos

Valor retornado

Retorna uma string contendo a representação hexadecimal do argumento. String

Exemplos

Inteiro simples

SELECT hex(1)
01

Números de ponto flutuante Float32

SELECT hex(toFloat32(number)) AS hex_presentation FROM numbers(15, 2)
┌─hex_presentation─┐
│ 00007041         │
│ 00008041         │
└──────────────────┘

Números Float64

SELECT hex(toFloat64(number)) AS hex_presentation FROM numbers(15, 2)
┌─hex_presentation─┐
│ 0000000000002E40 │
│ 0000000000003040 │
└──────────────────┘

Conversão de UUID

SELECT lower(hex(toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0'))) AS uuid_hex
┌─uuid_hex─────────────────────────┐
│ 61f0c4045cb311e7907ba6006ad3dba0 │
└──────────────────────────────────┘

hilbertDecode

Introduzido em: v24.6.0

Decodifica um índice da curva de Hilbert novamente em uma tupla de inteiros sem sinal, representando coordenadas em um espaço multidimensional.

Assim como a função hilbertEncode, esta função tem dois modos de operação:

  • Simples
  • Expandido

Modo simples

Aceita até 2 inteiros sem sinal como argumentos e gera um código UInt64.

Modo expandido

Aceita uma máscara de intervalo (tupla) como primeiro argumento e até 2 inteiros sem sinal como outros argumentos. Cada número na máscara configura o número de bits pelos quais o argumento correspondente será deslocado à esquerda, escalando efetivamente o argumento dentro do seu intervalo.

A expansão de intervalo pode ser útil quando você precisa de uma distribuição semelhante para argumentos com intervalos (ou cardinalidade) muito diferentes entre si. Por exemplo: 'endereço IP' (0...FFFFFFFF) e 'código do país' (0...FF). Assim como na função de codificação, isso é limitado a 8 números no máximo.

Sintaxe

hilbertDecode(tuple_size, code)

Argumentos

Valor retornado

Retorna uma tupla do tamanho especificado. Tuple(UInt64)

Exemplos

Modo simples

SELECT hilbertDecode(2, 31)
(3,4)

Argumento único

-- Hilbert code for one argument is always the argument itself (as a tuple).
SELECT hilbertDecode(1, 1)
(1)

Modo expandido

-- A single argument with a tuple specifying bit shifts will be right-shifted accordingly.
SELECT hilbertDecode(tuple(2), 32768)
(8192)

Uso de coluna

-- First create the table and insert some data
CREATE TABLE hilbert_numbers(
    n1 UInt32,
    n2 UInt32
)
ENGINE=MergeTree()
ORDER BY n1 SETTINGS index_granularity_bytes = '10Mi';
insert into hilbert_numbers (*) values(1,2);

-- Use column names instead of constants as function arguments
SELECT untuple(hilbertDecode(2, hilbertEncode(n1, n2))) FROM hilbert_numbers;
1	2

hilbertEncode

Introduzido em: v24.6.0

Calcula o código da Curva de Hilbert para uma lista de inteiros sem sinal.

A função tem dois modos de operação:

  • Simples
  • Expandido

Modo simples

Aceita até 2 inteiros sem sinal como argumentos e gera um código UInt64.

Modo expandido

Aceita uma máscara de intervalo (tupla) como primeiro argumento e até 2 inteiros sem sinal como argumentos adicionais.

Cada número na máscara configura o número de bits em que o argumento correspondente será deslocado para a esquerda, escalando efetivamente o argumento dentro do seu intervalo.

Sintaxe

-- Modo simplificado
hilbertEncode(args)

-- Modo expandido
hilbertEncode(range_mask, args)

Argumentos

  • args — Até dois valores UInt ou colunas do tipo UInt. UInt8/16/32/64
  • range_mask — No modo expandido, até dois valores UInt ou colunas do tipo UInt. UInt8/16/32/64

Valor retornado

Retorna um código UInt64. UInt64

Exemplos

Modo simples

SELECT hilbertEncode(3, 4)
31

Modo expandido

-- A expansão de intervalo pode ser útil quando você precisa de uma distribuição semelhante para
-- argumentos com intervalos (ou cardinalidade) muito diferentes.
-- Por exemplo: 'Endereço IP' (0...FFFFFFFF) e 'Código de país' (0...FF).
-- Nota: o tamanho da tupla deve ser igual ao número dos demais argumentos.
SELECT hilbertEncode((10, 6), 1024, 16)
4031541586602

Argumento único

-- Para um único argumento sem uma tupla, a função retorna o próprio argumento
-- como o índice de Hilbert, já que nenhum mapeamento dimensional é necessário.
SELECT hilbertEncode(1)
1

Argumento único expandido

-- Se um único argumento for fornecido com uma tupla especificando deslocamentos de bits, a função
-- desloca o argumento para a esquerda pelo número de bits especificado.
SELECT hilbertEncode(tuple(2), 128)
512

Uso de coluna

-- Primeiro crie a tabela e insira alguns dados
CREATE TABLE hilbert_numbers(
    n1 UInt32,
    n2 UInt32
)
ENGINE=MergeTree()
ORDER BY n1;
insert into hilbert_numbers (*) values(1, 2);

-- Use nomes de colunas em vez de constantes como argumentos da função
SELECT hilbertEncode(n1, n2) FROM hilbert_numbers;
13

mortonDecode

Introduzido em: v24.6.0

Decodifica uma codificação Morton (ZCurve) na tupla correspondente de inteiros sem sinal.

Assim como a função mortonEncode, esta função tem dois modos de operação:

  • Simples
  • Expandido

Modo simples

Aceita o tamanho da tupla resultante como primeiro argumento e o código como segundo argumento.

Modo expandido

Aceita uma máscara de intervalo (tupla) como primeiro argumento e o código como segundo argumento. Cada número na máscara configura o grau de redução do intervalo:

  • 1 - sem redução
  • 2 - redução de 2x
  • 3 - redução de 3x ⋮
  • Até 8x de redução.

A expansão do intervalo pode ser útil quando você precisa de uma distribuição semelhante para argumentos com intervalos muito diferentes (ou cardinalidade). Por exemplo: 'Endereço IP' (0...FFFFFFFF) e 'Código do país' (0...FF). Assim como na função de codificação, isso é limitado a no máximo 8 números.

Sintaxe

-- Simple mode
mortonDecode(tuple_size, code)

-- Expanded mode
mortonDecode(range_mask, code)

Argumentos

  • tuple_size — Valor inteiro de no máximo 8. UInt8/16/32/64
  • range_mask — No modo expandido, a máscara para cada argumento. A máscara é uma tupla de inteiros sem sinal. Cada número na máscara configura o grau de redução do intervalo. Tuple(UInt8/16/32/64)
  • code — Código UInt64. UInt64

Valor retornado

Retorna uma tupla do tamanho especificado. Tuple(UInt64)

Exemplos

Modo simples

SELECT mortonDecode(3, 53)
(1,2,3)

Argumento único

SELECT mortonDecode(1, 1)
(1)

Modo expandido, com redução de um argumento

SELECT mortonDecode(tuple(2), 32768)
(128)

Uso da coluna

-- First create the table and insert some data
CREATE TABLE morton_numbers(
    n1 UInt32,
    n2 UInt32,
    n3 UInt16,
    n4 UInt16,
    n5 UInt8,
    n6 UInt8,
    n7 UInt8,
    n8 UInt8
)
ENGINE=MergeTree()
ORDER BY n1;
INSERT INTO morton_numbers (*) values(1, 2, 3, 4, 5, 6, 7, 8);

-- Use column names instead of constants as function arguments
SELECT untuple(mortonDecode(8, mortonEncode(n1, n2, n3, n4, n5, n6, n7, n8))) FROM morton_numbers;
1	2	3	4	5	6	7	8

mortonEncode

Introduzido em: v24.6.0

Calcula a codificação Morton (ZCurve) para uma lista de inteiros sem sinal.

A função tem dois modos de operação:

  • Simples
  • Expandido*

Modo simples

Aceita até 8 inteiros sem sinal como argumentos e gera um código UInt64.

Modo expandido

Aceita uma máscara de intervalo (tupla) como primeiro argumento e até 8 inteiros sem sinal nos demais argumentos.

Cada número na máscara configura o fator de expansão do intervalo:

  • 1 - sem expansão
  • 2 - expansão de 2x
  • 3 - expansão de 3x ⋮
  • Até 8x de expansão.

Sintaxe

-- Modo simplificado
mortonEncode(args)

-- Modo expandido
mortonEncode(range_mask, args)

Argumentos

  • args — Até 8 inteiros sem sinal ou colunas do tipo mencionado acima. UInt8/16/32/64
  • range_mask — No modo expandido, a máscara de cada argumento. A máscara é uma tupla de inteiros sem sinal de 1 a 8. Cada número na máscara configura o grau de redução do intervalo. Tuple(UInt8/16/32/64)

Valor retornado

Retorna um código UInt64. UInt64

Exemplos

Modo simples

SELECT mortonEncode(1, 2, 3)
53

Modo expandido

-- A expansão de intervalo pode ser útil quando você precisa de uma distribuição semelhante para
-- argumentos com intervalos (ou cardinalidade) muito diferentes
-- Por exemplo: 'Endereço IP' (0...FFFFFFFF) e 'Código de país' (0...FF).
-- Nota: o tamanho da tupla deve ser igual ao número dos demais argumentos.
SELECT mortonEncode((1,2), 1024, 16)
1572864

Argumento único

-- A codificação Morton para um argumento é sempre o próprio argumento
SELECT mortonEncode(1)
1

Argumento único expandido

SELECT mortonEncode(tuple(2), 128)
32768

Uso da coluna

-- Primeiro, crie a tabela e insira alguns dados
CREATE TABLE morton_numbers(
    n1 UInt32,
    n2 UInt32,
    n3 UInt16,
    n4 UInt16,
    n5 UInt8,
    n6 UInt8,
    n7 UInt8,
    n8 UInt8
)
ENGINE=MergeTree()
ORDER BY n1;
INSERT INTO morton_numbers (*) values(1, 2, 3, 4, 5, 6, 7, 8);

-- Use nomes de colunas em vez de constantes como argumentos da função
SELECT mortonEncode(n1, n2, n3, n4, n5, n6, n7, n8) FROM morton_numbers;
2155374165

sqidDecode

Introduzido em: v24.1.0

Transforma um sqid novamente em um array de números.

Sintaxe

sqidDecode(sqid)

Argumentos

  • sqid — O sqid a ser decodificado. String

Valor retornado

Retorna um array de números a partir de sqid. Array(UInt64)

Exemplos

Exemplo de uso

SELECT sqidDecode('gXHfJ1C6dN');
┌─sqidDecode('gXHfJ1C6dN')─┐
│ [1,2,3,4,5]              │
└──────────────────────────┘

sqidEncode

Introduzido em: v24.1.0

Transforma números em um sqid, uma sequência de caracteres de ID semelhante à do YouTube.

Sintaxe

sqidEncode(n1[, n2, ...])

Aliases: sqid

Argumentos

  • n1[, n2, ...] — Quantos números forem necessários. UInt8/16/32/64

Valor retornado

Retorna um ID de hash String

Exemplos

Exemplo de uso

SELECT sqidEncode(1, 2, 3, 4, 5);
┌─sqidEncode(1, 2, 3, 4, 5)─┐
│ gXHfJ1C6dN                │
└───────────────────────────┘

unbin

Introduzido em: v21.8.0

Interpreta cada par de dígitos binários (no argumento) como um número e o converte no byte representado por esse número. A função executa a operação oposta à de bin.

Para um argumento numérico, unbin() não retorna o inverso de bin(). Se você quiser converter o resultado em um número, pode usar as funções reverse e reinterpretAs<Type>.

Aceita os dígitos binários 0 e 1. A quantidade de dígitos binários não precisa ser múltipla de oito. Se a string do argumento contiver qualquer coisa além de dígitos binários, o resultado será indefinido (nenhuma exceção é lançada).

Sintaxe

unbin(arg)

Argumentos

  • arg — Uma string que contém qualquer número de dígitos binários. String

Valor retornado

Retorna uma string binária (BLOB). String

Exemplos

Uso básico

SELECT UNBIN('001100000011000100110010'), UNBIN('0100110101111001010100110101000101001100')
┌─UNBIN('001100000011000100110010')─┬─UNBIN('0100110101111001010100110101000101001100')─┐
│ 012                               │ MySQL                                             │
└───────────────────────────────────┴───────────────────────────────────────────────────┘

Converter para número

SELECT reinterpretAsUInt64(reverse(unbin('1110'))) AS num
┌─num─┐
│  14 │
└─────┘

unhex

Introduzido em: v1.1.0

Executa a operação inversa de hex. Interpreta cada par de dígitos hexadecimais (no argumento) como um número e o converte no byte representado por esse número. O valor retornado é uma string binária (BLOB).

Se você quiser converter o resultado em um número, pode usar as funções reverse e reinterpretAs<Type>.

Aceita letras A-F, tanto maiúsculas quanto minúsculas. A quantidade de dígitos hexadecimais não precisa ser par. Se for ímpar, o último dígito é interpretado como a metade menos significativa do byte 00-0F. Se a string do argumento contiver qualquer caractere que não seja um dígito hexadecimal, algum resultado definido pela implementação será retornado (nenhuma exceção é lançada). Para um argumento numérico, unhex() não executa o inverso de hex(N).

Sintaxe

unhex(arg)

Argumentos

  • arg — Uma sequência de caracteres contendo qualquer quantidade de dígitos hexadecimais. String ou FixedString

Valor retornado

Retorna uma string binária (BLOB). String

Exemplos

Uso básico

SELECT unhex('303132'), UNHEX('4D7953514C')
┌─unhex('303132')─┬─UNHEX('4D7953514C')─┐
│ 012             │ MySQL               │
└─────────────────┴─────────────────────┘

Converter para número

SELECT reinterpretAsUInt64(reverse(unhex('FFF'))) AS num
┌──num─┐
│ 4095 │
└──────┘
Navigation