JSON_OBJECT

JSON オブジェクトとしてデータを返す変換関数です。

Synopsis

JSON_OBJECT(select-items [NULL ON NULL | ABSENT ON NULL])

引数

select-items

key:value ペアまたはコンマで区切られた key:value ペアのリスト。key はユーザが指定するリテラル文字列で、一重引用符で区切られます。value は、列名、集約関数、算術式、数値や文字リテラル、またはリテラル NULL になります。

ABSENT ON NULL

NULL ON NULL

オプション — 返された JSON オブジェクトでの NULL 値の表示方法を指定するキーワード句。NULL ON NULL (既定) は、NULL (存在しない) データを null という言葉 (引用符なし) で表します。ABSENT ON NULL は NULL データを JSON オブジェクトから省略します。値が NULL の場合は key:value のペアを削除して、プレースホルダのコンマを残しません。このキーワード句は、空の文字列値に影響を与えません。

説明

JSON_OBJECT はコンマ区切りの key:value ペアのリスト (例 : 'mykey':colname) を取得して、これらの値を含む JSON オブジェクトを返します。key 名には、任意の文字列を一重引用符で囲んで指定できます。JSON_OBJECT は key 名に名前付け規約や一意性チェックを適用しません。value には、列名またはその他の式を指定できます。

JSON_OBJECT は、SELECT 文で他のタイプの選択項目と組み合わせることができます。JSON_OBJECT は、WHERE 節など、SQL 関数を使用できる他の場所に指定できます。

返される JSON オブジェクトの形式は、以下のとおりです。

{ "key1" : "value1" , "key2" : "value2" , "key3" : "value3" }

JSON_OBJECT は、文字列 (二重引用符で囲まれます) または数字として、オブジェクト値を返します。数字はキャノニック形式で返されます。数値文字列は、リテラルとして、二重引用符で囲まれて返されます。その他のすべてのデータ型 (例えば、日付や $List) は、文字列として返され、現在の %SelectMode によって返される値の形式が決まります。DISPLAY または ODBC モードがクエリに選択されている場合、JSON_OBJECT は key と value の両方の値を DISPLAY または ODBC モードで返します。

JSON_OBJECT では、テーブル内のすべてのフィールドを指定するための方法としてアスタリスク (*) 構文を使用することはできません。

返される JSON オブジェクトの列には、Expression (既定) というラベルが付けられます。JSON_OBJECT には列のエイリアスを指定できます。

選択モードおよび照合

現在の %SelectMode プロパティによって、返される JSON オブジェクト値のフォーマットが決まります。選択モードを変更することによって、すべての日付値および %List 値が、その選択モードのフォーマットの文字列として JSON オブジェクトに組み込まれます。フォーマット変換関数 (%EXTERNAL、%INTERNAL、%ODBCIN、%ODBCOUT) を JSON_OBJECT 内の個別のフィールド名に適用することによって、現在の選択モードをオーバーライドできます。フォーマット変換関数を JSON_OBJECT に適用しても、JSON オブジェクトの key:value ペアは文字列であるため、影響はありません。

既定の照合によって、返される JSON オブジェクト値の照合が決まります。照合関数を JSON_OBJECT に適用し、キーと値の両方を変換できます。通常、キーは大文字と小文字を区別するため、照合関数を JSON_OBJECT に割り当てないでください。Caché は JSON オブジェクトへのフォーマットの後で照合を適用します。したがって、%SQLUPPER(JSON_OBJECT('k1':f1,'k2':f2)) では、JSON オブジェクトの key および value 文字列がすべて大文字に変換されます。%SQLUPPER は、オブジェクト内の値の前ではなく、JSON オブジェクトの前にスペースを挿入します。句読点を削除する照合関数 (%ALPHAUP など) は、戻り値から中括弧を削除するため、戻り値は JSON オブジェクトではなくなります。

JSON_OBJECT 内では、照合関数を key:value ペアの値部分に適用できます。％SQLUPPER は、値の前にスペースを挿入するので、一般に、LCASE、UCASE、LOWER などのケース変換関数を指定することが推奨されます。

ABSENT ON NULL

オプションの ABSENT ON NULL キーワード句を指定すると、NULL (または NULL リテラル) の列値は、JSON オブジェクトに含まれなくなります。JSON オブジェクトにプレースホルダは含まれません。この結果、JSON オブジェクトに含まれる key:value ペアの数が違ってくる可能性があります。例えば、以下のプログラムが返す JSON オブジェクトでは、一部のレコードは 3 番目の key:value ペアは Age になり、他のレコードでは 3 番目の key:value ペアは FavoriteColors になります。

SELECT JSON_OBJECT('id':%ID,'name':Name,'colors':FavoriteColors,'years':Age ABSENT ON NULL) FROM Sample.Person

キーワード句を指定しない場合、既定は NULL ON NULL になり、NULL は null という単語で (引用符による区切りなしで)、key:value ペアの値として表示されます。したがって、JSON_OBJECT 関数から返される JSON オブジェクトはすべて、同じ数の key:value ペアを持つことになります。

例

