JSON Functions

There are two sets of functions to parse JSON:

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

simpleJSON (visitParam) functions

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 functions

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

isValidJSON

渡された文字列が有効なJSONかどうかをチェックします。

構文

例

JSONHas

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

構文

パラメータ

• json — 解析するJSON文字列。 String 。
• indices_or_keys — 文字列または整数のいずれかを指定できるゼロ個以上の引数のリスト。 String、 Int*。

indices_or_keys のタイプ：

• String = キーによってオブジェクトメンバーにアクセスします。
• Positive integer = 開始から n 番目のメンバー/キーにアクセスします。
• Negative integer = 終わりから n 番目のメンバー/キーにアクセスします。

戻り値

• 値が json に存在する場合は 1 を返し、そうでない場合は 0 を返します。 UInt8。

例

クエリ：

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

JSONLength

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

構文

パラメータ

• json — 解析するJSON文字列。 String 。
• indices_or_keys — 文字列または整数のいずれかを指定できるゼロ個以上の引数のリスト。 String、 Int*。

indices_or_keys のタイプ：

• String = キーによってオブジェクトメンバーにアクセスします。
• Positive integer = 開始から n 番目のメンバー/キーにアクセスします。
• Negative integer = 終わりから 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 のタイプ：

• String = キーによってオブジェクトメンバーにアクセスします。
• Positive integer = 開始から n 番目のメンバー/キーにアクセスします。
• Negative integer = 終わりから n 番目のメンバー/キーにアクセスします。

戻り値

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

例

JSONExtractUInt

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

構文

パラメータ

• json — 解析するJSON文字列。 String 。
• indices_or_keys — 文字列または整数のいずれかを指定できるゼロ個以上の引数のリスト。 String、 Int*。

indices_or_keys のタイプ：

• String = キーによってオブジェクトメンバーにアクセスします。
• Positive integer = 開始から n 番目のメンバー/キーにアクセスします。
• Negative integer = 終わりから n 番目のメンバー/キーにアクセスします。

戻り値

• 存在する場合はUInt値を返し、そうでない場合は 0 を返します。 UInt64。

例

クエリ：

結果：

JSONExtractInt

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

構文

パラメータ

• json — 解析するJSON文字列。 String 。
• indices_or_keys — 文字列または整数のいずれかを指定できるゼロ個以上の引数のリスト。 String、 Int*。

indices_or_keys のタイプ：

• String = キーによってオブジェクトメンバーにアクセスします。
• Positive integer = 開始から n 番目のメンバー/キーにアクセスします。
• Negative integer = 終わりから n 番目のメンバー/キーにアクセスします。

戻り値

• 存在する場合はInt値を返し、そうでない場合は 0 を返します。 Int64。

例

クエリ：

結果：

JSONExtractFloat

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

構文

パラメータ

• json — 解析するJSON文字列。 String 。
• indices_or_keys — 文字列または整数のいずれかを指定できるゼロ個以上の引数のリスト。 String、 Int*。

indices_or_keys のタイプ：

• String = キーによってオブジェクトメンバーにアクセスします。
• Positive integer = 開始から n 番目のメンバー/キーにアクセスします。
• Negative integer = 終わりから n 番目のメンバー/キーにアクセスします。

戻り値

• 存在する場合はFloat値を返し、そうでない場合は 0 を返します。 Float64。

例

クエリ：

結果：

JSONExtractBool

JSONを解析し、ブール値を抽出します。値が存在しないか間違ったタイプの場合は 0 が返されます。

構文

パラメータ

• json — 解析するJSON文字列。 String 。
• indices_or_keys — 文字列または整数のいずれかを指定できるゼロ個以上の引数のリスト。 String、 Int*。

indices_or_keys のタイプ：

• String = キーによってオブジェクトメンバーにアクセスします。
• Positive integer = 開始から n 番目のメンバー/キーにアクセスします。
• Negative integer = 終わりから n 番目のメンバー/キーにアクセスします。

戻り値

• 存在する場合はブール値を返し、そうでない場合は 0 を返します。 Bool。

例

クエリ：

結果：

JSONExtractString

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

構文

パラメータ

• json — 解析するJSON文字列。 String 。
• indices_or_keys — 文字列または整数のいずれかを指定できるゼロ個以上の引数のリスト。 String、 Int*。

indices_or_keys のタイプ：

• String = キーによってオブジェクトメンバーにアクセスします。
• Positive integer = 開始から n 番目のメンバー/キーにアクセスします。
• Negative integer = 終わりから 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 のタイプ：

• String = キーによってオブジェクトメンバーにアクセスします。
• Positive integer = 開始から n 番目のメンバー/キーにアクセスします。
• Negative integer = 終わりから n 番目のメンバー/キーにアクセスします。

戻り値

• 指定された型の存在する値を返し、そうでない場合は指定された型に応じて 0 、 Null 、または空文字列を返します。 UInt64、 Int64、 Float64、 Bool または String。

例

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

結果：

JSONExtractKeysAndValues

指定されたClickHouseデータ型の値を持つJSONから、キー-値ペアを解析します。

構文

パラメータ

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

indices_or_keys のタイプ：

• String = キーによってオブジェクトメンバーにアクセスします。
• Positive integer = 開始から n 番目のメンバー/キーにアクセスします。
• Negative integer = 終わりから 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 のタイプ：

• String = キーによってオブジェクトメンバーにアクセスします。
• Positive integer = 開始から n 番目のメンバー/キーにアクセスします。
• Negative integer = 終わりから n 番目のメンバー/キーにアクセスします。

戻り値

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

例

JSONExtractArrayRaw

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

構文

パラメータ

• json — 解析するJSON文字列。 String 。
• indices_or_keys — 文字列または整数のいずれかを指定できるゼロ個以上の引数のリスト。 String、 Int*。

indices_or_keys のタイプ：

• String = キーによってオブジェクトメンバーにアクセスします。
• Positive integer = 開始から n 番目のメンバー/キーにアクセスします。
• Negative integer = 終わりから n 番目のメンバー/キーにアクセスします。

戻り値

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

例

JSONExtractKeysAndValuesRaw

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

構文

引数

• json — 有効なJSONの String 。
• p, a, t, h — ネストされたJSONオブジェクト内のフィールドに到達するためのインデックスまたはキーを指定するカンマ区切りの引数。各引数はキーによってフィールドを取得するための string または N 番目のフィールドを取得するための integer であるべきです（1から始まるインデックス，負の整数は終了からカウントします）。設定しない場合、全体の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_EXISTS(path, json)

戻り値

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

例

クエリ：

結果：

JSON_VALUE

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

この関数は以下の設定によって制御されます：

• SET function_json_value_return_type_allow_nullable = true の場合、NULL が返されます。値が複雑な型（構造体、配列、マップなど）の場合、デフォルトで空文字列が返されます。
• SET 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).

例