json-functions

JSONを解析するための関数セットが2つあります：

• simpleJSON* (visitParam*)は、限定されたJSONサブセットを非常に高速で解析するために作られています。
• JSONExtract*は、通常のJSONを解析するために作られています。

simpleJSON (visitParam) 関数

ClickHouseには簡略化されたJSONを操作するための特別な関数があります。これらのすべてのJSON関数は、JSONがどのようなものであるかについて強い前提に基づいています。できるだけ少ない処理で、できるだけ早く仕事を完了させようとします。

以下の前提があります：

1. フィールド名（関数の引数）は定数でなければなりません。
2. フィールド名は何らかの形でJSONで正規化されている必要があります。例えば：simpleJSONHas('{"abc":"def"}', 'abc') = 1 ですが、 simpleJSONHas('{"\\u0061\\u0062\\u0063":"def"}', 'abc') = 0 です。
3. フィールドは任意のネストレベルで無差別に検索されます。複数の一致するフィールドがある場合、最初の出現が使用されます。
4. JSONに文字列リテラルの外にスペース文字はありません。

simpleJSONHas

field_nameという名前のフィールドが存在するかどうかを確認します。結果は UInt8 です。

構文

エイリアス： visitParamHas。

パラメータ

• json — フィールドを検索するJSON。 String
• field_name — 検索するフィールドの名前。 String literal

返される値

• フィールドが存在すれば 1 を、そうでなければ 0 を返します。 UInt8。

例

クエリ：

結果：

simpleJSONExtractUInt

field_nameという名前のフィールドの値から UInt64 を解析します。これは文字列フィールドであれば、文字列の始めから数字を解析しようとします。フィールドが存在しないか、存在するが数値を含まない場合は 0 を返します。

構文

エイリアス： visitParamExtractUInt。

パラメータ

• json — フィールドを検索するJSON。 String
• field_name — 検索するフィールドの名前。 String literal

返される値

• フィールドが存在し、数値を含んでいれば、フィールドから解析された数値を返します。そうでなければ 0 を返します。 UInt64。

例

クエリ：

結果：

simpleJSONExtractInt

field_nameという名前のフィールドの値から Int64 を解析します。これは文字列フィールドであれば、文字列の始めから数字を解析しようとします。フィールドが存在しないか、存在するが数値を含まない場合は 0 を返します。

構文

エイリアス： visitParamExtractInt。

パラメータ

• json — フィールドを検索するJSON。 String
• field_name — 検索するフィールドの名前。 String literal

返される値

• フィールドが存在し、数値を含んでいれば、フィールドから解析された数値を返します。そうでなければ 0 を返します。 Int64。

例

クエリ：

結果：

simpleJSONExtractFloat

field_nameという名前のフィールドの値から Float64 を解析します。これは文字列フィールドであれば、文字列の始めから数字を解析しようとします。フィールドが存在しないか、存在するが数値を含まない場合は 0 を返します。

構文

エイリアス： visitParamExtractFloat。

パラメータ

• json — フィールドを検索するJSON。 String
• field_name — 検索するフィールドの名前。 String literal

返される値

• フィールドが存在し、数値を含んでいれば、フィールドから解析された数値を返します。そうでなければ 0 を返します。 Float64。

例

クエリ：

結果：

simpleJSONExtractBool

field_nameという名前のフィールドから真偽値を解析します。結果は UInt8 です。

構文

エイリアス： visitParamExtractBool。

パラメータ

• json — フィールドを検索するJSON。 String
• field_name — 検索するフィールドの名前。 String literal

返される値

フィールドの値が true であれば 1 を、それ以外は 0 を返します。この関数は以下のケースを含め（かつそれだけでなく） 0 を返します：

• フィールドが存在しない。
• フィールドが文字列として true を含む、例えば: {"field":"true"}。
• フィールドが数値として 1 を含む。

例

クエリ：

結果：

simpleJSONExtractRaw

field_nameという名前のフィールドの値を区切りを含めて String として返します。

構文

エイリアス： visitParamExtractRaw。

パラメータ

• json — フィールドを検索するJSON。 String
• field_name — 検索するフィールドの名前。 String literal

