エンコード関数

bech32Decode

導入バージョン: v25.6

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

注記

encode 関数とは異なり、Bech32Decode はパディング済みの FixedString 型を自動的に処理します。

構文

bech32Decode(address)

引数

address — デコードする Bech32 形式の文字列。String または FixedString

戻り値

文字列のエンコードに使用された (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

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

注記

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

構文

bech32Encode(hrp, data[, witver])

引数

hrp — コードの「human-readable part（人間可読部）」を指定する、小文字のみからなる 1〜83 文字の文字列。通常は 'bc' または 'tb'。String または FixedString
data — エンコード対象のバイナリデータを表す文字列。String または FixedString
witver — 省略可能。witness バージョン（デフォルト = 1）。実行するアルゴリズムのバージョンを指定する UInt*。Bech32 の場合は 0、Bech32m の場合は 1 以上。UInt*

戻り値

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

例

デフォルトの Bech32m

-- witness バージョンが指定されていない場合、デフォルトは 1 となり、更新された Bech32m アルゴリズムが使用されます。
SELECT bech32Encode('bc', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'))

bc1w508d6qejxtdg4y5r3zarvary0c5xw7k8zcwmq

Bech32 アルゴリズム

-- witness バージョンを 0 に設定すると、異なるアドレス文字列が生成されます。
SELECT bech32Encode('bc', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 0)

bc1w508d6qejxtdg4y5r3zarvary0c5xw7kj7gz7z

カスタムHRP

-- 'bc'（メインネット）と'tb'（テストネット）はSegWitアドレス形式で許可されている唯一のhrp値ですが、
-- Bech32は上記の要件を満たす任意のhrpを使用できます。
SELECT bech32Encode('abcdefg', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 10)

abcdefg1w508d6qejxtdg4y5r3zarvary0c5xw7k9rp8r4

bin

導入バージョン: v21.8

引数のバイナリ表現を含む文字列を、型ごとに次のロジックに従って返します。

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

構文

bin(arg)

引数

arg — 2 進数に変換する値。String、FixedString、(U)Int*、Float*、Decimal、Date、DateTime のいずれか。

戻り値

引数の 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

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

構文

bitPositionsToArray(引数)

引数

arg — 整数値。(U)Int*

戻り値

入力の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

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

構文

bitmaskToArray(num)

引数

num — 整数値。(U)Int*

返される値

入力された数値と等しくなるように合計した 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

bitmaskToArray と同様ですが、2 のべき乗をカンマ区切りの文字列として返します。

構文

bitmaskToList(num)

引数

num — 整数値。(U)Int*

戻り値

カンマ区切りの 2 のべき乗を含む文字列を返します。String

例

基本的な例

SELECT bitmaskToList(50) AS powers_list

┌─powers_list───┐
│ 2, 16, 32     │
└───────────────┘

char

導入バージョン: v20.1

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

引数の値が UInt8 データ型の範囲外の場合、必要に応じて丸めやオーバーフローが発生しながら UInt8 に変換されます。

構文

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

引数

num1[, num2[, num3 ...]] — 整数として解釈される数値引数。(U)Int8/16/32/64 または Float*

戻り値

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

例

基本的な例

SELECT char(104.1, 101, 108.9, 108.9, 111) AS hello;

┌─hello─┐
│ hello │
└───────┘

任意のエンコーディングの構築

-- 対応するバイト列を渡すことで、任意のエンコーディングの文字列を生成できます。
-- 例えば UTF-8 の場合
SELECT char(0xD0, 0xBF, 0xD1, 0x80, 0xD0, 0xB8, 0xD0, 0xB2, 0xD0, 0xB5, 0xD1, 0x82) AS hello;

┌─hello──┐
│ привет │
└────────┘

hex

導入バージョン: v1.1

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

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

この関数は A-F の大文字を使用し、プレフィックス（0x など）やサフィックス（h など）は使用しません。

構文

hex(arg)

引数

arg — 16進数に変換する値。String または (U)Int* または Float* または Decimal または Date または DateTime

戻り値

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

例

単純な整数

SELECT hex(1)

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

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

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

シンプル
拡張

シンプルモード

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

拡張モード

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

範囲の拡張は、範囲（またはカーディナリティ）が大きく異なる引数間で類似した分布を得たい場合に有用です。例: 「IP アドレス」(0...FFFFFFFF) と「国コード」(0...FF)。エンコード関数と同様に、最大 8 個の数値までに制限されています。

構文

hilbertDecode(tuple_size, code)

引数

tuple_size — 2 以下の整数値。UInt8/16/32/64 または Tuple(UInt8/16/32/64)
code — UInt64 型のコード。UInt64

返り値

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

例

シンプルモード

SELECT hilbertDecode(2, 31)

["3", "4"]

単一の引数

-- 1つの引数に対するヒルベルト符号は、常にその引数自体（タプルとして）です。
SELECT hilbertDecode(1, 1)

["1"]

拡張モード

-- ビットシフトを指定するタプルを持つ単一の引数は、それに応じて右シフトされます。
SELECT hilbertDecode(tuple(2), 32768)

["128"]

列の利用

-- まずテーブルを作成し、いくつかのデータを挿入します
CREATE TABLE hilbert_numbers(
    n1 UInt32,
    n2 UInt32
)
ENGINE=MergeTree()
ORDER BY n1 SETTINGS index_granularity = 8192, index_granularity_bytes = '10Mi';
insert into hilbert_numbers (*) values(1,2);

-- 関数の引数には定数ではなくカラム名を使用します
SELECT untuple(hilbertDecode(2, hilbertEncode(n1, n2))) FROM hilbert_numbers;

1    2

hilbertEncode

導入バージョン: v24.6

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

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

Simple
Expanded

Simple モード

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

Expanded モード

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

マスク中のそれぞれの数値は、対応する引数を左シフトするビット数を指定し、対応する引数をその範囲内でスケーリングします。

構文

-- シンプルモード
hilbertEncode(args)

-- 拡張モード
hilbertEncode(range_mask, args)

引数

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

戻り値

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

例

シンプルモード

SELECT hilbertEncode(3, 4)

拡張モード

-- 範囲の拡張は、範囲（またはカーディナリティ）が大きく異なる引数に対しても、
-- 似たような分布が必要な場合に有用です。
-- 例: 「IPアドレス」(0...FFFFFFFF) と 「国コード」(0...FF)。
-- 注意: タプルのサイズは、他の引数の個数と等しくなければなりません。
SELECT hilbertEncode((10, 6), 1024, 16)

4031541586602

単一引数

-- タプルではない単一の引数が指定された場合、この関数は
-- 次元マッピングが不要なため、その引数自体を Hilbert インデックスとして返します。
SELECT hilbertEncode(1)

展開後の単一引数

-- タプルでビットシフトを指定した単一の引数が提供された場合、
-- 関数は指定されたビット数だけ引数を左にシフトします。
SELECT hilbertEncode(tuple(2), 128)

列の使用方法

-- まずテーブルを作成し、いくつかデータを挿入します
CREATE TABLE hilbert_numbers(
    n1 UInt32,
    n2 UInt32
)
ENGINE=MergeTree()
ORDER BY n1;
insert into hilbert_numbers (*) values(1, 2);

-- 関数の引数には定数ではなくカラム名を使用します
SELECT hilbertEncode(n1, n2) FROM hilbert_numbers;

mortonDecode

導入バージョン: v24.6

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

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

シンプル
拡張

シンプルモード

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

拡張モード

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

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

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

構文

-- シンプルモード
mortonDecode(tuple_size, code)

-- 拡張モード
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"]

単一引数

SELECT mortonDecode(1, 1)

["1"]

拡張モード：引数を 1 つにまとめる

SELECT mortonDecode(tuple(2), 32768)

["128"]

カラムの使用

-- まずテーブルを作成し、データを挿入します
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);

-- 関数の引数として定数の代わりに列名を使用します
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

符号なし整数のリストに対して、Morton 符号化（ZCurve）を計算します。

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

シンプル
拡張

シンプルモード

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

拡張モード

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

マスク内の各数値は、範囲拡張の倍率を指定します:

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

構文

-- 簡易モード
mortonEncode(args)

-- 拡張モード
mortonEncode(range_mask, args)

引数

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

戻り値

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

例

シンプルモード

SELECT mortonEncode(1, 2, 3)

詳細モード

-- 範囲拡張は、大きく異なる範囲（またはカーディナリティ）を持つ
-- 引数に対して類似した分布が必要な場合に有用です
-- 例：「IPアドレス」（0...FFFFFFFF）と「国コード」（0...FF）
-- 注：タプルのサイズは他の引数の数と一致する必要があります。
SELECT mortonEncode((1,2), 1024, 16)

単一の引数

-- 1つの引数に対するMortonエンコーディングは常に引数自体です
SELECT mortonEncode(1)

展開後の単一引数

SELECT mortonEncode(tuple(2), 128)

カラムの利用

-- まずテーブルを作成し、いくつかデータを挿入します
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);

