Amazon Redshift は、パッチ 198 以降、新しい Python UDF の作成をサポートしなくなります。既存の Python UDF は、2026 年 6 月 30 日まで引き続き機能します。詳細については、[ブログ記事](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/)を参照してください。 # JSON 関数 **Topics** + [JSON\$1PARSE 関数](JSON_PARSE.md) + [CAN\$1JSON\$1PARSE 関数](CAN_JSON_PARSE.md) + [JSON\$1SERIALIZE 関数](JSON_SERIALIZE.md) + [JSON\$1SERIALIZE\$1TO\$1VARBYTE 関数](JSON_SERIALIZE_TO_VARBYTE.md) + [テキストベースの JSON 関数](text-json-functions.md) **注記** JSON を操作するには、次の関数を使用することをお勧めします。 [JSON\$1PARSE 関数](JSON_PARSE.md) [CAN\$1JSON\$1PARSE 関数](CAN_JSON_PARSE.md) [JSON\$1SERIALIZE 関数](JSON_SERIALIZE.md) [JSON\$1SERIALIZE\$1TO\$1VARBYTE 関数](JSON_SERIALIZE_TO_VARBYTE.md) JSON\$1PARSE では、取り込み時に JSON テキストを SUPER 型の値に 1 回変換するだけで済みます。その後は、SUPER 値に対して操作を行うことができます。Amazon Redshift は、テキストベースの JSON 関数の出力である VARCHAR よりも、SUPER 値をより効率的に解析します。SUPER データ型の操作の詳細については、「[Amazon Redshift の半構造化データ](super-overview.md)」を参照してください。 相対的に小さい一連のキーと値のペアを格納する必要がある場合は、データを JSON 形式で格納すると、スペースを節約できます。JSON 文字列は単一の列に格納できるため、データを表形式で格納するより、JSON を使用する方が効率的である可能性があります。例えば、スパース表があるとします。その表では、すべての属性を完全に表すために列が多数必要ですが、指定された行または指定された列のほとんどの列値が NULL であるとします。格納に JSON を使用することによって、行のデータを単一の JSON 文字列にキーと値のペアで格納できる可能性があり、格納データの少ない表の列を除去できる可能性があります。 さらに、JSON スキーマの変更時に、テーブルに列を追加することなく、JSON 文字列を簡単に変更して追加のキーと値のペアを保存できます。 JSON の使用は控えめにすることをお勧めします。JSON では、単一の列にさまざまなデータが保存され、Amazon Redshift の列保存アーキテクチャが使用されません。したがってこの形式は、大きいデータセットの保存には適していません。Amazon Redshift は CHAR 列と VARCHAR 列で JSON 関数をサポートしていますが、JSON のシリアル化形式でデータを処理するには、SUPER を使用することをお勧めします。SUPER では、階層データを効率的にクエリできる、ポスト解析スキーマレス表現が使用されています。SUPER データ型の詳細については、[Amazon Redshift の半構造化データ](super-overview.md)を参照してください。 JSON は UTF-8 でエンコードされたテキスト文字列を使用するため、JSON 文字列を CHAR データ型または VARCHAR データ型として格納できます。 JSON 文字列は、以下のルールに従って、正しくフォーマットされた JSON である必要があります。 + ルートレベルの JSON には、JSON オブジェクトまたは JSON 配列を使用できます。JSON オブジェクトは、順序が設定されていない一連のキーと値のペアがカンマで区切られ、中括弧で囲まれたものです。 例: `{"one":1, "two":2} ` + JSON 配列は、順序付けられた一連のカンマ区切り値が角括弧で囲まれたものです。 例は次のとおりです: `["first", {"one":1}, "second", 3, null] ` + JSON 配列は、0 から始まるインデックスを使用します。配列内の最初の要素の位置は 0 です。JSON のキーと値のペアでは、キーは二重引用符で囲まれた文字列です。 + JSON 値には次のいずれかを指定できます。 + JSON オブジェクト + array + string + 二重引用符で表される + 数値 + 整数、小数、浮動小数点数を含む + boolean + null + 空のオブジェクトおよび空の配列は、有効な JSON 値です。 + JSON フィールドでは、大文字と小文字が区別されます。 + JSON 構造要素 (`{ }, [ ]` など) は無視されます。 Amazon Redshift JSON 関数および Amazon Redshift COPY コマンドは、同じメソッドを使用して JSON 形式のデータを操作します。JSON の操作方法の詳細については、「[JSON 形式からの COPY](copy-usage_notes-copy-from-json.md)」を参照してください。 # JSON\$1PARSE 関数 JSON\$1PARSE 関数は、JSON 形式のデータを解析して、そのデータを `SUPER` 表現に変換します。 INSERT または UPDATE コマンドを使用して、データを `SUPER` 型として取り込むには、JSON\$1PARSE 関数を使用します。JSON\$1PARSE() を使用して JSON 文字列を `SUPER` 値に解析する場合、特定の制限が適用されます。詳細については、「[SUPER の解析オプション](super-configurations.md#parsing-options-super)」を参照してください。 ## 構文 ``` JSON_PARSE( {json_string | binary_value} ) ``` ## 引数 *json\$1string* シリアル化された JSON を `VARBYTE` 型または `VARCHAR` 型として返す式。 *binary\$1value* VARBYTE データ型のバイナリ値。 ## 戻り型 `SUPER` ## 例 JSON 配列 `[10001,10002,"abc"]` を `SUPER` データ型に変換するには、次の例を使用します。 ``` SELECT JSON_PARSE('[10001,10002,"abc"]'); +---------------------+ | json_parse | +---------------------+ | [10001,10002,"abc"] | +---------------------+ ``` 関数が JSON 配列を `SUPER` データ型に変換したことを確認するには、次の例を使用します。詳細については、[JSON\$1TYPEOF 関数](r_json_typeof.md)を参照してください。 ``` SELECT JSON_TYPEOF(JSON_PARSE('[10001,10002,"abc"]')); +-------------+ | json_typeof | +-------------+ | array | +-------------+ ``` # CAN\$1JSON\$1PARSE 関数 CAN\$1JSON\$1PARSE 関数は JSON 形式でデータを解析し、JSON\$1PARSE 関数を使用して結果を `SUPER` 値に変換できる場合は `true` を返します。 ## 構文 ``` CAN_JSON_PARSE( {json_string | binary_value} ) ``` ## 引数 *json\$1string* シリアル化された JSON を `VARCHAR` 形式で返す式。 *binary\$1value* VARBYTE データ型のバイナリ値。 ## 戻り型 `BOOLEAN` ## 使用に関する注意事項 + CAN\$1JSON\$1PARSE は空の文字列に対して false を返します。入力引数が null の場合は、NULL を返します。 ## 例 次の例は、CASE 条件を使用して適切に形成された JSON 配列に対する CAN\$1JSON\$1PARSE の実行を示しています。これは true を返すため、Amazon Redshift はサンプル値に対して JSON\$1PARSE 関数を実行します。 ``` SELECT CASE WHEN CAN_JSON_PARSE('[10001,10002,"abc"]') THEN JSON_PARSE('[10001,10002,"abc"]') END; case --------------------- '[10001,10002,"abc"]' ``` 次の例は、CASE 条件を使用して JSON 形式ではない値に対する CAN\$1JSON\$1PARSE の実行を示しています。これは false を返すため、Amazon Redshift は代わりに CASE 条件の ELSE 句でセグメントを返します。 ``` SELECT CASE WHEN CAN_JSON_PARSE('This is a string.') THEN JSON_PARSE('This is a string.') ELSE 'This is not JSON.' END; case --------------------- "This is not JSON." ``` # JSON\$1SERIALIZE 関数 JSON\$1SERIALIZE 関数は、RFC 8259 に従って、`SUPER` 式をテキスト JSON 表現でシリアル化します。詳細については、[The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259)を参照してください。 `SUPER` のサイズ制限はブロックでの制限とほぼ同じで、`VARCHAR` の制限は `SUPER` でのサイズ制限よりも小さくなっています。したがって、JSON 形式がシステムの VARCHAR 制限を超えると、JSON\$1SERIALIZE 関数はエラーを返します。`SUPER` 式のサイズを確認するには、[JSON\$1SIZE](r_json_size.md) 関数を参照してください。 ## 構文 ``` JSON_SERIALIZE(super_expression) ``` ## 引数 *super\$1expression* `SUPER` 式または列。 ## 戻り型 `VARCHAR` **注記** 返される VARCHAR 値は、常に null 以外の JSON 文字列になります。*super\$1expression* が NULL の場合、JSON\$1SERIALIZE は JSON 文字列 `'null'` を返します。 ## 例 `SUPER` 値を文字列にシリアル化するには、次の例を使用します。 ``` SELECT JSON_SERIALIZE(JSON_PARSE('[10001,10002,"abc"]')); +---------------------+ | json_serialize | +---------------------+ | [10001,10002,"abc"] | +---------------------+ ``` # JSON\$1SERIALIZE\$1TO\$1VARBYTE 関数 JSON\$1SERIALIZE\$1TO\$1VARBYTE 関数は、`SUPER` 値を JSON\$1SERIALIZE() と同様の JSON 文字列に変換しますが、この関数は `VARBYTE` 値に保存されます。 ## 構文 ``` JSON_SERIALIZE_TO_VARBYTE(super_expression) ``` ## 引数 *super\$1expression* `SUPER` 式または列。 ## 戻り型 `VARBYTE` ## 例 `SUPER` 値をシリアル化し、結果を `VARBYTE` 形式で返すには、次の例を使用します。 ``` SELECT JSON_SERIALIZE_TO_VARBYTE(JSON_PARSE('[10001,10002,"abc"]')); +----------------------------------------+ | json_serialize_to_varbyte | +----------------------------------------+ | 5b31303030312c31303030322c22616263225d | +----------------------------------------+ ``` `SUPER` 値をシリアル化し、結果を `VARCHAR` 形式にキャストするには、次の例を使用します。詳細については、「[CAST 関数](r_CAST_function.md)」を参照してください。 ``` SELECT CAST((JSON_SERIALIZE_TO_VARBYTE(JSON_PARSE('[10001,10002,"abc"]'))) AS VARCHAR); +---------------------------+ | json_serialize_to_varbyte | +---------------------------+ | [10001,10002,"abc"] | +---------------------------+ ``` # テキストベースの JSON 関数 このセクションの関数は、JSON 値を VARCHAR として解析します。JSON を解析するには、JSON 値を SUPER として解析する以下の関数を代わりに使用することをお勧めします。Amazon Redshift は、VARCHAR よりも SUPER 値をより効率的に解析します。 + [JSON\$1PARSE 関数](JSON_PARSE.md) + [CAN\$1JSON\$1PARSE 関数](CAN_JSON_PARSE.md) + [JSON\$1SERIALIZE 関数](JSON_SERIALIZE.md) + [JSON\$1SERIALIZE\$1TO\$1VARBYTE 関数](JSON_SERIALIZE_TO_VARBYTE.md) **Topics** + [IS\$1VALID\$1JSON 関数](IS_VALID_JSON.md) + [IS\$1VALID\$1JSON\$1ARRAY 関数](IS_VALID_JSON_ARRAY.md) + [JSON\$1ARRAY\$1LENGTH 関数](JSON_ARRAY_LENGTH.md) + [JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT 関数](JSON_EXTRACT_ARRAY_ELEMENT_TEXT.md) + [JSON\$1EXTRACT\$1PATH\$1TEXT 関数](JSON_EXTRACT_PATH_TEXT.md) # IS\$1VALID\$1JSON 関数 **注記** CAN\$1JSON\$1PARSE および関連する関数は、JSON 値を SUPER として解析します。Amazon Redshift は、VARCHAR よりも SUPER をより効率的に解析します。 IS\$1VALID\$1JSON を使用する代わりに、[CAN\$1JSON\$1PARSE 関数](CAN_JSON_PARSE.md) を使用して JSON 文字列を検証することをお勧めします。 IS\$1VALID\$1JSON 関数は、JSON 文字列を確認します。この関数は、文字列が正しい JSON 形式になっている場合、`true` のブール値を返し、正しい形式ではない場合は、`false` を返します。JSON 配列を検証するには、[IS\$1VALID\$1JSON\$1ARRAY 関数](IS_VALID_JSON_ARRAY.md)を使用します。 詳細については、「[JSON 関数](json-functions.md)」を参照してください。 ## 構文 ``` IS_VALID_JSON('json_string') ``` ## 引数 *json\$1string* 評価して JSON 文字列を返す文字列または式。 ## 戻り型 `BOOLEAN` ## 例 テーブルを作成し、テスト用の JSON 文字列を挿入するには、次の例を使用します。 ``` CREATE TABLE test_json(id int IDENTITY(0,1), json_strings VARCHAR); -- Insert valid JSON strings -- INSERT INTO test_json(json_strings) VALUES ('{"a":2}'), ('{"a":{"b":{"c":1}}}'), ('{"a": [1,2,"b"]}'); -- Insert invalid JSON strings -- INSERT INTO test_json(json_strings) VALUES ('{{}}'), ('{1:"a"}'), ('[1,2,3]'); ``` 前の例の文字列を検証するには、次の例を使用します。 ``` SELECT id, json_strings, IS_VALID_JSON(json_strings) FROM test_json ORDER BY id; +----+---------------------+---------------+ | id | json_strings | is_valid_json | +----+---------------------+---------------+ | 0 | {"a":2} | true | | 4 | {"a":{"b":{"c":1}}} | true | | 8 | {"a": [1,2,"b"]} | true | | 12 | {{}} | false | | 16 | {1:"a"} | false | | 20 | [1,2,3] | false | +----+---------------------+---------------+ ``` # IS\$1VALID\$1JSON\$1ARRAY 関数 **注記** JSON\$1PARSE および関連する関数は、JSON 値を SUPER として解析します。Amazon Redshift は、VARCHAR よりも SUPER をより効率的に解析します。 IS\$1VALID\$1JSON\$1ARRAY を使用する代わりに、[JSON\$1PARSE 関数](JSON_PARSE.md) を使用して JSON 文字列を解析し、SUPER 値を取得することをお勧めします。次に、[IS\$1ARRAY 関数](r_is_array.md) 関数を使用して、配列が適切に形成されていることを確認します。 IS\$1VALID\$1JSON\$1ARRAY 関数は、JSON 配列を確認します。この関数は、配列が正しい JSON 形式になっている場合、`true` のブール値を返し、正しい形式ではない場合は、`false` を返します。JSON 文字列を検証するには、[IS\$1VALID\$1JSON 関数](IS_VALID_JSON.md)を使用します。 詳細については、「[JSON 関数](json-functions.md)」を参照してください。 ## 構文 ``` IS_VALID_JSON_ARRAY('json_array') ``` ## 引数 *json\$1array* 評価して JSON 配列を返す文字列または式。 ## 戻り型 `BOOLEAN` ## 例 テーブルを作成し、テスト用の JSON 文字列を挿入するには、次の例を使用します。 ``` CREATE TABLE test_json_arrays(id int IDENTITY(0,1), json_arrays VARCHAR); -- Insert valid JSON array strings -- INSERT INTO test_json_arrays(json_arrays) VALUES('[]'), ('["a","b"]'), ('["a",["b",1,["c",2,3,null]]]'); -- Insert invalid JSON array strings -- INSERT INTO test_json_arrays(json_arrays) VALUES('{"a":1}'), ('a'), ('[1,2,]'); ``` 前の例の文字列を検証するには、次の例を使用します。 ``` SELECT json_arrays, IS_VALID_JSON_ARRAY(json_arrays) FROM test_json_arrays ORDER BY id; +------------------------------+---------------------+ | json_arrays | is_valid_json_array | +------------------------------+---------------------+ | [] | true | | ["a","b"] | true | | ["a",["b",1,["c",2,3,null]]] | true | | {"a":1} | false | | a | false | | [1,2,] | false | +------------------------------+---------------------+ ``` # JSON\$1ARRAY\$1LENGTH 関数 **注記** JSON\$1PARSE および関連する関数は、JSON 値を SUPER として解析します。Amazon Redshift は、VARCHAR よりも SUPER をより効率的に解析します。 JSON\$1ARRAY\$1LENGTH を使用する代わりに、[JSON\$1PARSE 関数](JSON_PARSE.md) を使用して JSON 文字列を解析し、SUPER 値を取得することをお勧めします。次に、[GET\$1ARRAY\$1LENGTH 関数](get_array_length.md) を使用して配列の長さを取得します。 JSON\$1ARRAY\$1LENGTH 関数は、JSON 文字列の外部配列内の要素数を返します。*null\$1if\$1invalid* の引数が `true` に設定され、JSON 文字列が無効になっている場合、この関数はエラーを返す代わりに `NULL` を返します。 詳細については、「[JSON 関数](json-functions.md)」を参照してください。 ## 構文 ``` JSON_ARRAY_LENGTH('json_array' [, null_if_invalid ] ) ``` ## 引数 *json\$1array* 正しくフォーマットされた JSON 配列。 *null\$1if\$1invalid* (オプション) 入力 JSON 文字列が無効である場合に、エラーを返す代わりに `NULL` を返すかどうかを指定する `BOOLEAN` 値。JSON が無効な場合に `NULL` を返すには、`true` (`t`) を指定します。JSON が無効な場合にエラーを返すには、`false` (`f`) を指定します。デフォルトは `false` です。 ## 戻り型 `INTEGER` ## 例 配列内の要素数を返すには、次の例を使用します。 ``` SELECT JSON_ARRAY_LENGTH('[11,12,13,{"f1":21,"f2":[25,26]},14]'); +-------------------+ | json_array_length | +-------------------+ | 5 | +-------------------+ ``` JSON が無効であるためエラーを返すには、次の例を使用します。 ``` SELECT JSON_ARRAY_LENGTH('[11,12,13,{"f1":21,"f2":[25,26]},14'); ERROR: invalid json array object [11,12,13,{"f1":21,"f2":[25,26]},14 ``` *null\$1if\$1invalid* を *true* に設定し、ステートメントが無効な JSON のエラーを返す代わりに `NULL` を返すようにするには、次の例を使用します。 ``` SELECT JSON_ARRAY_LENGTH('[11,12,13,{"f1":21,"f2":[25,26]},14',true); +-------------------+ | json_array_length | +-------------------+ | NULL | +-------------------+ ``` # JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT 関数 **注記** JSON\$1PARSE および関連する関数は、JSON 値を SUPER として解析します。Amazon Redshift は、VARCHAR よりも SUPER をより効率的に解析します。 JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT を使用する代わりに、[JSON\$1PARSE 関数](JSON_PARSE.md) を使用して JSON 文字列を解析し、SUPER 値を取得することをお勧めします。次に、`value[element position]` 構文を使用し、必要とする配列インデックスが含まれている要素をクエリします。SUPER 値の配列要素に対するクエリ実行の詳細については、「[半構造化データのクエリ](query-super.md)」を参照してください。 JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT 関数は、JSON 文字列の最外部の配列内の JSON 配列要素 (0 から始まるインデックスを使用) を返します。配列内の最初の要素の位置は 0 です。インデックスが負または範囲外である場合、JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT は `NULL` 文字列を返します。*null\$1if\$1invalid* の引数が `TRUE` に設定され、JSON 文字列が無効になっている場合、この関数はエラーを返す代わりに `NULL` を返します。 詳細については、「[JSON 関数](json-functions.md)」を参照してください。 ## 構文 ``` JSON_EXTRACT_ARRAY_ELEMENT_TEXT('json string', pos [, null_if_invalid ] ) ``` ## 引数 *json\$1string* 正しくフォーマットされた JSON 文字列。 *pos* 返される配列要素のインデックスを表す `INTEGER` (0 から始まる配列インデックスを使用)。 *null\$1if\$1invalid* (オプション) 入力 JSON 文字列が無効である場合に、エラーを返す代わりに `NULL` を返すかどうかを指定する `BOOLEAN` 値。JSON が無効な場合に `NULL` を返すには、`true` (`t`) を指定します。JSON が無効な場合にエラーを返すには、`false` (`f`) を指定します。デフォルトは `false` です。 ## 戻り型 `VARCHAR` *pos* によって参照される JSON 配列要素を表す `VARCHAR` 文字列。 ## 例 配列の位置 2 の要素 (0 から始まる配列インデックスの 3 番目の要素) を返すには、次の例を使用します。 ``` SELECT JSON_EXTRACT_ARRAY_ELEMENT_TEXT('[111,112,113]', 2); +---------------------------------+ | json_extract_array_element_text | +---------------------------------+ | 113 | +---------------------------------+ ``` JSON が無効であるためエラーを返すには、次の例を使用します。 ``` SELECT JSON_EXTRACT_ARRAY_ELEMENT_TEXT('["a",["b",1,["c",2,3,null,]]]',1); ERROR: invalid json array object ["a",["b",1,["c",2,3,null,]]] ``` *null\$1if\$1invalid* を *true* に設定し、ステートメントが無効な JSON のエラーを返す代わりに `NULL` を返すようにするには、次の例を使用します。 ``` SELECT JSON_EXTRACT_ARRAY_ELEMENT_TEXT('["a",["b",1,["c",2,3,null,]]]',1,true); +---------------------------------+ | json_extract_array_element_text | +---------------------------------+ | NULL | +---------------------------------+ ``` 次のステートメントサンプルについて考えてみます。指定された JSON 文字列またはインデックスが NULL の場合、JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT は他のパラメータの値を問わず、NULL を返します。 ``` --Statement where json_string is NULL. SELECT json_extract_array_element_text(NULL, 0) json_extract_array_element_text --------------------------------- NULL --Statement where pos is NULL and json_string is invalid JSON. SELECT json_extract_array_element_text('invalid_json', NULL); json_extract_array_element_text --------------------------------- NULL --Statement where json_string is NULL and null_if_invalid is FALSE. SELECT json_extract_array_element_text(NULL, 0, FALSE); json_extract_array_element_text --------------------------------- NULL ``` 次のステートメントサンプルについて考えてみます。*null\$1if\$1invalid* が TRUE の場合、*json\$1string* が無効な JSON であれば、JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT は NULL を返します。*null\$1if\$1invalid* が FALSE であったり、設定されていなかったりする場合、*json\$1string* が無効であれば、この関数はエラーを返します。 ``` --Statement with invalid JSON where null_if_invalid is TRUE. SELECT json_extract_array_element_text('invalid_json', 0, TRUE); json_extract_array_element_text --------------------------------- NULL --Statement with invalid JSON where null_if_invalid is FALSE. SELECT json_extract_array_element_text('invalid_json', 0); ERROR: JSON parsing error ``` *json\$1string* が有効な JSON で、*pos* が JSON `null` 値を参照する、次の例について考えてみます。この場合、JSON\$1EXTRACT\$1ARRAY\$1ELEMENT\$1TEXT は、*null\$1if\$1invalid* の値を問わず、NULL を返します。 ``` --Statement selecting a null value. SELECT json_extract_array_element_text('[null]', 0); json_extract_array_element_text ---------------------------------- NULL ``` # JSON\$1EXTRACT\$1PATH\$1TEXT 関数 **注記** JSON\$1PARSE および関連する関数は、JSON 値を SUPER として解析します。Amazon Redshift は、VARCHAR よりも SUPER をより効率的に解析します。 JSON\$1EXTRACT\$1PATH\$1TEXT を使用する代わりに、[JSON\$1PARSE 関数](JSON_PARSE.md) を使用して JSON 文字列を解析し、SUPER 値を取得することをお勧めします。次に、`value.attribute` 構文を使用する対象の要素をクエリします。SUPER 値の配列要素に対するクエリ実行の詳細については、「[半構造化データのクエリ](query-super.md)」を参照してください。 JSON\$1EXTRACT\$1PATH\$1TEXT 関数は、JSON 文字列内の一連のパス要素から参照されるキーと値のペアを値として返します。JSON パスは、最大 5 レベルの深さまでネストできます。パス要素では、大文字と小文字が区別されます。JSON 文字列にパス要素が存在しない場合、JSON\$1EXTRACT\$1PATH\$1TEXT は `NULL` を返します。 *null\$1if\$1invalid* の引数が `TRUE` に設定され、JSON 文字列が無効になっている場合、この関数はエラーを返す代わりに `NULL` を返します。 JSON\$1EXTRACT\$1PATH\$1TEXT のデータサイズは最大 64 KB です。JSON レコードのサイズが 64 KB を超えると、JSON\$1EXTRACT\$1PATH\$1TEXT での処理エラーになります。 その他の JSON 関数については、「[JSON 関数](json-functions.md)」を参照してください。JSON の操作方法の詳細については、「[JSON 形式からの COPY](copy-usage_notes-copy-from-json.md)」を参照してください。 ## 構文 ``` JSON_EXTRACT_PATH_TEXT('json_string', 'path_elem' [,'path_elem'[, …] ] [, null_if_invalid ] ) ``` ## 引数 *json\$1string* 正しくフォーマットされた JSON 文字列。 *path\$1elem* JSON 文字列内のパス要素。1 つのパス要素が必要です。パス要素は、最大 5 レベルの深さまで、追加で指定できます。 *null\$1if\$1invalid* (オプション) 入力 JSON 文字列が無効である場合に、エラーを返す代わりに `NULL` を返すかどうかを指定する `BOOLEAN` 値。JSON が無効な場合に `NULL` を返すには、`TRUE` (`t`) を指定します。JSON が無効な場合にエラーを返すには、`FALSE` (`f`) を指定します。デフォルトは `FALSE` です。 JSON 文字列では、Amazon Redshift は `\n` を改行文字として、`\t` をタブ文字として認識します。バックスラッシュをロードするには、バックスラッシュをバックスラッシュでエスケープします (`\\`)。詳細については、「[JSON のエスケープ文字](copy-usage_notes-copy-from-json.md#copy-usage-json-escape-characters)」を参照してください。 ## 戻り型 `VARCHAR` パス要素から参照される JSON 値を表す `VARCHAR` 文字列。 ## 例 パス `'f4', 'f6'` の値を返すには、次の例を使用します。 ``` SELECT JSON_EXTRACT_PATH_TEXT('{"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}}','f4', 'f6'); +------------------------+ | json_extract_path_text | +------------------------+ | star | +------------------------+ ``` JSON が無効であるためエラーを返すには、次の例を使用します。 ``` SELECT JSON_EXTRACT_PATH_TEXT('{"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}','f4', 'f6'); ERROR: invalid json object {"f2":{"f3":1},"f4":{"f5":99,"f6":"star"} ``` *null\$1if\$1invalid* を *TRUE* に設定し、ステートメントがエラーを返す代わりに `NULL` を返すようにするには、次の例を使用します。 ``` SELECT JSON_EXTRACT_PATH_TEXT('{"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}','f4', 'f6',true); +------------------------+ | json_extract_path_text | +------------------------+ | NULL | +------------------------+ ``` `'farm', 'barn', 'color'` のパスの値を選択する次の例を考えてみます。取得される値は 3 番目のレベルにあります。次の例を使用します。読みやすくするために、このサンプルは JSON Lint ツールを使用してフォーマットされています。 ``` SELECT JSON_EXTRACT_PATH_TEXT('{ "farm": { "barn": { "color": "red", "feed stocked": true } } }', 'farm', 'barn', 'color'); +------------------------+ | json_extract_path_text | +------------------------+ | red | +------------------------+ ``` `'color'` 要素がないため `NULL` を返すには、次の例を使用します。このサンプルは JSON Lint ツールでフォーマットされています。 ``` SELECT JSON_EXTRACT_PATH_TEXT('{ "farm": { "barn": {} } }', 'farm', 'barn', 'color'); +------------------------+ | json_extract_path_text | +------------------------+ | NULL | +------------------------+ ``` JSON が有効な場合、欠落している要素を抽出しようとすると `NULL` が返されます。 パス `'house', 'appliances', 'washing machine', 'brand'` の値を返すには、次の例を使用します。 ``` SELECT JSON_EXTRACT_PATH_TEXT('{ "house": { "address": { "street": "123 Any St.", "city": "Any Town", "state": "FL", "zip": "32830" }, "bathroom": { "color": "green", "shower": true }, "appliances": { "washing machine": { "brand": "Any Brand", "color": "beige" }, "dryer": { "brand": "Any Brand", "color": "white" } } } }', 'house', 'appliances', 'washing machine', 'brand'); +------------------------+ | json_extract_path_text | +------------------------+ | Any Brand | +------------------------+ ``` 次の例は、サンプルテーブルを作成し、SUPER 値を入力して、両方の行の `'f2'` パスの値を返します。 ``` CREATE TABLE json_example(id INT, json_text SUPER); INSERT INTO json_example VALUES (1, JSON_PARSE('{"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}}')), (2, JSON_PARSE('{ "farm": { "barn": { "color": "red", "feed stocked": true } } }')); SELECT * FROM json_example; id | json_text ------------+-------------------------------------------- 1 | {"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}} 2 | {"farm":{"barn":{"color":"red","feed stocked":true}}} SELECT id, JSON_EXTRACT_PATH_TEXT(JSON_SERIALIZE(json_text), 'f2') FROM json_example; id | json_text ------------+-------------------------------------------- 1 | {"f3":1} 2 | ``` 次のステートメントサンプルについて考えてみます。指定された *path\$1elem* が NULL であるため、JSON\$1EXTRACT\$1PATH\$1TEXT は他のパラメータの値を問わず、NULL を返します。 ``` --Statement where path_elem is NULL and json_string is valid JSON. SELECT JSON_EXTRACT_PATH_TEXT('{"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}}',NULL); json_extract_path_text ------------------------ NULL --Statement where only one path_elem is NULL. SELECT JSON_EXTRACT_PATH_TEXT('{"f2":{"f3":1},"f4":{"f5":99,"f6":"star"}}','f4',NULL); json_extract_path_text ------------------------ NULL --Statement where path_elem is NULL and json_string is invalid JSON. SELECT json_extract_path_text('invalid_json', NULL); json_extract_path_text ------------------------ NULL --Statement where path_elem is NULL and null_if_invalid is FALSE. SELECT json_extract_path_text(NULL, 0, FALSE); json_extract_path_text ------------------------ NULL ``` 次のステートメントサンプルについて考えてみます。*null\$1if\$1invalid* が TRUE の場合、*json\$1string* が無効な JSON であれば、JSON\$1EXTRACT\$1PATH\$1TEXT は NULL を返します。*null\$1if\$1invalid* が FALSE であったり、設定されていなかったりする場合、*json\$1string* が無効であれば、この関数はエラーを返します。 ``` --Statement with invalid JSON where null_if_invalid is TRUE. SELECT json_extract_path_text('invalid_json', 0, TRUE); json_extract_path_text ------------------------ NULL --Statement with invalid JSON where null_if_invalid is FALSE. SELECT json_extract_path_text('invalid_json', 0, FALSE); ERROR: JSON parsing error ``` *json\$1string* が有効な JSON で、*path\$1elem* が JSON `null` 値を参照する、次の例について考えてみます。この場合、JSON\$1EXTRACT\$1PATH\$1TEXT は NULL を返します。同様に、*path\$1elem* が存在しない値を参照する場合、JSON\$1EXTRACT\$1PATH\$1TEXT は *null\$1if\$1invalid* の値を問わず、NULL を返します。 ``` --Statement selecting a null value. SELECT json_extract_path_text('[null]', 0); json_extract_path_text ------------------------- NULL --Statement selecting a non-existing value. SELECT json_extract_path_text('{}', 'a'); json_extract_path_text ------------------------- NULL ```