Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

%INLIST

値を %List 構造化リストの要素と一致させます。

Synopsis

scalar-expression %INLIST list [SIZE ((nn))]

引数

scalar-expression 値を list 要素と比較するスカラ式 (通常はデータ列)。
list 1 つまたは複数の要素を含んだ %List 構造。
SIZE ((nn)) オプションlist 内の要素数の桁を指定する整数。10、100、1000、10000、といった値のいずれかでリテラルとして指定する必要があります。

説明

%INLIST 述語は、フィールドの値をリスト構造の要素に一致させるための、Caché の拡張機能です。%INLISTIN はどちらも、指定した複数の値でこのような等値比較を実行できます。%INLIST は、これらの複数の値を、単一の list 引数の要素として指定します。したがって、%INLIST では、別のクエリ・キャッシュを作成することなく、マッチングする値の数を変更できます。

オプションの %INLIST SIZE 節では、整数 nn を提供し、これによって list 内のリスト要素数の桁を指定します。Caché はこの桁数を使用して、最適なクエリ・プランを決定します。list 内の要素の数に関係なく同じクエリ・キャッシュを使用できるので、SIZE を指定すると、list 内の要素の想定される概数に合わせて最適化されたクエリ・キャッシュを作成できます。SIZE リテラルを変更すると、別のクエリ・キャッシュが作成されます。nn は、10、100、1000、10000、その他のいずれかのリテラルで指定します。nn は、コンパイル時に定数値として使用可能であることが要求されるため、すべての SQL コードでリテラルとして指定する必要があります。コンパイルされたすべての SQL (ダイナミック SQL) で、次に示すように二重括弧を指定する必要があります。二重括弧は埋め込み SQL では使用されません。詳細は、"Caché SQL 最適化ガイド" の “クエリ・キャッシュ” の章を参照してください。

%INLIST は、list の各要素との等値比較を実行します。%INLIST 比較では、scalar-expression に対して定義された照合タイプが使用されます。したがって、list 要素の比較では、scalar-expression の照合に応じて、大文字と小文字が区別される場合も、されない場合もあります。既定では、文字列データ型フィールドは大文字と小文字が区別されない SQLUPPER 照合で定義されます。現在のネームスペースにおける既定の文字列の照合の定義およびフィールド/プロパティの定義における既定以外のフィールドの照合タイプの指定の詳細は、"Caché SQL の使用法" の “照合” の章を参照してください。

NULL を比較値として指定することに意味はありません。NULL は値なしであるため、すべての等式テストに失敗します。%INLIST 述語 (または他の任意の述語) を指定すると、指定されたフィールドのインスタンスのうち NULL であるものがすべて排除されます。NULL のフィールドを述語の結果セットに含めるためには、IS NULL 述語を指定する必要があります。

ほとんどの述語と同様に、%INLIST は NOT 論理演算子を使用して反転できます。%INLISTNOT %INLIST も、NULL フィールドを返すために使用することはできません。NULL フィールドを返すには、IS NULL を使用します。

マッチング式が %List 形式でない場合、%INLIST は SQLCODE -400 エラーを発行します。例えば、クラスが MultiValue クラス (%MV.Adaptor で指定) の場合、またはコレクション・プロパティの SqlListType が DELIMITED の場合は、リスト・フィールドの論理値は %List 形式ではありません。リスト構造の詳細は、SQL の $LIST 関数を参照してください。

述語条件を指定できる場所であればどこでも、%INLIST を使用できます。詳細は、このドキュメントの "述語の概要" ページを参照してください。

コンマで区切られた値リストのように、構造化されていない一連の項目に値を結合するには、IN 述語を使用します。IN では、等値比較やサブクエリ比較を実行できます。

%SelectMode

%INLIST 述語は、現在の %SelectMode 設定を使用しません。list の要素は、%SelectMode 設定に関係なく、論理形式で指定する必要があります。list 要素を ODBC 形式または表示形式で指定しようとすると、通常は、データが一致しないか、意図していないデータと一致することになります。

%EXTERNAL または %ODBCOUT 形式変換関数を使用すると、述語による操作対象となる scalar-expression フィールドを変換できます。これにより、表示形式または ODBC 形式で list 要素を指定できるようになります。ただし、形式変換関数を使用すると、そのフィールドのためのインデックスを使用できなくなり、それによってパフォーマンスに大きな影響を与える可能性があります。

以下のダイナミック SQL の例では、%INLIST 述語により、%SelectMode=1 (ODBC) 形式ではなく論理形式で、1978 年の日付値要素を含むリストを指定します。これらの $HOROLOG 形式の日付に対応する日付が選択されます。

  ZNSPACE "SAMPLES"
  SET bday=$LISTBUILD(50039)
  FOR i=50039:1:50403 {SET bday=bday_$LISTBUILD(i) }
  SET q1 = "SELECT Name,DOB FROM Sample.Person "
  SET q2 = "WHERE DOB %INLIST ?"
  SET myquery = q1_q2
  SET tStatement = ##class(%SQL.Statement).%New()
  SET tStatement.%SelectMode=1
  SET qStatus = tStatement.%Prepare(myquery)
    IF qStatus'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT}
  SET rset = tStatement.%Execute(bday)
  DO rset.%Display()

