メインコンテンツへスキップ
メインコンテンツへスキップ

エンコード関数

bech32Decode

導入されたバージョン: v25.6.0

bech32 または bech32m アルゴリズムによって生成された Bech32 アドレス文字列をデコードします。

注記

エンコード関数とは異なり、bech32Decode はパディング済みの FixedString を自動的に処理します。

構文

bech32Decode(address[, 'raw'])

引数

  • address — デコード対象の Bech32 文字列。String または FixedString
  • mode — オプション。先頭バイトを witness version として取り除かずにデコードするには 'raw' を渡します。非 SegWit アドレス (例: Cosmos SDK) の場合はこれを使用します。String

戻り値

文字列のエンコードに使用された (hrp, data) から成るタプルを返します。data はバイナリ形式のデータです。Tuple(String, String)

アドレスのデコード

SELECT tup.1 AS hrp, hex(tup.2) AS data FROM (SELECT bech32Decode('bc1w508d6qejxtdg4y5r3zarvary0c5xw7kj7gz7z') AS tup)
bc   751E76E8199196D454941C45D1B3A323F1433BD6

テストネット用アドレス

SELECT tup.1 AS hrp, hex(tup.2) AS data FROM (SELECT bech32Decode('tb1w508d6qejxtdg4y5r3zarvary0c5xw7kzp034v') AS tup)
tb   751E76E8199196D454941C45D1B3A323F1433BD6

bech32Encode

導入バージョン: v25.6.0

バイナリデータ文字列と、human-readable part (HRP) を Bech32 または Bech32m アルゴリズムでエンコードします。

注記

FixedString データ型を使用する場合、値が行を完全に埋めないときはヌル文字でパディングされます。 bech32Encode 関数は hrp 引数についてはこれを自動的に処理しますが、data 引数については値がパディングされていてはなりません。 このため、すべての値が同一の長さであることが確実であり、FixedString カラムもその長さに設定されていることを保証できる場合を除き、 データ値に FixedString データ型を使用することは推奨されません。

構文

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

引数

  • hrp — コードの「human-readable part」を指定する、1 - 83 文字の小文字英字から成る文字列。通常は 'bc' または 'tb'。String または FixedString
  • data — エンコード対象のバイナリデータを表す文字列。String または FixedString
  • witver_or_variant — 任意。UInt* の witness version (デフォルト = 1、Bech32 の場合は 0、Bech32m の場合は 1 以上) または String のエンコーディング variant のいずれかを指定します: 'bech32' (BIP173) または 'bech32m' (BIP350)。文字列の variant を使用する場合、witness version バイトは前置されません。これは Cosmos SDK などの非 SegWit アドレスで必要です。UInt* または String

戻り値

human-readable part、常に '1' となるセパレータ文字、およびデータ部から成る Bech32 アドレス文字列を返します。文字列の長さは 90 文字を超えることはありません。入力から有効なアドレスを生成できない場合は、空文字列を返します。String

使用例

デフォルトの Bech32m

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

Bech32 アルゴリズム

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

カスタム HRP

-- 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)
abcdefg1w508d6qejxtdg4y5r3zarvary0c5xw7k9rp8r4

Cosmos SDK アドレス (BIP173、witness version を含まない)

-- 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')
inj1w508d6qejxtdg4y5r3zarvary0c5xw7kgj5aqs

bin

導入バージョン: v21.8.0

引数の値をバイナリ表現に変換した文字列を、型ごとに次のロジックに従って返します:

TypeDescription
(U)Int*最上位ビットから最下位ビットへの順序 (ビッグエンディアン、いわゆる「人間が読みやすい」順序) でビット列を出力します。先頭のゼロバイトは省略され、最初に出現する非ゼロバイトから始まりますが、各バイトについては先頭ビットがゼロであっても必ず 8 ビット (8 桁) を出力します。
Date and DateTime対応する整数としてフォーマットされます (Date はエポックからの日数、DateTime は UNIX タイムスタンプの値) 。
String and FixedStringすべてのバイトが、各バイトあたり 8 ビット (8 桁) の2進数としてそのままエンコードされます。ゼロバイトも省略されません。
Float* and Decimalメモリ上の表現のままエンコードされます。little-endian アーキテクチャをサポートしているため、little-endian でエンコードされます。先頭および末尾のゼロバイトも省略されません。
UUIDビッグエンディアン順の文字列としてエンコードされます。

