Package ubic.gemma.rest.util.args

Class FilterArg<O extends Identifiable>

java.lang.Object
ubic.gemma.rest.util.args.AbstractArg<FilterArg.Filter>
ubic.gemma.rest.util.args.FilterArg<O>
All Implemented Interfaces:
Arg<FilterArg.Filter>
public class FilterArg<O extends Identifiable> extends AbstractArg<FilterArg.Filter>
Represent a filter argument designed to generate a Filters from user input.

Filtering is done by constructing predicates in the property operator requiredValue form. Properties, operators and required values must be delimited by spaces.

Properties

Filtering can be done on any property or nested property of an entity managed by a FilteringService. E.g: 'curationDetails' or 'curationDetails.lastTroubledEvent.date'.

The available filterable properties on an entity can be retrieved from FilteringService.getFilterableProperties().

Any property of a supported type. Currently, supported types are:

String
Property of String type. Strings that contain parenthesis (), comma , or space ' ' characters, or empty strings must be quoted with double-quotes ". Double-quotes can be escaped with a backslash character: \".
Number
Any Number subclasses (i.e. Float, Double, Integer, Long). Required value must be a string parseable to the specific number type.
Boolean
Required value will be parsed to true only if the string matches true, ignoring case.
Date
Property of Date, required value must be an ISO 8601 formatted date or datetime, UTC is assumed of no timezone is supplied.
Collection
Property of a Collection of any type aforementioned, nested collections are not supported. The format of collection is a sequence of comma-delimited values surrounded by parenthesis. The values must be compatible with the type contained in the collection.
Example: (1,2,3,4)

Operators

Accepted operator keywords are:
=
Equality
!=
Non-equality
<
Smaller than (only Number and Date types)
>
Larger than (only Number and Date types)
<=
Smaller or equal (only Number and Date types)
>=
Larger or equal (only Number and Date types)
like or LIKE
Similar string, effectively means 'begins with', translates to the SQL LIKE operator where a '%' is appended to the given value (only String type)
not like or NOT LIKE
Similar string, effectively means 'does not begins with', translates to the SQL NOT LIKE operator where a '%' is appended to the given value (only String type)
in or IN
Required value in the given collection with the semantic of the '=' equality operator (only for Collection types)
not in or NOT IN
Required value not in the given collection with the semantic of '=' equality operator (only for Collection types)
See Filter.Operator for more details on the available operators.

Quantifiers

If the property refers to a collection of entities, an quantifier can be used to indicate the desired behavior:
any(predicate)
True if any element of the collection satisfies the predicate.
all(predicate)
True if all elements of the collection satisfies the predicate. Note that this is true for an empty collection.
none(predicate)
True if no element of the collection satisfies the predicate. Note that this is true for an empty collection.
By default, any(predicate) is used.

Logical expressions

Multiple filters can be chained using conjunctions (i.e. AND, and) or disjunctions (i.e. OR, or, ',') keywords. Example:
property1 < value1 AND property2 like value2

Queries mixing conjunctions and disjunctions are interpreted in conjunctive normal form (CNF) without any parentheses. Every AND conjunctions separates blocks of OR disjunctions.

Example:
p1 = v1 OR p1 != v2 AND p2 <=v2 AND p3 > v3, p3 < v4

Above query will translate to:
(p1 = v1 OR p1 != v2) AND (p2 <= v2) AND (p3 > v3 OR p3 < v4)

Breaking the CNF results in an error.

Author:
tesarst, poirigui
See Also:

  • Field Details

    • MAX_CLAUSES

      public static final int MAX_CLAUSES
      Maximum number of clauses that can appear in a filter expression.
      See Also:

  • Method Details

    • valueOf

      public static <O extends Identifiable> FilterArg<O> valueOf(String s)
      Used by RS to parse value of request parameters.

      The filter string may be compressed and base64-encoded.

      Parameters:
      s - the request filter string.
      Returns:
      an instance of DatasetFilterArg representing the filtering options in the given string.