返される値

• フィールドが存在すればその値を文字列として返し、区切りも含まれます。そうでなければ空の文字列を返します。 String

例

クエリ：

結果：

simpleJSONExtractString

field_nameという名前のフィールドの値から、二重引用符で囲まれた String を解析します。

構文

エイリアス： visitParamExtractString。

パラメータ

• json — フィールドを検索するJSON。 String
• field_name — 検索するフィールドの名前。 String literal

返される値

• フィールドのアンエスケープされた値を文字列として返します。フィールドが二重引用符の文字列を含まない、アンエスケープが失敗した、またはフィールドが存在しない場合は空の文字列を返します。 String。

実装の詳細

現在、基本多言語プレーン以外の形式 \uXXXX\uYYYY のコードポイントはサポートされていません（それらはUTF-8の代わりにCESU-8に変換されます）。

例

クエリ：

結果：

JSONExtract 関数

次の関数は、simdjsonに基づいており、より複雑なJSON解析要求に対応するために設計されています。

isValidJSON

渡された文字列が有効なJSONであるかを確認します。

構文

例

JSONHas

JSON文書にその値が存在する場合、1が返されます。値が存在しない場合は 0 が返されます。

構文

パラメータ

• json — 解析するJSON文字列。 String。
• indices_or_keys — 零個以上の引数のリストで、各引数は文字列または整数のいずれかです。 String, Int*。

indices_or_keys型：

• 文字列 = キーによるオブジェクトメンバーへのアクセス。
• 正の整数 = 開始からn番目のメンバー/キーへのアクセス。
• 負の整数 = 終わりからn番目のメンバー/キーへのアクセス。

返される値

• json内に値が存在すれば 1 を、それ以外の場合は 0 を返します。 UInt8。

例

クエリ：

要素の最小インデックスは1です。したがって、要素0は存在しません。整数を使用してJSON配列およびJSONオブジェクトの両方にアクセスできます。例えば：

JSONLength

JSON配列またはJSONオブジェクトの長さを返します。値が存在しない場合や、型が間違っている場合は 0 が返されます。

構文

パラメータ

• json — 解析するJSON文字列。 String。
• indices_or_keys — 零個以上の引数のリストで、各引数は文字列または整数のいずれかです。 String, Int*。

indices_or_keys型：

• 文字列 = キーによるオブジェクトメンバーへのアクセス。
• 正の整数 = 開始からn番目のメンバー/キーへのアクセス。
• 負の整数 = 終わりからn番目のメンバー/キーへのアクセス。

返される値

• JSON配列またはJSONオブジェクトの長さを返します。値が存在しない場合や、型が間違っている場合は 0 を返します。 UInt64。

例

JSONType