-- 関数の引数には定数ではなくカラム名を指定します
SELECT mortonEncode(n1, n2, n3, n4, n5, n6, n7, n8) FROM morton_numbers;

2155374165

sqidDecode

導入: v24.1

sqid を数値の配列にデコードします。

構文

sqidDecode(sqid)

引数

sqid — デコードする sqid。String

戻り値

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

例

使用例

SELECT sqidDecode('gXHfJ1C6dN');

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

sqidEncode

導入バージョン: v24.1

数値を sqid（YouTube の動画 ID のような ID 文字列）にエンコードします。

構文

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

エイリアス: sqid

引数

n1[, n2, ...] — 任意の数の数値。UInt8/16/32/64

戻り値

ハッシュ ID を返します。型は String です。

例

使用例

SELECT sqidEncode(1, 2, 3, 4, 5);

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

unbin

導入バージョン: v21.8

引数内の各 2 ビットの組を数値として解釈し、その数値で表されるバイトへ変換します。この関数は bin と逆の処理を行います。

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

注記

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

2 進数の数字 0 と 1 をサポートします。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

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

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

注記

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

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

構文

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 │
└──────┘

bech32Decode​

bech32Encode​

bin​

bitPositionsToArray​

bitmaskToArray​

bitmaskToList​

char​

hex​

hilbertDecode​

hilbertEncode​

mortonDecode​

mortonEncode​

sqidDecode​

sqidEncode​

unbin​

unhex​

bech32Decode

bech32Encode

bin

bitPositionsToArray

bitmaskToArray

bitmaskToList

char

hex

hilbertDecode

hilbertEncode

mortonDecode

mortonEncode

sqidDecode

sqidEncode

unbin

unhex