構造化・半構造化関数
TiDB Cloud Lake の構造化関数および半構造化関数を使用すると、配列、オブジェクト、マップ、JSON、その他の構造化データ形式を効率的に処理できます。これらの関数は、構造化データおよび半構造化データの作成、解析、クエリ、変換、操作のための包括的な機能を提供します。
JSON 関数
解析と検証
| 関数 | 説明 | 例 |
|---|---|---|
| PARSE_JSON | JSON 文字列を variant 値に解析します | PARSE_JSON('[1,2,3]') |
| CHECK_JSON | 文字列が有効な JSON かどうかを検証します | CHECK_JSON('{"a":1}') |
| JSON_TYPEOF | JSON 値の型を返します | JSON_TYPEOF(PARSE_JSON('[1,2,3]')) |
パスベースのクエリ
| 関数 | 説明 | 例 |
|---|---|---|
| JSON_PATH_EXISTS | JSON パスが存在するかどうかを確認します | JSON_PATH_EXISTS(json_obj, '$.name') |
| JSON_PATH_QUERY | JSONPath を使用して JSON データをクエリします | JSON_PATH_QUERY(json_obj, '$.items[*]') |
| JSON_PATH_QUERY_ARRAY | JSON データをクエリし、結果を配列として返します | JSON_PATH_QUERY_ARRAY(json_obj, '$.items') |
| JSON_PATH_QUERY_FIRST | JSON パスクエリの最初の結果を返します | JSON_PATH_QUERY_FIRST(json_obj, '$.items[*]') |
| JSON_PATH_MATCH | JSON 値をパスパターンに照合します | JSON_PATH_MATCH(json_obj, '$.age') |
| JQ | jq 構文を使用して高度な JSON 処理を行います | JQ('.name', json_obj) |
値の抽出
| 関数 | 説明 | 例 |
|---|---|---|
| GET | JSON オブジェクトからキーで、または配列からインデックスで値を取得します | GET(PARSE_JSON('[1,2,3]'), 0) |
| GET_PATH | パス式を使用して JSON オブジェクトから値を取得します | GET_PATH(json_obj, 'user.name') |
| GET_IGNORE_CASE | 大文字と小文字を区別しないキー照合で値を取得します | GET_IGNORE_CASE(json_obj, 'NAME') |
| JSON_EXTRACT_PATH_TEXT | パスを使用して JSON からテキスト値を抽出します | JSON_EXTRACT_PATH_TEXT(json_obj, 'name') |
変換と出力
| 関数 | 説明 | 例 |
|---|---|---|
| JSON_TO_STRING | JSON 値を文字列に変換します | JSON_TO_STRING(PARSE_JSON('{"a":1}')) |
| JSON_PRETTY | JSON を適切なインデントで整形します | JSON_PRETTY(PARSE_JSON('{"a":1}')) |
| STRIP_NULL_VALUE | JSON の null 値を SQL の NULL 値に変換します | STRIP_NULL_VALUE(parse_json('null')) → NULL |
| JSON_STRIP_NULLS | JSON オブジェクトから null 値を削除します | JSON_STRIP_NULLS(PARSE_JSON('{"a":1,"b":null}')) → {"a":1} |
配列/オブジェクトの展開
| 関数 | 説明 | 例 |
|---|---|---|
| JSON_EACH | JSON オブジェクトをキーと値のペアに展開します | JSON_EACH(PARSE_JSON('{"a":1,"b":2}')) |
| JSON_ARRAY_ELEMENTS | JSON 配列を個々の要素に展開します | JSON_ARRAY_ELEMENTS(PARSE_JSON('[1,2,3]')) |
配列関数
| 関数 | 説明 | 例 |
|---|---|---|
| ARRAY | 式から配列を構築します | ARRAY(1, 2, 3) |
| ARRAY_CONSTRUCT | 個々の値から配列を作成します | ARRAY_CONSTRUCT(1, 2, 3) |
| RANGE | 連続した数値の配列を生成します | RANGE(1, 5) |
| ARRAY_GENERATE_RANGE | オプションのステップ付きでシーケンスを生成します | ARRAY_GENERATE_RANGE(0, 6, 2) |
| GET | インデックスで配列から要素を取得します | GET([1,2,3], 0) |
| ARRAY_GET | GET 関数のエイリアスです | ARRAY_GET([1,2,3], 1) |
| CONTAINS | 配列に特定の値が含まれているかどうかを確認します | CONTAINS([1,2,3], 2) |
| ARRAY_CONTAINS | 配列に特定の値が含まれているかどうかを確認します | ARRAY_CONTAINS([1,2,3], 2) |
| ARRAY_SIZE | 配列の長さを返します（エイリアス: ARRAY_LENGTH） | ARRAY_SIZE([1,2,3]) |
| ARRAY_COUNT | NULL ではない要素の数を数えます | ARRAY_COUNT([1,NULL,2]) |
| ARRAY_ANY | 最初の非 NULL エントリを返します | ARRAY_ANY([NULL,'a','b']) |
| ARRAY_APPEND | 配列の末尾に要素を追加します | ARRAY_APPEND([1,2], 3) |
| ARRAY_PREPEND | 配列の先頭に要素を追加します | ARRAY_PREPEND([2,3], 1) |
| ARRAY_INSERT | 指定した位置に要素を挿入します | ARRAY_INSERT([1,3], 1, 2) |
| ARRAY_REMOVE | 指定した要素のすべての出現を削除します | ARRAY_REMOVE([1,2,2,3], 2) |
| ARRAY_REMOVE_FIRST | 配列の最初の要素を削除します | ARRAY_REMOVE_FIRST([1,2,3]) |
| ARRAY_REMOVE_LAST | 配列の最後の要素を削除します | ARRAY_REMOVE_LAST([1,2,3]) |
| ARRAY_CONCAT | 複数の配列を連結します | ARRAY_CONCAT([1,2], [3,4]) |
| ARRAY_SLICE | 配列の一部を抽出します | ARRAY_SLICE([1,2,3,4], 1, 2) |
| SLICE | ARRAY_SLICE 関数のエイリアスです | SLICE([1,2,3,4], 1, 2) |
| ARRAYS_ZIP | 複数の配列を要素ごとに結合します | ARRAYS_ZIP([1,2], ['a','b']) |
| ARRAY_DISTINCT | 配列から一意な要素を返します | ARRAY_DISTINCT([1,2,2,3]) |
| ARRAY_UNIQUE | ARRAY_DISTINCT 関数のエイリアスです | ARRAY_UNIQUE([1,2,2,3]) |
| ARRAY_INTERSECTION | 配列間の共通要素を返します | ARRAY_INTERSECTION([1,2,3], [2,3,4]) |
| ARRAY_EXCEPT | 1 つ目の配列にあり 2 つ目の配列にない要素を返します | ARRAY_EXCEPT([1,2,3], [2,3]) |
| ARRAY_OVERLAP | 配列に共通要素があるかどうかを確認します | ARRAY_OVERLAP([1,2], [2,3]) |
| ARRAY_TRANSFORM | 各配列要素に関数を適用します | ARRAY_TRANSFORM([1,2,3], x -> x * 2) |
| ARRAY_FILTER | 条件に基づいて配列要素をフィルタリングします | ARRAY_FILTER([1,2,3,4], x -> x > 2) |
| ARRAY_REDUCE | 集計を使用して配列を単一の値に縮約します | ARRAY_REDUCE([1,2,3], 0, (acc, x) -> acc + x) |
| ARRAY_AGGREGATE | 関数を使用して配列要素を集計します | ARRAY_AGGREGATE([1,2,3], 'sum') |
| ARRAY_SUM | 数値の合計を返します | ARRAY_SUM([1,2,3]) |
| ARRAY_AVG | 数値の平均を返します | ARRAY_AVG([1,2,3]) |
| ARRAY_MEDIAN | 数値の中央値を返します | ARRAY_MEDIAN([1,3,2]) |
| ARRAY_MIN | 最小値を返します | ARRAY_MIN([1,2,3]) |
| ARRAY_MAX | 最大値を返します | ARRAY_MAX([1,2,3]) |
| ARRAY_STDDEV_POP | 母標準偏差を返します | ARRAY_STDDEV_POP([1,2,3]) |
| ARRAY_STDDEV_SAMP | 標本標準偏差を返します | ARRAY_STDDEV_SAMP([1,2,3]) |
| ARRAY_KURTOSIS | 過剰尖度を返します | ARRAY_KURTOSIS([1,2,3,4]) |
| ARRAY_SKEWNESS | 歪度を返します | ARRAY_SKEWNESS([1,2,3,10]) |
| ARRAY_APPROX_COUNT_DISTINCT | 重複を除いた件数の近似値を返します | ARRAY_APPROX_COUNT_DISTINCT([1,1,2]) |
| ARRAY_SORT | 値をソートします。バリアントにより順序や null の扱いを制御します | ARRAY_SORT([3,1,2]) |
| ARRAY_TO_STRING | 配列要素を連結します | ARRAY_TO_STRING(['a','b'], ',') |
| ARRAY_COMPACT | 配列から null 値を削除します | ARRAY_COMPACT([1, NULL, 2, NULL, 3]) |
| ARRAY_FLATTEN | ネストした配列を 1 つの配列に平坦化します | ARRAY_FLATTEN([[1,2], [3,4]]) |
| ARRAY_REVERSE | 配列要素の順序を反転します | ARRAY_REVERSE([1,2,3]) |
| ARRAY_INDEXOF | 要素が最初に出現するインデックスを返します | ARRAY_INDEXOF([1,2,3,2], 2) |
| UNNEST | 配列を個々の行に展開します | UNNEST([1,2,3]) |
オブジェクト関数
| 関数 | 説明 | 例 |
|---|---|---|
| OBJECT_CONSTRUCT | キーと値のペアから JSON オブジェクトを作成します | OBJECT_CONSTRUCT('name', 'John', 'age', 30) |
| OBJECT_CONSTRUCT_KEEP_NULL | null 値を保持したまま JSON オブジェクトを作成します | OBJECT_CONSTRUCT_KEEP_NULL('a', 1, 'b', NULL) |
| OBJECT_KEYS | JSON オブジェクトのすべてのキーを配列として返します | OBJECT_KEYS(PARSE_JSON('{"a":1,"b":2}')) |
| OBJECT_INSERT | JSON オブジェクトにキーと値のペアを挿入または更新します | OBJECT_INSERT(json_obj, 'new_key', 'value') |
| OBJECT_DELETE | JSON オブジェクトからキーと値のペアを削除します | OBJECT_DELETE(json_obj, 'key_to_remove') |
| OBJECT_PICK | 指定したキーのみを含む新しいオブジェクトを作成します | OBJECT_PICK(json_obj, 'name', 'age') |
マップ関数
| 関数 | 説明 | 例 |
|---|---|---|
| MAP_CAT | 複数のマップを 1 つのマップに結合します | MAP_CAT({'a':1}, {'b':2}) |
| MAP_KEYS | マップのすべてのキーを配列として返します | MAP_KEYS({'a':1, 'b':2}) |
| MAP_VALUES | マップのすべての値を配列として返します | MAP_VALUES({'a':1, 'b':2}) |
| MAP_SIZE | マップ内のキーと値のペア数を返します | MAP_SIZE({'a':1, 'b':2}) |
| MAP_CONTAINS_KEY | マップに特定のキーが含まれているかどうかを確認します | MAP_CONTAINS_KEY({'a':1}, 'a') |
| MAP_INSERT | マップにキーと値のペアを挿入します | MAP_INSERT({'a':1}, 'b', 2) |
| MAP_DELETE | マップからキーと値のペアを削除します | MAP_DELETE({'a':1, 'b':2}, 'b') |
| MAP_TRANSFORM_KEYS | マップ内の各キーに関数を適用します | MAP_TRANSFORM_KEYS(map, k -> UPPER(k)) |
| MAP_TRANSFORM_VALUES | マップ内の各値に関数を適用します | MAP_TRANSFORM_VALUES(map, v -> v * 2) |
| MAP_FILTER | 述語に基づいてキーと値のペアをフィルタリングします | MAP_FILTER(map, (k, v) -> v > 10) |
| MAP_PICK | 指定したキーのみを含む新しいマップを作成します | MAP_PICK({'a':1, 'b':2, 'c':3}, 'a', 'c') |
型変換関数
| 関数 | 説明 | 例 |
|---|---|---|
| AS_BOOLEAN | VARIANT 値を BOOLEAN に変換します | AS_BOOLEAN(PARSE_JSON('true')) |
| AS_INTEGER | VARIANT 値を BIGINT に変換します | AS_INTEGER(PARSE_JSON('42')) |
| AS_FLOAT | VARIANT 値を DOUBLE に変換します | AS_FLOAT(PARSE_JSON('3.14')) |
| AS_DECIMAL | VARIANT 値を DECIMAL に変換します | AS_DECIMAL(PARSE_JSON('12.34')) |
| AS_STRING | VARIANT 値を STRING に変換します | AS_STRING(PARSE_JSON('"hello"')) |
| AS_BINARY | VARIANT 値を BINARY に変換します | AS_BINARY(TO_BINARY('abcd')::VARIANT) |
| AS_DATE | VARIANT 値を DATE に変換します | AS_DATE(TO_DATE('2025-10-11')::VARIANT) |
| AS_ARRAY | VARIANT 値を ARRAY に変換します | AS_ARRAY(PARSE_JSON('[1,2,3]')) |
| AS_OBJECT | VARIANT 値を OBJECT に変換します | AS_OBJECT(PARSE_JSON('{"a":1}')) |
型述語関数
| 関数 | 説明 | 例 |
|---|---|---|
| IS_ARRAY | JSON 値が配列かどうかを確認します | IS_ARRAY(PARSE_JSON('[1,2,3]')) |
| IS_OBJECT | JSON 値がオブジェクトかどうかを確認します | IS_OBJECT(PARSE_JSON('{"a":1}')) |
| IS_STRING | JSON 値が文字列かどうかを確認します | IS_STRING(PARSE_JSON('"hello"')) |
| IS_INTEGER | JSON 値が整数かどうかを確認します | IS_INTEGER(PARSE_JSON('42')) |
| IS_FLOAT | JSON 値が浮動小数点数かどうかを確認します | IS_FLOAT(PARSE_JSON('3.14')) |
| IS_BOOLEAN | JSON 値がブール値かどうかを確認します | IS_BOOLEAN(PARSE_JSON('true')) |
| IS_NULL_VALUE | JSON 値が null かどうかを確認します | IS_NULL_VALUE(PARSE_JSON('null')) |