JSON値の型を返します。値が存在しない場合は Null=0 が返されます（通常のNullではなく、Enum8('Null' = 0, 'String' = 34,...）の Null=0` です）。

構文

パラメータ

• json — 解析するJSON文字列。 String。
• indices_or_keys — 零個以上の引数のリストで、各引数は文字列または整数のいずれかです。 String, Int*。

indices_or_keys型：

• 文字列 = キーによるオブジェクトメンバーへのアクセス。
• 正の整数 = 開始からn番目のメンバー/キーへのアクセス。
• 負の整数 = 終わりからn番目のメンバー/キーへのアクセス。

返される値

• JSON値の型を文字列として返します。値が存在しない場合は Null=0 を返します。 Enum。

例

JSONExtractUInt

JSONを解析し、UInt型の値を抽出します。

構文

パラメータ

• json — 解析するJSON文字列。 String。
• indices_or_keys — 零個以上の引数のリストで、各引数は文字列または整数のいずれかです。 String, Int*。

indices_or_keys型：

• 文字列 = キーによるオブジェクトメンバーへのアクセス。
• 正の整数 = 開始からn番目のメンバー/キーへのアクセス。
• 負の整数 = 終わりからn番目のメンバー/キーへのアクセス。

返される値

• 存在すればUInt値を返します。そうでなければ 0 を返します。 UInt64。

例

クエリ：

結果：

JSONExtractInt

JSONを解析し、Int型の値を抽出します。

構文

パラメータ

• json — 解析するJSON文字列。 String。
• indices_or_keys — 零個以上の引数のリストで、各引数は文字列または整数のいずれかです。 String, Int*。

indices_or_keys型：

• 文字列 = キーによるオブジェクトメンバーへのアクセス。
• 正の整数 = 開始からn番目のメンバー/キーへのアクセス。
• 負の整数 = 終わりからn番目のメンバー/キーへのアクセス。

返される値

• 存在すればInt値を返します。そうでなければ 0 を返します。 Int64。

例

クエリ：

結果：

JSONExtractFloat

JSONを解析し、Float型の値を抽出します。

構文

パラメータ

• json — 解析するJSON文字列。 String。
• indices_or_keys — 零個以上の引数のリストで、各引数は文字列または整数のいずれかです。 String, Int*。

indices_or_keys型：

• 文字列 = キーによるオブジェクトメンバーへのアクセス。
• 正の整数 = 開始からn番目のメンバー/キーへのアクセス。
• 負の整数 = 終わりからn番目のメンバー/キーへのアクセス。

返される値

• 存在すればFloat値を返します。そうでなければ 0 を返します。 Float64。

例

クエリ：

結果：

JSONExtractBool

JSONを解析し、ブール値を抽出します。値が存在しない場合や型が間違っている場合は 0 が返されます。

構文

パラメータ

• json — 解析するJSON文字列。 String。
• indices_or_keys — 零個以上の引数のリストで、各引数は文字列または整数のいずれかです。 String, Int*。

indices_or_keys型：

• 文字列 = キーによるオブジェクトメンバーへのアクセス。
• 正の整数 = 開始からn番目のメンバー/キーへのアクセス。
• 負の整数 = 終わりからn番目のメンバー/キーへのアクセス。

返される値

• 存在すればブール値を返します。そうでなければ 0 を返します。 Bool。

例

クエリ：

結果：

JSONExtractString

JSONを解析し、文字列を抽出します。この関数は、visitParamExtractString関数と似ています。値が存在しない場合や型が間違っている場合は、空の文字列が返されます。

構文

パラメータ

• json — 解析するJSON文字列。 String。
• indices_or_keys — 零個以上の引数のリストで、各引数は文字列または整数のいずれかです。 String, Int*。

indices_or_keys型：

• 文字列 = キーによるオブジェクトメンバーへのアクセス。
• 正の整数 = 開始からn番目のメンバー/キーへのアクセス。
• 負の整数 = 終わりからn番目のメンバー/キーへのアクセス。

返される値

• jsonからのアンエスケープされた文字列を返します。アンエスケープが失敗した場合、値が存在しない場合、または型が間違っている場合は空の文字列が返されます。 String。

例

JSONExtract

JSONを解析し、指定されたClickHouseデータ型の値を抽出します。この関数は、前述の JSONExtract<type> 関数の一般化バージョンです。意味するところ:

JSONExtract(..., 'String') は JSONExtractString() と完全に同じものを返し、 JSONExtract(..., 'Float64') は JSONExtractFloat() と完全に同じものを返します。

構文

パラメータ

• json — 解析するJSON文字列。 String。
• indices_or_keys — 零個以上の引数のリストで、各引数は文字列または整数のいずれかです。 String, Int*。
• return_type — 抽出する値の型を指定する文字列。 String。

indices_or_keys型：

• 文字列 = キーによるオブジェクトメンバーへのアクセス。
• 正の整数 = 開始からn番目のメンバー/キーへのアクセス。
• 負の整数 = 終わりからn番目のメンバー/キーへのアクセス。

返される値

• 指定された型の値が存在すればその値を返し、そうでなければ 0、Null、または空文字列を返します。 UInt64、Int64、Float64、Bool または String。

例

複数の indices_or_keys パラメータを渡してネストされた値を参照する：

結果：

JSONExtractKeysAndValues

JSONからキー-値ペアを解析し、値が指定されたClickHouseデータ型であるものを抽出します。

構文

パラメータ

• json — 解析するJSON文字列。 String。
• indices_or_keys — 零個以上の引数のリストで、各引数は文字列または整数のいずれかです。 String, Int*。
• value_type — 抽出する値の型を指定する文字列。 String。

indices_or_keys型：

• 文字列 = キーによるオブジェクトメンバーへのアクセス。
• 正の整数 = 開始からn番目のメンバー/キーへのアクセス。
• 負の整数 = 終わりからn番目のメンバー/キーへのアクセス。

返される値

• 解析されたキー-値ペアの配列を返します。 Array(Tuple(value_type))。

例

JSONExtractKeys

JSON文字列を解析し、キーを抽出します。

構文

パラメータ

• json — 有効なJSONを含むString。
• a, b, c... — ネストされたJSONオブジェクト内の内部フィールドへのパスを指定するコンマ区切りインデックスまたはキー。各引数は、キーによってフィールドを取得するためのStringか、N番目のフィールドを取得するためのIntegerのいずれかです（1からインデックス、負の整数は末尾からカウント）。設定されていない場合、全体のJSONが最上級オブジェクトとして解析されます。オプションのパラメータ。

返される値

• JSONのキーを含む配列を返します。 Array(String)。

例

クエリ：

結果：

JSONExtractRaw

JSONの一部を未解析の文字列として返します。部分が存在しないか型が間違っている場合は空の文字列が返されます。

構文

パラメータ

• json — 解析するJSON文字列。 String。
• indices_or_keys — 零個以上の引数のリストで、各引数は文字列または整数のいずれかです。 String, Int*。

indices_or_keys型：

• 文字列 = キーによるオブジェクトメンバーへのアクセス。
• 正の整数 = 開始からn番目のメンバー/キーへのアクセス。
• 負の整数 = 終わりからn番目のメンバー/キーへのアクセス。

返される値

• JSONの一部を未解析の文字列として返します。部分が存在しないか型が間違っている場合、空の文字列が返されます。 String。

例

JSONExtractArrayRaw

JSON配列の要素を、各要素が未解析の文字列として表された配列を返します。部分が存在しないか、配列でない場合は空の配列が返されます。

構文

パラメータ

• json — 解析するJSON文字列。 String。
• indices_or_keys — 零個以上の引数のリストで、各引数は文字列または整数のいずれかです。 String, Int*。

indices_or_keys型：

• 文字列 = キーによるオブジェクトメンバーへのアクセス。
• 正の整数 = 開始からn番目のメンバー/キーへのアクセス。
• 負の整数 = 終わりからn番目のメンバー/キーへのアクセス。

返される値

• JSON配列の要素を、各要素が未解析の文字列として表した配列を返します。そうでない場合、部分が存在しない場合や配列でない場合は空の配列が返されます。 Array(String)。

例

JSONExtractKeysAndValuesRaw

JSONオブジェクトから生データを抽出します。

構文

引数

• json — Stringで有効なJSON。
• p, a, t, h — ネストされたJSONオブジェクト内の内部フィールドへのパスを指定するコンマ区切りインデックスまたはキー。各引数は、キーによってフィールドを取得するための文字列か、N番目のフィールドを取得するための整数のいずれかです（設定されていない場合、全体のJSONが最上級オブジェクトとして解析されます）。オプションです。

返される値

• ('key', 'value')のタプルを含む配列。両方のタプルメンバーは文字列です。 Array(Tuple(String, String))。
• 要求されたオブジェクトが存在しない場合や、入力JSONが無効な場合は空の配列が返されます。 Array(Tuple(String, String))。

例

クエリ：

結果：

クエリ：

結果：

クエリ：

結果：

JSON_EXISTS

JSON文書にその値が存在するなら 1 が返されます。値が存在しない場合は 0 が返されます。

構文

パラメータ

• json — 有効なJSONを含む文字列。 String。
• path — パスを表す文字列。 String。

注記

バージョン21.11以前では、引数の順序が間違っていました。つまり、JSON_EXISTS(path, json)

返される値

• JSON文書にその値が存在すれば 1 を、それ以外の場合は 0 が返されます。

例

JSON_QUERY

JSONを解析し、JSON配列またはJSONオブジェクトとして値を抽出します。値が存在しない場合、空の文字列が返されます。

構文

パラメータ

• json — 有効なJSONを含む文字列。 String。
• path — パスを表す文字列。 String。

注記

バージョン21.11以前では、引数の順序が間違っていました。つまり、JSON_QUERY(path, json)

返される値

• 抽出した値をJSON配列またはJSONオブジェクトとして返します。存在しない場合は空の文字列を返します。 String。

例

クエリ：

結果：

JSON_VALUE

JSONを解析し、スカラ値としての値を抽出します。値が存在しない場合、デフォルトでは空文字列が返されます。

この関数は以下の設定で制御されます：

• function_json_value_return_type_allow_nullable を true に設定すると、 NULL が返されます。値が複雑な型（構造体、配列、マップなど）の場合、デフォルトでは空文字列が返されます。
• function_json_value_return_type_allow_complex を true に設定すると、複雑な値が返されます。

構文

パラメータ

• json — 有効なJSONを含む文字列。 String.
• path — パスを表す文字列。 String.

注記

バージョン21.11以前は、引数の順序が逆でした。すなわち、 JSON_EXISTS(path, json) です。

返される値

• 抽出された値が存在する場合はJSONスカラとして返され、それ以外の場合は空文字列が返されます。 String.

例

クエリ:

結果:

toJSONString

値をJSON表現にシリアライズします。さまざまなデータ型やネストされた構造がサポートされています。 64ビット 整数 またはそれ以上（ UInt64 や Int128 のような）は、デフォルトで引用符で囲まれます。 output_format_json_quote_64bit_integers がこの動作を制御します。 特別な値 NaN および inf は null に置き換えられます。表示するには output_format_json_quote_denormals 設定を有効にします。 Enum 値をシリアライズする場合、関数はその名前を出力します。

構文

引数

• value — シリアライズする値。値は任意のデータ型を持つことができます。

返される値

• 値のJSON表現。 String.

例

最初の例は Map のシリアライズを示しています。 2番目の例は、特別な値を Tuple でラップしたものを示しています。

クエリ:

結果:

関連情報

• output_format_json_quote_64bit_integers
• output_format_json_quote_denormals

JSONArrayLength

最も外側のJSON配列の要素数を返します。入力JSON文字列が無効な場合、関数はNULLを返します。

構文

別名: JSON_ARRAY_LENGTH(json).

引数

• json — 有効なJSONを含む String.

返される値

• json が有効なJSON配列文字列の場合、配列要素の数を返します。それ以外の場合はNULLを返します。 Nullable(UInt64).

例

jsonMergePatch

複数のJSONオブジェクトをマージして形成されたマージされたJSONオブジェクト文字列を返します。

構文

引数

• json — 有効なJSONを含む String.

返される値

• JSONオブジェクト文字列が有効な場合、マージされたJSONオブジェクト文字列を返します。 String.

例

JSONAllPaths

各行に格納されているすべてのパスのリストを返します JSON カラムで。

構文

引数

• json — JSON.

返される値

• パスの配列。 Array(String).

例

JSONAllPathsWithTypes

各行に格納されているすべてのパスとそのデータ型のマップを返します JSON カラムで。

構文

引数

• json — JSON.

返される値

• パスの配列。 Map(String, String).

例

JSONDynamicPaths

JSON カラムで、各行に格納されている動的パスのリストを返します。

構文

引数

• json — JSON.

返される値

• パスの配列。 Array(String).

例

JSONDynamicPathsWithTypes

個々の行に格納されている動的パスとその型のマップを返します JSON カラムで。

構文

引数

• json — JSON.

返される値

• パスの配列。 Map(String, String).

例

JSONSharedDataPaths

JSON カラムで、共有データ構造に格納されているパスのリストを返します。

構文

引数

• json — JSON.

返される値

• パスの配列。 Array(String).

例

JSONSharedDataPathsWithTypes

JSON カラムで、共有データ構造に格納されているパスとそれらの型のマップを各行に返します。

構文

引数

• json — JSON.

返される値

• パスの配列。 Map(String, String).

例