構文

bin(arg)

引数

戻り値

引数の2進表現を表す文字列を返します。String

単純な整数

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

Float32 数値

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

Float64 数値

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

UUID 変換

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

bitPositionsToArray

導入バージョン: v21.7.0

この関数は、符号なし整数の2進数表現における、値が 1 のビットの位置 (昇順) を返します。 符号付き整数の入力は、最初に符号なし整数にキャストされます。

構文

bitPositionsToArray(arg)

引数

返り値

入力の2進数表現において、1ビットが立っている位置を昇順に並べた配列を返します。Array(UInt64)

単一ビットがセットされている場合

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

すべてのビットが 1 の場合

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

bitmaskToArray

導入バージョン: v1.1.0

この関数は整数を 2 のべき乗の和に分解します。 2 のべき乗は昇順に並んだ配列として返されます。

構文

bitmaskToArray(num)

引数

返される値

入力値を 2 の冪の和として表したときの、各 2 の冪を昇順に並べた配列を返します。Array(UInt64)

基本的な例

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

単一の 2 の冪

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

bitmaskToList

導入バージョン: v1.1.0

bitmaskToArray と似ていますが、2 の冪の値をカンマ区切りの文字列として返します。

構文

bitmaskToList(num)

引数

戻り値

2 の累乗をカンマ区切りで並べた文字列を返します。String

基本的な例

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

char

導入バージョン: v20.1.0

渡された引数の数と同じ長さの文字列を返し、各バイトの値は対応する引数の値になります。数値型の複数の引数を受け取ります。

引数の値が UInt8 データ型の範囲外の場合、丸めやオーバーフローが発生する可能性のある形で UInt8 に変換されます。

構文

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

引数

戻り値

指定されたバイト列からなる文字列を返します。String

基本例

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

任意のエンコーディングの生成

-- You can construct a string of arbitrary encoding by passing the corresponding bytes.
-- for example UTF8
SELECT char(0xD0, 0xBF, 0xD1, 0x80, 0xD0, 0xB8, 0xD0, 0xB2, 0xD0, 0xB5, 0xD1, 0x82) AS hello;
┌─hello──┐
│ привет │
└────────┘

hex

導入バージョン: v1.1.0

引数の 16 進数表現を含む文字列を、型ごとに次のロジックに従って返します:

TypeDescription
(U)Int*最上位から最下位の 16 進桁 (「ニブル」) までを (ビッグエンディアン、すなわち「人間が読みやすい」順序で) 出力します。最上位の 0 ではないバイトから開始し (先頭の 0 バイトは省略されます) が、各バイトについては先頭の桁が 0 であっても常に 2 桁とも出力します。
Date および DateTime対応する整数としてフォーマットされます (Date はエポックからの日数、DateTime は Unix タイムスタンプの値) 。
String および FixedStringすべてのバイトは単純に 2 桁の 16 進数としてエンコードされます。0 バイトは省略されません。
Float* および Decimalメモリ上の表現としてエンコードされます。ClickHouse は内部的に常にリトルエンディアンで値を表現するため、その形式でエンコードされます。先頭および末尾の 0 バイトは省略されません。
UUIDビッグエンディアン順の文字列としてエンコードされます。

この関数は A-F の大文字を使用し、接頭辞 (0x など) や接尾辞 (h など) は使用しません。

構文

hex(arg)

引数

戻り値

引数の16進数表現を表す文字列を返します。String

単純な整数

SELECT hex(1)
01

Float32 型の数値

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

Float64 型の数値

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

UUID の変換

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

hilbertDecode

導入バージョン: v24.6.0

Hilbert 曲線のインデックスを、多次元空間における座標を表す符号なし整数のタプルにデコードします。

hilbertEncode 関数と同様に、この関数には 2 つの動作モードがあります。

  • Simple
  • Expanded

Simple モード

最大 2 つの符号なし整数を引数として受け取り、UInt64 のコードを生成します。

Expanded モード

最初の引数として範囲マスク (タプル) を受け取り、その他の引数として最大 2 つの符号なし整数を受け取ります。マスク中の各数値は、対応する引数を左シフトするビット数を指定し、その引数をその範囲内でスケーリングします。

