JSON_COMPOSE

Teradata® Database JSONデータ型

brand
Software
prodname
Teradata Database
vrm_release
16.20
category
プログラミング リファレンス
featnum
B035-1150-162K-JPN

目的

JSON_COMPOSEは、指定した入力パラメータで構成されるJSON文書を作成します。この関数は、JSON_AGG関数と同時に使用することにより、JSON文書の複雑な構成を提供します。

構文



RETURNS句を指定した場合、関数呼び出しを括弧で囲む必要があります。





構文要素

param
何らかの値に評価される列参照、定数、または式にすることができる入力パラメータ。可変個のパラメータが許可され、各入力パラメータは、返されるJSON文書で名前と値のペアになります。
LOB属性を入力として、構造化されたUDTを使用できません。
FORMAT 'format string'
format stringは、Teradataで許可される任意の書式設定文字列です。
format stringの使用例については、例: SUBQUERYとGROUP BYによるJSON_COMPOSEの使用を参照してください。
AS name
nameは、Teradataで許可される任意の名前です。
作成される文字列はJSON標準エスケープ スキームに準拠します。UNICODE文字のサブセットは、'\'文字によってエスケープする必要があります。これは、Teradataの文字列には当てはまりません。したがって、Teradata文字列をJSON文字列に移植する場合は、必要に応じて適切なJSONエスケープ文字が使用されます。これは、JSONインスタンスの値およびJSON_AGG関数にも適用されます。文字セットがLATINの場合、'\'エスケープ文字はその文字セットに含まれる必要があります。そうしなければ、構文エラーが報告されます。
RETURNS data_type
data_typeが関数の戻り型になるように指定します。
この関数のdata_typeはJSONにする必要があります。
integer
JSON型の文字の最大長を指定する正の整数値。指定する場合、長さは最小2文字で関数の絶対最大長を超えることはできません。短い方の長さが指定されます。
JSON_AGGは、集約関数として最大64,000バイトをサポートします(32,000のUNICODE文字または64,000のLATIN文字)。RETURNS句は、さらに大きな戻り値を指定できますが、JSON_AGGが返す実際のデータは64,000バイトです。データ長がこれより大きい場合はエラーが返されます。JSON_COMPOSEは、JSON_AGGより大きな値を指定できます。
RETURNS句を指定しない場合、戻り値の型はデフォルトのJSON(32,000) CHARACTER SET UNICODEになります。言い換えれば、デフォルトの戻り値の型はUNICODE文字セットのJSONデータ型で、戻り値の長さは32,000文字です。
CHARACTER SET UNICODE | LATIN
RETURNS data_type句のデータ型の文字セット。
文字セットは、LATINまたはUNICODEにできます。
RETURNS STYLE column_expr
関数の戻り型が指定列のデータ型と同じになるように指定します。列のデータ型はJSONである必要があります。
column_exprは、有効なテーブルまたはビューの列参照にすることができます。

戻り値

デフォルトでは、JSON_COMPOSEは、文字セットがUNICODEで、最大長が32,000のUNICODE文字(64,000バイト)のLOBベースのJSON文書を返します(オプションのRETURNS句で別の指定がない場合)。

この関数で階層関係は使用できません。結果として得られるJSON文書は平坦で、各入力パラメータが結果の1つの子に対応します。結果として得られるドキュメントは、次の形式になります。
{
   name1 : data1,
   name2 : data2,
   ...,
   nameN : dataN,
}

JSON文書を構成する値の1つがTeradata NULLの場合、その値はJSONインスタンスでJSON nullとして返されます。

ルールと制限

入力パラメータには、Teradataで許可される任意のデータ型を使用できます。事前定義型は、次のマッピングに基づいてJSONデータ型にマップされます。
  • Teradataの数値データ型は、JSONの数値にマップされます。
  • Teradataのnull値はJSONのnullにマップされます。
  • Teradataの他のすべてのデータ型は、JSONの文字列にマップされます。

LOB属性を入力として、構造化されたUDTを使用できません。

JSON_COMPOSEは、括弧で囲まれたカンマ区切りリストにある構造化されたUDTのすべての属性の値を書き出します。例: (att1Valatt2Val、...、attNVal)。これを64,000バイトで実行できない場合は、SQLエラーが報告されクエリーは失敗します。

JSON構文に適合するように正しくエスケープされていないエスケープ文字を入力文字データに含めることができます。エスケープされていない文字が関数で検出されると、適切なJSON構文に適合するように入力データがエンコードされます。ただし、エスケープ後も切り捨てられたデータが正しくないJSON構文の結果を返す場合は構文エラーが返されます。

すべてのUDTなど、事前定義型以外のすべての型では、変換された値を使用して、結果として得られるJSON文書を生成します。適切に機能するように、有効なJSON構文のデータを出力する変換を指定する必要があります。そうしないと、JSONインスタンスの妥当性検査に失敗して関数がエラー メッセージを返します。ただし、前述のように、関数はエスケープされていない文字を受け取るので、この場合、エラーは返されません。

JSON値のデータ型は、変換結果の事前定義データ型に基づいて上記のマッピングに従って決定されます。すべての非LOB事前定義型は、特定の列に指定したオプションのFORMAT句、または特定のデータ型のデフォルトの形式(FORMAT句が存在しない場合)に従ってフォーマットされます。

param名は、各パラメータにオプションの"AS"句を使用して指定できます。オプション部分がNULLの場合、結果として得られるJSON文書を構成するパラメータの名前は、Teradataの式の現在の命名ルールに応じて与えられます。

使用上の注意

JSON_COMPOSEは、JSON_AGGと同時に使用する場合に最も役立ちます。JSON_AGGは、GROUP BY句によって識別されるグループを提供するように制限されていますが、グループを作成するために使用した値は提供しません。これを取得するには、派生テーブルを生成するsubqueryでJSON_AGGを使用し、JSON_COMPOSE関数へのパラメータの1つとしてJSON_AGGの結果を参照します。グループ化される値が適切なグループに含まれるようにするために、JSON_AGG関数のsubqueryのGROUP BY句で使用される列は、JSON_AGGの結果とともにJSON_COMPOSE関数へのパラメータとして使用する必要があります。これにより、グループ化される値がグループとともに含められます。