RESTForms - 永続クラスにREST APIをアドオンする パート2: クエリ
最初の記事では、RESTForms（永続クラス用のREST API）について説明をしました。 基本的な機能についてはすでに説明しましたが、ここではクエリ機能を中心とする高度な機能について説明します。
* 基本クエリ * クエリ引数 * カスタムクエリ ### クエリクエリを使用すると、任意の条件に基づいてデータの一部を取得できます。 RESTFormsには、2種類のクエリがあります。
* 基本クエリは一度定義すればすべてのRESTFormsクラスに対して機能します。異なっているのはフィールドリストのみです。 * カスタムクエリはそれが指定され、使用できるクラスに対してのみ機能しますが、開発者はクエリの本文に完全にアクセスできます。 ### 基本クエリ一度定義すると、すべてのクラスか一部のクラスですぐに使用できます。 基本クエリはシステムによって定義されているものもありますが、開発者が追加することもできます。これらのクエリはすべて、SELECTのフィールドリストのみを定義します。 その他すべて（絞り込み、ページネーションなど）はRESTFormsによって行われます。 form/objects/:class/:query を呼び出すと、単純なクエリを実行できます。 2番目の :query パラメーターはクエリ名（クエリの SELECT と FROM の間の内容）を定義します。 デフォルトのクエリタイプは次のとおりです。
| クエリ | 説明 |
|---|---|
| all | すべての情報 |
| info | displayName と id |
| infoclass | displayName、id、class |
| count | 行数 |
例えば、Form.Test.Personオブジェクトに関する基本的な情報を取得するには、infoclassクエリを実行できます。 form/objects/Form.Test.Person/infoclass
{"children": [
{"_id":"1", "displayName":"Alice", "_class":"Form.Test.Person"},
{"_id":"2", "displayName":"Charlie", "_class":"Form.Test.Person"},
{"_id":"3", "displayName":"William", "_class":"Form.Test.Person"}
]}RESTFormsは次の場所で myq という名前のクエリを探します（最初にヒットするまで）。
- フォームクラス内のqueryMYQクラスメソッド
- クエリクラス内のMYQパラメーター
- クエリクラス内のqueryMYQクラスメソッド
- Form.REST.Objectsクラス内のMYQパラメーター
- Form.REST.Objectsクラス内のqueryMYQクラスメソッド
独自のクエリクラスを定義できます（上記リストの項目2、3用）。このクエリクラスは、すべてのクラスで使用可能なクエリの定義を保持する特別なクラスです。 そのクラスで myq という名前の独自クエリを定義する手順は以下のとおりです。
- （1回だけ）YourClassName クラスを定義します。
- そのクラスで MYQ パラメーターか queryMYQ クラスメソッドを定義します。 パラメーターはメソッドよりも優先されます。
- メソッドまたはパラメーターは、SQLクエリのSELECTとFROMの間の部分を返す必要があります。
- （1回だけ）ターミナルで以下を実行します。 Do ##class(For.Settings).setSetting("queryclass", YourClassName)
メソッドの署名は以下のとおりです。
ClassMethod queryMYQ(class As %String) As %String
クラス固有のクエリを定義することもできます。 myq という名前の独自クラスクエリを定義する手順は以下のとおりです。
- フォームクラスで queryMYQ クラスメソッドを定義します。
- メソッドの署名は以下のとおりです。ClassMethod queryMYQ() As %String
- メソッドは、SQLクエリのSELECTとFROMの間の部分を返す必要があります。
URL 引数
フィルターやその他のパラメーターをURLで指定できます。 すべての引数は省略可能です。| 引数 | サンプル値 | 説明 |
|---|---|---|
| size | 2 | ページサイズ |
| page | 1 | ページ番号 |
| filter | 値+contains+W | WHERE句 |
| orderby | 値+desc | ORDER BY句 |
| collation | UPPER | COLLATION句 |
| nocount | 1 | レコード数を削除（クエリを高速化します） |
これらの引数に関するいくつかの情報を次に示します。
ORDER BY句
結果の順序を変更します。 値は、カラム名またはカラム名+desc です。 カラム名は、SQLテーブルのカラム名またはカラム番号です。
WHERE句
絞り込み条件の書式は、カラム名+条件+値です。 カラム名+条件+値+カラム名2+条件2+値2のように、複数の条件を指定できます。 矢印構文とシリアルオブジェクトもサポートされています: Column_ColumnField+条件+値 Valueに空白が含まれている場合、サーバーに送信する前にタブに置き換えます。
| URL | SQL |
|---|---|
| neq | != |
| eq | = |
| gte | >= |
| gt | > |
| lte | <= |
| lt | < |
| startswith | %STARTSWITH |
| contains | [ |
| doesnotcontain | '[ |
| in | IN |
| like | LIKE |
リクエストの例:
form/objects/Form.Test.Simple/info?size=2&page=1&orderby=text form/objects/Form.Test.Simple/all?orderby=text+desc form/objects/Form.Test.Simple/all?filter=text+eq+Hello form/objects/Form.Test.Person/infoclass?filter=company_name+contains+a form/objects/Form.Test.Simple/all?filter=text+in+A9044~B5920
SQLアクセスには、ユーザーに適切なSQL権限（フォームテーブルに対するSELECT）を付与する必要があることに注意してください。
COLLATION句
書式は、collation=UPPER または collation=EXACT です。 指定した照合順序をWHERE句で強制します。 省略した場合、デフォルトの照合順序が使用されます。
ページネーション
ページネーションは、デフォルトで1ページあたり25レコードになります。 ページサイズと現在のページを変更するには、size 引数と page 引数を（1を基準として）指定します。
カスタムクエリ
form/objects/:class/custom/:query を呼び出すと、カスタムクエリを実行できます。 カスタムクエリを使用すると、開発者はクエリの内容全体を決めることができます。 size および page 以外のURLパラメーターは指定できません。 メソッドは他のすべてのURLパラメーターを解析する必要があります（またはForm.JSON.SQLからデフォルトのパーサーを呼び出す必要があります）。 myq という名前のカスタムクエリを定義する手順は以下のとおりです。
- フォームクラスで customqueryMYQ クラスメソッドを定義します。
- メソッドの署名は以下のとおりです。ClassMethod customqueryMYQ() As %String
- メソッドは有効なSQLクエリを返す必要があります。
デモ
[現在デモ環境はお試しいただくことができません。]
こちらでRESTFormsをオンラインで試すことができます（ユーザー名：Demo、パスワード：Demo）。
また、RESTFormsUIアプリケーション（RESTFormsデータエディタ）もあります。こちらをご確認ください（ユーザー名：Demo、パスワード：Demo）。 クラスリストのスクリーンショットを以下に掲載しています。
まとめ
RESTFormsは、幅広くカスタマイズ可能なクエリ機能を提供します。
次の内容
次の記事では、いくつかの高度な機能について説明します。
- メタデータの解釈
- セキュリティと権限
- オブジェクト名