以下のダイナミック SQL の例は、JSON_OBJECT を適用して、フィールド値を含む JSON オブジェクトをフォーマットします。

  ZNSPACE "SAMPLES"
  SET myquery = 2
  SET myquery(1) = "SELECT TOP 3 JSON_OBJECT('id':%ID,'name':Name,'birth':DOB,"
  SET myquery(2) = "'age':Age,'state':Home_State) FROM Sample.Person"
  SET tStatement = ##class(%SQL.Statement).%New()
  SET qStatus = tStatement.%Prepare(.myquery)
   IF qStatus'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT}
  SET rset = tStatement.%Execute()
  WHILE rset.%Next() {DO rset.%Print(" ^ ")}
  WRITE !,"Total row count=",rset.%ROWCOUNT

以下のダイナミック SQL の例は、JSON_OBJECT を適用して、リテラルおよびフィールド値を含む JSON オブジェクトをフォーマットします。

  ZNSPACE "SAMPLES"
  SET myquery = 2
  SET myquery(1) = "SELECT TOP 3 JSON_OBJECT('lit':'Employee from','t':%TABLENAME,"
  SET myquery(2) = "'name':Name,'num':SSN) FROM Sample.Employee"
  SET tStatement = ##class(%SQL.Statement).%New()
  SET qStatus = tStatement.%Prepare(.myquery)
   IF qStatus'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT}
  SET rset = tStatement.%Execute()
  WHILE rset.%Next() {DO rset.%Print(" ^ ")}
  WRITE !,"Total row count=",rset.%ROWCOUNT

以下のダイナミック SQL の例は、JSON_OBJECT を適用して、NULL およびフィールド値を含む JSON オブジェクトをフォーマットします。

  ZNSPACE "SAMPLES"
  SET myquery = 2
  SET myquery(1) = "SELECT JSON_OBJECT('name':Name,'colors':FavoriteColors) FROM Sample.Person"
  SET myquery(2) = " WHERE Name %STARTSWITH 'S'"
  SET tStatement = ##class(%SQL.Statement).%New()
  SET qStatus = tStatement.%Prepare(.myquery)
   IF qStatus'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT}
  SET rset = tStatement.%Execute()
  WHILE rset.%Next() {DO rset.%Print(" ^ ")}
  WRITE !,"Total row count=",rset.%ROWCOUNT

以下のダイナミック SQL の例では ODBC %SelectMode が設定されます。これは、JSON オブジェクト値を含むすべてのフィールドを表す方法を決定します。このクエリは、%EXTERNAL フォーマット変換関数を適用することによって、特定の JSON_OBJECT 値に対応するこの選択モードをオーバーライドします。

  ZNSPACE "SAMPLES"
  SET myquery = 3
    SET myquery(1) = "SELECT TOP 8 JSON_OBJECT('ODBCBday':DOB,'DispBday':%EXTERNAL(DOB)),"
    SET myquery(2) = "JSON_OBJECT('ODBCcolors':FavoriteColors,'DispColors':%EXTERNAL(FavoriteColors)) "
    SET myquery(3) = "FROM Sample.Person"
   SET tStatement = ##class(%SQL.Statement).%New()
   SET tStatement.%SelectMode=1
    WRITE "SelectMode is ODBC",!
  SET qStatus = tStatement.%Prepare(.myquery)
   IF qStatus'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT}
  SET rset = tStatement.%Execute()
     IF rset.%SQLCODE=0 { WRITE !,"Executed query",! }
     ELSE { SET badSQL=##class(%Exception.SQL).%New(,rset.%SQLCODE,,rset.%Message)}
  DO rset.%Display()
  WRITE !,"End of data"

以下のダイナミック SQL の例は、JSON_OBJECT を適用して、結合されたテーブルのフィールド値を含む JSON オブジェクトをフォーマットします。

  ZNSPACE "SAMPLES"
  SET myquery = 2
  SET myquery(1) = "SELECT TOP 3 JSON_OBJECT('e.t':E.%TABLENAME,'e.name':E.Name,'c.t':C.%TABLENAME,"
  SET myquery(2) = "'c.name':C.Name) FROM Sample.Employee AS E,Sample.Company AS C"
  SET tStatement = ##class(%SQL.Statement).%New()
  SET qStatus = tStatement.%Prepare(.myquery)
   IF qStatus'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT}
  SET rset = tStatement.%Execute()
  WHILE rset.%Next() {DO rset.%Print(" ^ ")}
  WRITE !,"Total row count=",rset.%ROWCOUNT

以下のダイナミック SQL の例は、JSON_OBJECT を WHERE 節で使用して、OR 構文を使用しないで複数の列で Contains テストを実行します。

  ZNSPACE "SAMPLES"
  SET myquery = 2
  SET myquery(1) = "SELECT Name,Home_City,Home_State FROM Sample.Person"
  SET myquery(2) = " WHERE JSON_OBJECT('name':Name,'city':Home_City,'state':Home_State) [ 'X'"
  SET tStatement = ##class(%SQL.Statement).%New()
  SET qStatus = tStatement.%Prepare(.myquery)
   IF qStatus'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT}
  SET rset = tStatement.%Execute()
  WHILE rset.%Next() {DO rset.%Print(" ^ ")}
  WRITE !,"Total row count=",rset.%ROWCOUNT

JSON_OBJECT

Synopsis

引数

説明

選択モードおよび照合

ABSENT ON NULL

例

関連項目