クラス・クエリの定義と使用
ここでは、クラス・クエリについて説明します。クラス・クエリは、クラス構造の一部である名前付きクエリとして機能し、ダイナミック SQL を通じてアクセスできます。
クラス・クエリの概要
クラス・クエリとは、ダイナミック SQL と共に使用することを目的として、クラスに含まれているツールです。これにより、指定した条件を満たすレコードを検索します。クラス・クエリを使用すると、アプリケーションに応じて事前に定義した検索を作成できます。例えば、名前でレコードを検索したり、特定の条件のセット (パリからマドリッドまでのすべての航空便など) を満たすレコードのリストを提供したりできます。
クラス・クエリを作成することで、特定のオブジェクトの内部 ID を使用してそのオブジェクトを検索せずに済むようになります。その代わりに、必要とするクラス・プロパティに基づいてレコードを検索するクエリを作成できます。これは、実行時にユーザによって指定することも可能です。
カスタム・クラス・クエリを定義すると、検索ロジックに ObjectScript を使用することも、検索ロジックを任意の複合式にすることもできます。
クラス・クエリには、以下の 2 種類があります。
-
基本クラス・クエリ。クラス %SQLQueryOpens in a new tab と SQL SELECT 文を使用します。
-
カスタム・クラス・クエリ。クラス %QueryOpens in a new tab と、カスタム・ロジック (クエリを実行、フェッチ、およびクローズするためのロジック) を使用します。これらについては別途説明します。
クラス・クエリはどのクラス内でも定義できます。クラス・クエリは永続クラス内に含める必要はありません。
別のクラス・クエリの結果に依存するクラス・クエリを定義しないでください。このような依存関係はサポートされません。
クラス・クエリの使用法
クラス・クエリを定義する方法について説明する前に、その使用方法を知っておくと便利です。サーバ側のコードでは、以下のようにクラス・クエリを使用できます。
-
%New() を使用して、%SQL.StatementOpens in a new tab のインスタンスを作成します。
-
そのインスタンスの %PrepareClassQuery() メソッドを呼び出します。引数として、以下をこの順番で使用します。
-
使用するクエリを定義しているクラスの完全修飾名。
-
そのクラスに含まれるクエリの名前。
このメソッドは %StatusOpens in a new tab 値を返すので、その値を確認する必要があります。
-
-
%SQL.StatementOpens in a new tab インスタンスの %Execute() メソッドを呼び出します。これにより %SQL.StatementResultOpens in a new tab のインスタンスが返されます。
-
%SQL.StatementResultOpens in a new tab のメソッドを使用して、結果セットからデータを取得します。詳細は、"ダイナミック SQL の使用" を参照してください。
以下に、Sample.Person の ByName クエリを使用する簡単な例を示します。
// classquerydemo
set statement = ##class(%SQL.Statement).%New()
set status = statement.%PrepareClassQuery("Sample.Person","ByName")
if $$$ISERR(status) {
write "%Prepare failed:" do $SYSTEM.Status.DisplayError(status)
quit
}
set rset = statement.%Execute()
if (rset.%SQLCODE '= 0) {
write "%Execute failed:", !, "SQLCODE ", rset.%SQLCODE, ": ", rset.%Message
quit
}
while rset.%Next()
{
write !, rset.%Get("Name")
}
if (rset.%SQLCODE < 0) {
write "%Next failed:", !, "SQLCODE ", rset.%SQLCODE, ": ", rset.%Message
quit
}
ストアド・プロシージャとしてクエリを呼び出して、それを SQL コンテキストから実行することもできます。"ストアド・プロシージャの定義と使用" を参照してください。
基本クラス・クエリの定義
基本クラス・クエリを定義するには、以下のようにクエリを定義します。
-
(単純なクラス・クエリの場合) タイプは %SQLQueryOpens in a new tab にする必要があります。
-
引数リストに、クエリが受け入れる引数を指定します。
-
定義の本文に、SQL SELECT 文を記述します。
この文では、引数名の先頭にコロン (:) を付けて、引数を参照します。
この SELECT 文には、INTO 節を含めないでください。
-
クエリ定義に SqlProc キーワードを含めます。
-
オプションとして、ストアド・プロシージャに既定の名前とは別の名前を付ける場合は、クエリ定義内で SqlName キーワードを指定します。
これらは、コンパイラ・キーワードであるため、クエリ・タイプ (%SQLQueryOpens in a new tab) の後のパラメータに続く角括弧の内側に含めます。
例
以下に簡単な例を示します。
Query ListEmployees(City As %String = "")
As %SQLQuery (ROWSPEC="ID:%Integer,Name:%String,Title:%String", CONTAINID = 1) [SqlProc, SqlName=MyProcedureName]
{
SELECT ID,Name,Title FROM Employee
WHERE (Home_City %STARTSWITH :City)
ORDER BY Name
}
文字列パラメータの最大長
ADO.NET、ODBC、または JDBC を使用してクラス・クエリを呼び出す場合、既定では、文字列パラメータが 50 文字に切り捨てられます。パラメータの最大文字列長を長くするには、以下の例のようにシグニチャで MAXLEN を指定します。
Query MyQuery(MyParm As %String(MAXLEN = 200)) As %SQLQuery [SqlProc]
管理ポータルまたは ObjectScript からクエリを呼び出す場合、この切り捨ては行われません。