以下のダイナミック SQL の例では、%ODBCOUT 形式変換関数を使用して、述語によって、一致した DOB フィールドを変換します。これにより、%INLIST リスト要素を ODBC 形式で指定できるようになります。ただし、形式変換関数を指定すると、DOB フィールド値のためのインデックスを使用できなくなります。

  ZNSPACE "SAMPLES"
  SET births=$LISTBUILD("1978-01-15","1978-08-22","1978-10-01")
  SET q1 = "SELECT Name,DOB FROM Sample.Person "
  SET q2 = "WHERE %ODBCOUT(DOB) %INLIST ?"
  SET myquery = q1_q2
  SET tStatement = ##class(%SQL.Statement).%New()
  SET tStatement.%SelectMode=1
  SET qStatus = tStatement.%Prepare(myquery)
    IF qStatus'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT}
  SET rset = tStatement.%Execute(births)
  DO rset.%Display()

%INLIST および IN

%INLIST および IN 述語はどちらも、等値比較に使用する複数の値を指定するために使用できます。以下のダイナミック SQL の例は、同じ結果を返します。

  ZNSPACE "SAMPLES"
  SET states=$LISTBUILD("VT","NH","ME")
  SET myquery = "SELECT Name,Home_State FROM Sample.Person WHERE Home_State %INLIST ?"
  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(states)
  DO rset.%Display()
  ZNSPACE "SAMPLES"
  SET s1="VT"
  SET s2="NH"
  SET s3="ME"
  SET myquery = "SELECT Name,Home_State FROM Sample.Person WHERE Home_State IN(?,?,?)"
  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(s1,s2,s3)
  DO rset.%Display()

ただし、ダイナミック SQL では、%INLIST 述語は単一のホスト変数として指定できますが、IN 述語は個別のホスト変数として指定する必要があります。したがって、IN 述語の値の数を変更すると、別個のクエリ・キャッシュが作成されることになります。%INLIST 述語の値の数を変更しても、別のクエリ・キャッシュは作成されません。詳細は、“Caché SQL 最適化ガイド” の “クエリ・キャッシュ” の章を参照してください。

以下の例では、Home_State 列の値を、New England 北部の州の構造化されたリストの要素に一致させます。

  ZNSPACE "SAMPLES"
  SET states=$LISTBUILD("VT","NH","ME")
  SET myquery="SELECT Name,Home_State FROM Sample.Person "_
              "WHERE Home_State %INLIST ?"
  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(states)
  DO rset.%Display()

以下の 2 つの例では、照合のマッチングが scalar-expression 照合に基づいていることが示されています。Home_State フィールドは、大文字と小文字が区別されない SQLUPPER 照合で定義されます。これらの例の list は、New Hampshire を “NH” ではなく “nH” と指定しています。最初の例では NH Home_State 値が返されますが、2 番目の例では NH Home_State 値が返されません。

  ZNSPACE "SAMPLES"
  SET states=$LISTBUILD("VT","nH","ME")
  SET myquery="SELECT Name,Home_State FROM Sample.Person "_
              "WHERE Home_State %INLIST ?"
  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(states)
  DO rset.%Display()
  ZNSPACE "SAMPLES"
  SET states=$LISTBUILD("VT","nH","ME")
  SET myquery="SELECT Name,Home_State FROM Sample.Person "_
              "WHERE %EXACT(Home_State) %INLIST ?"
  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(states)
  DO rset.%Display()

以下の例では、SIZE リテラルが 10 のクエリ・キャッシュを作成します。10 は桁数でリスト内の要素の実数に対応するので、SIZE 10 の指定はこのクエリには最適です。リスト内の要素の数を変更しても、別のクエリ・キャッシュは作成されません。SIZE リテラルを変更すると、別のクエリ・キャッシュが作成されます。

  ZNSPACE "SAMPLES"
  SET states=$LISTBUILD("VT","NH","ME")
  SET myquery="SELECT Name,Home_State FROM Sample.Person "_
              "WHERE Home_State %INLIST ? SIZE ((10))"
  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(states)
  DO rset.%Display()
  ZNSPACE "SAMPLES"
  SET states=$LISTBUILD("VT","nH","ME")
  SET myquery="SELECT Name,Home_State FROM Sample.Person "_
              "WHERE Home_State %INLIST ?"
  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(states)
  DO rset.%Display()

以下の例では、SIZE リテラルが 10 のクエリ・キャッシュを作成します。10 は桁数でリスト内の要素の実数に対応するので、SIZE 10 の指定はこのクエリには最適です。リスト内の要素の数を変更しても、別のクエリ・キャッシュは作成されません。SIZE リテラルを変更すると、別のクエリ・キャッシュが作成されます。

  ZNSPACE "SAMPLES"
  SET states=$LISTBUILD("VT","NH","ME")
  SET myquery="SELECT Name,Home_State FROM Sample.Person "_
              "WHERE Home_State %INLIST ? SIZE ((10))"
  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(states)
  DO rset.%Display()

関連項目

FeedbackOpens in a new tab