範囲の拡張は、範囲 (またはカーディナリティ) が大きく異なる引数について、同程度の分布が必要な場合に有用です。例: 「IP Address」(0...FFFFFFFF) と 「Country code」(0...FF)。エンコード関数の場合と同様に、これは最大 8 個の数値に制限されます。

構文

hilbertDecode(tuple_size, code)

引数

返り値

指定したサイズのタプルを返します。Tuple(UInt64)

シンプルモード

SELECT hilbertDecode(2, 31)
["3", "4"]

引数が 1 つの場合

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

Expanded モード

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

カラムの使い方

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

導入バージョン: v24.6.0

符号なし整数のリストに対して、ヒルベルト曲線のコード値を計算します。

この関数には 2 つの動作モードがあります:

  • シンプル
  • 拡張

シンプルモード

最大 2 個の符号なし整数を引数として受け取り、UInt64 のコード値を生成します。

拡張モード

最初の引数として範囲マスク (Tuple) を、 その他の引数として最大 2 個の 符号なし整数 を受け取ります。

マスク内の各数値は、対応する引数を左にシフトするビット数を設定し、その範囲内で引数を事実上スケーリングします。

構文

-- Simplified mode
hilbertEncode(args)

-- Expanded mode
hilbertEncode(range_mask, args)

引数

  • args — 最大 2 つの UInt 値、または UInt 型のカラム。UInt8/16/32/64
  • range_mask — 拡張モード用の、最大 2 つの UInt 値、または UInt 型のカラム。UInt8/16/32/64

戻り値

UInt64 のコードを返します。UInt64

Simple モード

SELECT hilbertEncode(3, 4)
31

展開モード

-- Range expansion can be beneficial when you need a similar distribution for
-- arguments with wildly different ranges (or cardinality).
-- For example: 'IP Address' (0...FFFFFFFF) and 'Country code' (0...FF).
-- Note: tuple size must be equal to the number of the other arguments.
SELECT hilbertEncode((10, 6), 1024, 16)
4031541586602

単一引数

-- For a single argument without a tuple, the function returns the argument
-- itself as the Hilbert index, since no dimensional mapping is needed.
SELECT hilbertEncode(1)
1

拡張単一引数

-- If a single argument is provided with a tuple specifying bit shifts, the function
-- shifts the argument left by the specified number of bits.
SELECT hilbertEncode(tuple(2), 128)
512

カラムの使い方

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

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

mortonDecode

導入バージョン: v24.6.0

Morton encoding (ZCurve) を対応する符号なし整数タプルにデコードします。

mortonEncode 関数と同様に、この関数には 2 つの動作モードがあります:

  • シンプル
  • 拡張

シンプルモード

最初の引数として結果タプルのサイズを、2 番目の引数としてコードを受け取ります。

拡張モード

最初の引数としてレンジマスク (タプル) を、2 番目の引数としてコードを受け取ります。 マスク内の各数値はレンジ縮小の度合いを設定します:

  • 1 - 縮小なし
  • 2 - 2 倍に縮小
  • 3 - 3 倍に縮小 ⋮
  • 最大 8 倍に縮小。

引数のレンジ (またはカーディナリティ) が大きく異なる場合でも、同様の分布が必要なときには、レンジの拡大が有用です。例: 'IP Address' (0...FFFFFFFF) と 'Country code' (0...FF)。エンコード関数と同様に、これは最大 8 個の数値までに制限されます。

構文

-- Simple mode
mortonDecode(tuple_size, code)

-- Expanded mode
mortonDecode(range_mask, code)

引数

  • tuple_size — 8 以下の整数値。UInt8/16/32/64
  • range_mask — 拡張モードの場合、各引数に対するマスク。マスクは符号なし整数のタプルです。マスク内の各値は、範囲の縮小量を指定します。Tuple(UInt8/16/32/64)
  • code — UInt64 コード。UInt64

戻り値

指定されたサイズのタプルを返します。Tuple(UInt64)

使用例

シンプルモード

SELECT mortonDecode(3, 53)
["1", "2", "3"]

引数 1 つ

SELECT mortonDecode(1, 1)
["1"]

拡張モード (1 つの引数を縮小)

SELECT mortonDecode(tuple(2), 32768)
["128"]

カラムの使い方

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

導入バージョン: v24.6.0

符号なし整数のリストに対して Morton エンコード (ZCurve) を計算します。

この関数には 2 つの動作モードがあります:

  • Simple
  • Expanded*

