%DLIST (SQL)

値の InterSystems IRIS リストを作成する集約関数です。

構文

%DLIST([ALL | DISTINCT [BY(col-list)]] 
  string-expr 
  [%FOREACH(col-list)] [%AFTERHAVING])

説明

%DLIST 集約関数は、指定された列の値をリストの要素として含む ObjectScript %List 構造を返します。

シンプルな %DLIST (または %DLIST ALL) は、選択された行の string-expr に対応する NULL 以外のすべての値で構成される InterSystems IRIS リストを返します。string-expr が NULL の行は、リスト構造の要素として含まれません。

%DLIST DISTINCT は、選択された行の string-expr に対応する NULL 以外のすべての個別 (一意の) 値で構成される InterSystems IRIS リストを返します (%DLIST(DISTINCT col1))。NULL は、%List 構造の要素として含まれません。%DLIST(DISTINCT BY(col2) col1) は、col2 値が個別 (一意) であるレコードのこれらの col1 フィールド値のみが含まれる要素の %List を返します。ただし、個別の col2 値には、個別値として NULL が 1 つ含まれる場合があります。

InterSystems IRIS リスト構造の詳細は、$LIST および関連する関数を参照してください。

%DLIST と %SelectMode

%SelectMode プロパティを使用して、%DLIST から返されるデータの表示モードを 0 = 論理 (既定)、1 = ODBC、2 = 表示のいずれかに指定できます。

ODBC モードでは %DLIST は列の値のリストをコンマで区切り、$LISTTOSTRING は (既定では) %List 列値内の要素をコンマで区切って返します。

%DLIST と ORDER BY

%DLIST 関数は、複数の行のテーブル列の値を %List 構造の値リストに結合します。すべての集約フィールドが評価された後に ORDER BY 節がクエリ結果セットに適用されるため、ORDER BY がこのリスト内の値の順序に直接影響することはありません。特定の状況下では、%DLIST の結果が順番に表示されることがありますが、この順番を信頼すべきではありません。特定の集約結果値内にリストされる値を、明示的に順序付けすることはできません。

引数

ALL

%DLIST で、string-expr にある値すべてのリストを返すことを指定する引数 (オプション)。キーワードが指定されていない場合は、これが既定になります。

DISTINCT

%DLIST が一意の string-expr の値のみを含む %List 構造リストを返すように指定する DISTINCT 節 (オプション)。DISTINCT で BY(col-list) 従属節を指定できます。col-list には 1 つのフィールド、またはコンマ区切りのフィールドのリストを指定できます。

string-expr

文字列として評価する SQL 式。通常は選択されたテーブルの列の名前です。

%FOREACH(col-list)

1 つの列名、またはコンマで区切った複数の列名のリストです (オプション)。%FOREACH の詳細は、"SELECT" を参照してください。

%AFTERHAVING

HAVING 節にある条件を適用する引数 (オプション)。

例

以下の例では、Sample.Person テーブルの Home_State 列にある、先頭の文字が “A” であるすべての値の InterSystems IRIS リストを返します。

SELECT %DLIST(Home_State)
FROM Sample.Person
WHERE Home_State %STARTSWITH 'A'

この InterSystems IRIS リストには、値が重複する要素が含まれています。

以下の例では、Sample.Person テーブルの Home_State 列にある、先頭の文字が “A” であるすべての個別値 (一意の値) の InterSystems IRIS リストを返します。

SELECT %DLIST(DISTINCT Home_State)
FROM Sample.Person
WHERE Home_State %STARTSWITH 'A'

以下の例では、各州の Home_City 列にあるすべての値の InterSystems IRIS リストを作成し、これらの都市の値の数を州ごとにカウントします。それぞれの Home_State の行には、その州のすべての Home_City 値のリストが格納されます。これらのリストでは、都市名が重複している可能性があります。

SELECT Home_State,
       %DLIST(Home_City) AS AllCities,
       COUNT(Home_City) AS CityCount
FROM Sample.Person
GROUP BY Home_State

以下の例に示すように、各州の Home_City 列にあるすべての個別値のリストを生成したほうが役に立つことが普通です。

SELECT Home_State,
       %DLIST(DISTINCT Home_City) AS CitiesList,
       COUNT(DISTINCT Home_City) AS DistinctCities,
       COUNT(Home_City) AS TotalCities
FROM Sample.Person
GROUP BY Home_State

この例は、各州の個別の都市名をカウントした整数と、都市名の合計をカウントした整数の両方を返します。

以下の例は、"A" で始まる Home_State 値の %List 構造を返します。これは、個別の Home_State 値 (DISTINCT Home_State)、個別の Home_City 値に対応する Home_State 値 (DISTINCT BY(Home_City) Home_State、Home_City に対応する一意の NULL が 1 つ含まれる場合があります)、およびすべての Home_State 値を %List 要素として返します。

SELECT %DLIST(DISTINCT Home_State) AS DistStates,
       %DLIST(DISTINCT BY(Home_City) Home_State) AS DistCityStates,
       %DLIST(Home_State) AS AllStates
FROM Sample.Person
WHERE Home_State %STARTSWITH 'A'

以下のダイナミック SQL の例では、%SelectMode プロパティを使用して、%List 構造の FavoriteColors 日付フィールドに ODBC 表示モードを指定しています。ODBC モードは、各列の値をコンマ区切りリストとして返し、$LISTTOSTRING 関数は異なる区切り文字 (この例では ||) を指定し、異なる列の値を区切ります。

  set myquery = "SELECT %DLIST(FavoriteColors) AS colors FROM Sample.Person WHERE Name %STARTSWITH 'A'"
  set tStatement = ##class(%SQL.Statement).%New()
  set tStatement.%SelectMode=1

  set qStatus = tStatement.%Prepare(myquery)
  if $$$ISERR(qStatus) {write "%Prepare failed:" do $SYSTEM.Status.DisplayError(qStatus) quit}
  
  set rset = tStatement.%Execute()
  if (rset.%SQLCODE '= 0) {write "%Execute failed:", !, "SQLCODE ", rset.%SQLCODE, ": ", rset.%Message quit}

  while rset.%Next()
  {
    write $LISTTOSTRING(rset.colors,"||"),!
  }
  if (rset.%SQLCODE < 0) {write "%Next failed:", !, "SQLCODE ", rset.%SQLCODE, ": ", rset.%Message quit}

  write !,"End of data"

以下の例では、%AFTERHAVING キーワードを使用します。ここでは、HAVING 節の条件 (先頭の文字が “M” である名前) を満たす Name 値が 1 つ以上ある Home_State 行をすべて返します。最初の %DLIST 関数は、該当の州についてすべての名前のリストを返します。2 番目の %DLIST 関数は、HAVING 節の条件を満たす名前のみを含むリストを返します。

SELECT Home_State,
       %DLIST(Name) AS AllNames,
       %DLIST(Name %AFTERHAVING) AS HaveClauseNames
    FROM Sample.Person
    GROUP BY Home_State
    HAVING Name LIKE 'M%'
    ORDER BY Home_state