メインコンテンツまでスキップ
バージョン: 次へ

$filter

データクラスまたはメソッドが返すデータをフィルターします (例: $filter="firstName!='' AND salary>30000")

説明

このパラメーターを使って、データクラスまたはメソッドが返すデータに対するフィルターを定義することができます。

単純なフィルターの利用

フィルターは次の要素で構成されます:

{attribute} {comparator} {value}

たとえば $filter="firstName=john" の場合、firstName属性 (attribute)=比較演算子 (comparator)john値 (value) にあたります。

複雑なフィルターの利用

複雑なフィルターは複数の単純なフィルターの組み合わせで構成されます:

{attribute} {comparator} {value} {AND/OR/EXCEPT} {attribute} {comparator} {value}

たとえば: $filter="firstName=john AND salary>20000"firstName および salary は Employee データクラスの属性です)。

paramsプロパティの使用

You can also use 4D's params property which is a collection of values.

{attribute} {comparator} {placeholder} {AND/OR/EXCEPT} {attribute} {comparator} {placeholder}&$params='["{value1}","{value2}"]'

たとえば: $filter="firstName=:1 AND salary>:2"&$params='["john",20000]' (firstName および salary は Employee データクラスの属性です)。

4D においてデータをクエリする方法についての詳細は、dataClass.query() ドキュメンテーションを参照ください。

単一引用符 (') または二重引用符 (") を挿入するには、対応する文字コードを使ってそれらをエスケープする必要があります:

  • 単一引用符 ('): \u0027
  • 二重引用符 ("): \u0022
  • たとえば、単一引用符が含まれる値を params プロパティに渡すには、次のように書きます:
    http://127.0.0.1:8081/rest/Person/?$filter="lastName=:1"&$params='["O\u0027Reilly"]'

    値を直接渡す場合は、次のように書けます: http://127.0.0.1:8081/rest/Person/?$filter="lastName=O'Reilly"

    属性

    同じデータクラスに属している属性はそのまま受け渡せます (: firstName)。 別のデータクラスをクエリする場合は、リレーション名と属性、つまりパスを渡さなくてはなりません (: employer.name)。 属性名の文字の大小は区別されます (firstNameFirstName は異なります)。

    オブジェクト型属性もドット記法によってクエリできます。 たとえば、"objAttribute" という名称のオブジェクト属性が次の構造を持っていた場合:

    {
    prop1: "一つ目のプロパティです",
    prop2: 9181,
    prop3: ["abc","def","ghi"]
    }

    このオブジェクトをクエリするには、次のように書きます:

    GET /rest/Person/?filter="objAttribute.prop2 == 9181"

    比較演算子

    以下の比較演算子を使用できます:

    比較演算子説明
    =等しい
    !=等しくない
    >大きい
    > =以上
    <小さい
    <=以下
    begin前方一致

    Vector similarity

    If the attribute stores vector objects (see how to configure a 4D field to only store 4D.Vector class objects), you can filter the dataclass using vectors, aka embeddings.

    For more information about vector similarity searches, please refer to Query by vector similarity section.

    Use the params property to provide the filter with the vector comparison parameter, using a syntax like:

    {vectorAttribute} {comparator} {placeholder}&$params=vectorComparison

    The vectorComparison parameter is a collection of the following elements:

    プロパティ説明
    [].vectorObject の Collection)必須設定です。 A collection that represents the vector to compare
    [].metricText任意。 Vector computation to use for the query. Supported values:
  • "cosine" (default if omitted): calculates the cosine distance between vectors.
  • "dot": calculates the dot similarity of vectors.
  • "euclidean": calculates the Euclidean distance between vectors.
  • [].thresholdRealOptional (default: 0.5). A threshold value used to filter vector comparisons based on their cosine, dot or euclidean similarity score according to the selected "metric". It is highly recommended to choose a similarity that best fits your specific use case for optimal results.

    Only a subset of comparator symbols are supported with vector comparisons. Note that they compare results to the threshold value:

    比較演算子記号説明
    小さい<Lower than the threshold
    大きい>Greater than the threshold
    以下<=Lower than or equal to the threshold
    以上> =Greater than or equal to the threshold

    例題

    名字が "j" で始まる社員を検索します:

     GET  /rest/Employee?$filter="lastName begin j"

    Employee データクラスより、給与が 20,000 超で、かつ Acme という名称の企業で働いていない社員を検索します:

     GET  /rest/Employee?$filter="salary>20000 AND  
    employer.name!=acme"&$orderby="lastName,firstName"

    Person データクラスより、anotherobj オブジェクト属性の number プロパティが 50 より大きい人のデータを検索します:

     GET  /rest/Person/?filter="anotherobj.mynum > 50"

    In this example, we do a vector search with basic values:

     GET  /rest/Person/?filter="VectorAtt>=:1"&$params='[{vector:[1,2,3],threshold:1}]'