Simple モード

最大 8 個の符号なし整数を引数として受け取り、UInt64 コードを生成します。

Expanded モード

最初の引数としてレンジマスク (Tuple) を、その他の引数として最大 8 個の符号なし整数を受け取ります。

マスク内の各数値はレンジ拡張の倍率を設定します:

  • 1 - 拡張なし
  • 2 - 2 倍拡張
  • 3 - 3 倍拡張 ⋮
  • 最大 8 倍拡張。

構文

-- Simplified mode
mortonEncode(args)

-- Expanded mode
mortonEncode(range_mask, args)

引数

  • args — 最大 8 個までの符号なし整数、または前述の型のカラム。UInt8/16/32/64
  • range_mask — 拡張モードで使用する、各引数に対応したマスク。マスクは 18 の符号なし整数からなるタプルです。マスク内の各数値は、範囲をどの程度縮小するかを指定します。Tuple(UInt8/16/32/64)

戻り値

UInt64 のコードを返します。UInt64

シンプルモード

SELECT mortonEncode(1, 2, 3)
53

Expanded モード

-- Range expansion can be beneficial when you need a similar distribution for
-- arguments with wildly different ranges (or cardinality)
-- For example: 'IP Address' (0...FFFFFFFF) and 'Country code' (0...FF).
-- Note: the Tuple size must be equal to the number of the other arguments.
SELECT mortonEncode((1,2), 1024, 16)
1572864

引数が 1 つの場合

-- Morton encoding for one argument is always the argument itself
SELECT mortonEncode(1)
1

拡張モードで引数が 1 つの場合

SELECT mortonEncode(tuple(2), 128)
32768

カラムの使い方

-- 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 mortonEncode(n1, n2, n3, n4, n5, n6, n7, n8) FROM morton_numbers;
2155374165

sqidDecode

導入バージョン: v24.1.0

sqid を数値の配列に変換します。

構文

sqidDecode(sqid)

引数

  • sqid — デコード対象の sqid。String

戻り値

sqid から取得した数値の配列を返します。Array(UInt64)

使用例

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

sqidEncode

導入バージョン: v24.1.0

数値を sqid に変換します。sqid は YouTube の動画 ID のような形式の ID 文字列です。

構文

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

別名: sqid

引数

返り値

ハッシュ ID (String 型) を返します。

使用例

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

unbin

導入バージョン: v21.8.0

引数内の 2 ビットごとに値として解釈し、その値が表すバイトに変換します。この関数は bin の逆の処理を行います。

数値引数に対しては、unbin()bin() の逆を返しません。結果を数値に変換したい場合は、reverse 関数および reinterpretAs<Type> 関数を使用できます。

注記

clickhouse-client 内から unbin が呼び出された場合、バイナリ文字列は UTF-8 として表示されます。

2 進数の数字 01 をサポートします。2 進数の桁数は 8 の倍数である必要はありません。引数の文字列に 2 進数以外の文字が含まれている場合、 結果は未定義です (例外はスローされません) 。

構文

unbin(arg)

引数

  • arg — 任意長の2進数文字列。String

戻り値

バイナリ文字列 (BLOB) を返します。String

基本的な使用方法

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

数値に変換

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

unhex

導入バージョン: v1.1.0

hex と逆の変換を行います。引数内の 16 進数の各 2 桁を数値として解釈し、その数値で表されるバイトに変換します。返される値はバイナリ文字列 (BLOB) です。

結果を数値に変換したい場合は、reverse 関数と reinterpretAs<Type> 関数を使用できます。

注記

clickhouse-client は文字列を UTF-8 として解釈します。 そのため、hex が返す値の表示結果が予期しないものに見える場合があります。

大文字・小文字両方の A-F をサポートします。 16 進数の桁数は偶数である必要はありません。 奇数の場合、最後の 1 桁は 00-0F バイトの下位 4 ビットとして解釈されます。 引数の文字列に 16 進数以外の文字が含まれている場合は、実装依存の結果が返されます (例外はスローされません)。 数値引数に対しては、hex(N) の逆変換は unhex() によっては行われません。

Syntax

unhex(arg)

引数

  • arg — 任意の数の16進数の数字からなる文字列。String または FixedString

戻り値

バイナリ文字列 (BLOB) を返します。String

基本的な使い方

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

数値への変換

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