dataClass.query( ) メソッドは、データクラス内にある全てのエンティティから、queryString または formula 引数と任意のvalue 引数で指定された検索条件に合致するエンティティを検索し、データクラス内から見つかった全てのエンティティを格納するEntitySelection 型の新しいオブジェクトを返します。このメソッドにはレイジーローディングが適用されます。

合致するエンティティが見つからない場合、空のEntitySelection が返されます。

 queryString 引数は以下のシンタックスを使用します:

詳細は以下の通りです:

• attributePath: クエリを実行したい属性のパス。この単純な名前(例えば"country" など)または有効な属性パス(例えば"country.name" など)の形式をとることができます。属性パスがCollection 型である場合、全てのオカレンスを管理するためには[] 記法を使用してください(例えば "children[ ].age" など)。また、プレースホルダーを使用することもできます(以下参照)
  
  注: ".", "[ ]", または "=", ">", "#"..., などの特殊文字を含んでいる名前の属性を直接使用することはできません。なぜならこれらの文字はクエリ文字列の中で正しく評価されないからです。こういった属性をクエリしたい場合には、プレースホルダーの使用を検討してください。この場合、属性パス内の文字で使用できる幅は広がります(以下の value引数(およびプレースホルダー) を参照してください)。

• comparator: attributePath 引数をvalue 引数を比較する記号。以下の記号がサポートされます:
  

  比較	記号	補足
  等しい	=, ==	一致するデータを取得。ワイルドカード(@)をサポートし、大文字小文字/アクセント記号の有無は区別しません。
  	===, IS	一致するデータを取得。ワイルドカード(@)は標準文字として認識され、大文字小文字/アクセント記号の有無は区別しません。
  等しくない	#, !=	ワイルドカード(@)をサポート
  	!==, IS NOT	ワイルドカード(@)は標準文字として認識
  未満	<
  より大きい	>
  以下	<=
  以上	>=
  含まれる	IN	コレクション、あるいは複数の値の中の、どれか一つの値と等しいデータを取得します。ワイルドカード(@)をサポート
  宣言にNot 条件を適用する	NOT	複数の演算子が含まれる宣言の前にNOTを使用する場合にはカッコをつける必要があります。
  キーワードを含む	%	キーワードは文字列あるいはピクチャー型の属性中で使用されるものが対象です

• logicalOperator: 複数の条件をクエリ内で結合させるのに使用します(任意)。以下の論理演算子のいずれか一つを使用する事ができます(名前あるいは記号のどちらかを渡します):
  

  結合	記号
  AND	&, &&, and
  OR	|, ||, or

• order by attributePath: クエリに "order by attributePath" ステートメントを追加することで、結果をソートすることができます。カンマで区切ることで、複数のorder by ステートメントを使用することもできます(例: order by attributePath1 desc, attributePath2 asc)。デフォルトの並び順は昇順です。並び順を指定するには、降順の場合は 'desc' 昇順の場合は 'asc' を追加します。
  注: このステートメントを使用した場合、順序ありエンティティセレクションが返されます (詳細については エンティティセレクションの順列あり/順列なし を参照ください)。
  

クオートを使用する
クエリ内でクオートを使用する場合、クエリ内においてはシングルクオート ' 'を使用し、クエリ全体をくくるためにはダブルクオート " " を使用します。クオートを混同するとエラーが返されます。例:

注: シングルクオート(')は検索する値としてはサポートされていません。クエリ文字列を分解してしまうからです。例えば、"comp.name = 'John's pizza' " という文字列はエラーを生成します。シングルクオートを含む値を検索したい場合には、プレースホルダーを使用を検討してください(以下参照)。

カッコを使用する
クエリ内でカッコを使用する事で、計算に優先順位をつけることができます。例えば、以下のようにクエリを整理することができます:

queryString 引数内でのフォーミュラ挿入(上記参照)の代替として、formula オブジェクトをブール検索条件として直接渡すことができます。クエリにおいてフォーミュラオブジェクトを使用することは、トークナイズの利点を生かせる、コードが検索しやすく読みやすい、などといった面から推奨されています。

フォーミュラは、Formula あるいは Formula from string コマンドを使用して作成されている必要があります。この場合:

• formula 引数のフォーミュラはそれぞれのエンティティに対して評価され、trueまたはfalseを返さなければなりません。クエリの実行中、フォーミュラの結果がブール値でなかった場合、それはfalseであるとみなされます。
• formula 引数内にて、エンティティはThis オブジェクトを通して利用可能です。
• formula オブジェクトがnull の場合、エラー1626("テキストまたはフォーミュラが必要です")が生成されます。このエラーはON ERR CALLで実装したメソッドを使用して割り込み可能です。

注: セキュリティ上の理由から、query() メンバーメソッド内でのフォーミュラの呼び出しは禁止することができます。querySettings 引数の詳細を参照してください。

フォーミュラに引数を渡す

query() メンバーメソッド内で呼び出されたformula 引数のどんなフォーミュラも、引数を受け取ることができます:

• 引数は、querySettings 引数のargs プロパティ(オブジェクト)を通して渡さなければなりません。
• フォーミュラはargs オブジェクトを$1 引数に受け取ります。

以下の短いコードは引数がどのようにメソッドに渡されるかという仕組みを示しています:

さらなる使用例は、例題3にて提供されています。

4D Server: クライアント/サーバーにおいては、フォーミュラはサーバーで実行されます。このコンテキストにおいては、querySettings.args オブジェクトのみがフォーミュラに送信されます。

4D では、queryString 引数内のattributePath 、formula および value 引数に対してプレースホルダーを使用することができます。プレースホルダーとは、クエリ文字列に挿入する引数で、クエリ文字列が評価される時に他の値で置き換えられるものです。プレースホルダーの値はクエリの開始時に一度だけ評価されます。各要素に対して毎回評価されるわけではありません。

プレースホルダーには二つの種類があります。インデックスプレースホルダーおよび命名プレースホルダーです:

queryString 引数では全ての種類の引数を混ぜて使用することができます。queryString 引数では、attributePath 引数とformula 引数と value 引数に以下のものを含めることができます:

• 値を直接渡す(プレースホルダーを使用しない)
• インデックスプレースホルダーまたは命名プレースホルダー

以下の理由から、クエリでのプレースホルダーの使用は推奨されます:

1. 悪意あるコードの挿入を防ぐ: ユーザーが入力した変数をクエリ文字列として直接使用した場合、ユーザーは余計なクエリ引数を入力する事でクエリ条件を変更する可能性があります。例えば、以下のようなクエリ文字列の場合を考えます:
   
    $vquery:="status = 'public' & name = "+myname //ユーザーが名前を入力する
   
   このクエリは非公開のデータはフィルタリングされているため、一見安全なように見えます。しかしながら、もしユーザーが例えばmyname エリアに"smith OR status='private' のようなものを入力した場合、クエリ文字列は解釈時に変更され、非公開なデータも返してしまう可能性があります。
   プレースホルダーを使用した場合、セキュリティ条件を上書きすることは不可能です:
   
    $result:=$col.query("status='public' & name=:1";myname)
   
   この場合、ユーザーがmyname エリアにsmith OR status='private' と入力した場合でも、それはクエリ文字列とはみなされず、値として渡されるだけです。"smith OR status='private' " という名前の人物を検索したところで、結果は失敗に終わるだけです。
2. フォーマットや文字の問題を心配する必要がありません。これは特に、attributePath または value 引数が例えば"."、 "['...などの英数字でない文字を格納している可能性がある場合に有用です。
3. クエリ引数の中に変数や式を使用する事ができます。例:
   
    $result:=$col.query("address.city = :1 & name =:2";$city;$myVar+"@")
 $result2:=$col.query("company.name = :1";"John's Pizzas")

null値の検索
null 値を検索する場合、プレースホルダーシンタックスは使用できません。なぜならクエリエンジンはnull を予期せぬ比較値としてみなすからです。例えば、以下のクエリを実行した場合:

コレクション内のオブジェクトの属性内を、AND 演算子で結合された複数のクエリ引数を使用して検索する場合、異なる要素の中に条件値が含まれるエンティティではなく、全ての検索条件に合致するエンティティのみを取得したい場合があるかもしれません。このような検索をするためには、リンクされた引数を格納した単一の要素のみが見つかるように、クエリ引数をコレクションの要素に リンクする 必要があります。

例えば、以下の二つのエンティティを考えます: 

エンティティ 1:
ds.People.name: "martin"
ds.People.places: 
    { "locations" : [ {
                "kind":"home",
                "city":"paris" 
            } ] }

Entity 2:
ds.People.name: "smith"
ds.People.places: 
    { "locations" : [ {
                "kind":"home",
                "city":"lyon" 
            } , {
                "kind":"office",
                "city":"paris" 
            } ] }

locationn のkind が"home"であり、そのcity が"paris" である人を探したい場合を考えます。以下のように書いた場合:

... このクエリは"martin"と"smith" の両方を返します。何故なら"smith" も"kind" 属性が"home" である"location" を持っており、"city"が"paris"である"location" を持っているからです(ですがこれら2つは異なる要素です)。

同じコレクション要素内にある合致する引数があるエンティティのみを取得したい場合、引数をリンクする必要があります。クエリ引数をリンクするためには、以下のようにしてください:

• [] で囲まれた文字を最初のパスに追加し、リンクした条件引数に対して同じ文字を繰り返します。例: locations[a].city と locations[a].kind アルファベット文字であればどの文字でも使用可能です(大文字と小文字は区別されません)。
• 同じクエリ内にて異なるリンクされた条件を追加するためには、他のアルファベット文字を使用します。単一のクエリ内では、最大で26個の組み合わせた検索条件を使用することができます。

上記の2つのエンティティにおいては、以下のように書いた場合:

... クエリの結果は"martin" のみを返します。"kind"属性が"home"でありかつ"city"が"paris"であるエンティティはこれだけだからです。"smith"は"home" と"paris" が同じコレクション要素内にないため、クエリの結果には含まれません。

querySettings 引数には追加のオプションを格納したオブジェクトを渡す事ができます。以下のプロパティがサポートされます:

queryPlan と queryPath について
queryPlan/queryPath に格納されている情報には、クエリの種類(インデックス付きとシーケンシャル)とそれぞれに必要な寒クエリとその連結演算子が含まれます。クエリパスは見つかったエンティティの数と各検索条件を実行するににかかった時間も含まれます。この情報は、アプリケーションの開発中であれば解析することで有効に活用できます。一般的には、クエリプランとクエリパスの詳細は同一になるはずですが、4D はパフォーマンスの向上のために、クエリ実行時に動的な最適化を実装する事があるからです。例えば、4D エンジンは、そちらの方が早いと判断した場合には、インデックス付きクエリをシーケンシャルなものへと動的に変換する事があります。これは検索されているエンティティの数が少ないときに起き得ます。

例えば、以下のクエリを実行した場合を考えます:

queryPlan:

queryPath:

この章では様々なクエリの例を紹介しています。

文字列をクエリ:

NOT 節を用いたクエリ:

日付をクエリ:

値に対してインデックスプレースホルダーを使用したクエリ:

リレートされたデータクラスの値に対してインデックスプレースホルダーを使用したクエリ:

降順の宣言を含んだインデックスプレースホルダーを使用したクエリ:

値に対して命名プレースホルダーを使用したクエリ:

値に対して命名プレースホルダーとインデックスプレースホルダーの両方を使用したクエリ:

queryPlan および queryPath オブジェクトがあるクエリ:

Collection 型の属性パスを用いたクエリ:

Collection 型の属性パスとリンクされた属性を使用したクエリ:

Collection 型の属性パスと複数のリンクされた属性を使用したクエリ:

Object 型の属性パスを用いたクエリ:

IN 節を用いたクエリ:

NOT (IN) 節を用いたクエリ:

属性に対してインデックスプレースホルダーを使用したクエリ:

属性にインデックスプレースホルダーを、値に命名プレースホルダーを使用したクエリ: 

属性と値に対してインデックスプレースホルダーを使用したクエリ: 

この章では属性に対して命名プレースホルダーを使用するクエリを紹介しています。

2つのエンティティをもつEmployee データクラスを考えます:

• エンティティ 1:
  name: "Marie"
  number: 46
  softwares:{
  "Word 10.2": "Installed",
  "Excel 11.3": "To be upgraded",
  "Powerpoint 12.4": "Not installed"
  }
• エンティティ 2:
  name: "Sophie"
  number: 47
  softwares:{
  "Word 10.2": "Not installed",
  "Excel 11.3": "To be upgraded",
  "Powerpoint 12.4": "Not installed" 
  }

属性に対して命名プレースホルダーを使用したクエリ:

属性と値に対して命名プレースホルダーを使用したクエリ:

以下は、クエリ内において引数ありまたは引数なしでフォーミュラを使用する様々な方法を紹介しているものです。

フォーミュラがqueryString 引数内のeval() でテキストとして渡されている方法:

フォーミュラがプレースホルダーを通してフォーミュラオブジェクトとして渡されている方法:

フォーミュラオブジェクトのみが条件として渡されている方法:

複数のフォーミュラを適用することもできます:

queryString 引数内のテキストフォーミュラが引数を受け取る方法:

同じcheckName メソッドを使用して、プレースホルダーとしてのフォーミュラオブジェクトが引数を受け取る方法:

ユーザーがクエリを入力した場合などに、フォーミュラを禁止する方法: