Predicate¶
- class Predicate[source]¶
Bases:
object
Represents a map entry predicate. Implementations of this class are basic building blocks for performing queries on map entries.
Special Attributes
The predicates that accept an attribute name support two special attributes:
__key
- instructs the predicate to act on the key associated with an item.this
- instructs the predicate to act on the value associated with an item.
Attribute Paths
Dot notation may be used for attribute name to instruct the predicate to act on the attribute located at deeper level of an item. Given
"full_name.first_name"
path the predicate will act onfirst_name
attribute of the value fetched byfull_name
attribute from the item itself. If any of the attributes along the path can’t be resolved,IllegalArgumentError
will be thrown. Reading of any attribute fromNone
will produceNone
value.Square brackets notation may be used to instruct the predicate to act on the list element at the specified index. Given
"names[0]"
path the predicate will act on the first item of the list fetched bynames
attribute from the item. The index must be non-negative, otherwiseIllegalArgumentError
will be thrown. Reading from the index pointing beyond the end of the list will produceNone
value.Special
any
keyword may be used to act on every list element. Given"names[any].full_name.first_name"
path the predicate will act onfirst_name
attribute of the value fetched byfull_name
attribute from every list element stored in the item itself undernames
attribute.Handling of None
The predicates that accept
None
as a value to compare with or a pattern to match against if and only if that is explicitly stated in the method documentation. In this case, the usual equality logic applies: ifNone
is provided, the predicate passes an item if and only if the value stored under the item attribute in question is alsoNone
.Special care must be taken while comparing with
None
values stored inside items being filtered through the predicates created by the following methods:greater()
,greater_or_equal()
,less()
,less_or_equal()
,between()
. They always evaluate toFalse
and therefore never pass such items.Implicit Type Conversion
If the type of the stored value doesn’t match the type of the value provided to the predicate, implicit type conversion is performed before predicate evaluation. The provided value is converted to match the type of the stored attribute value. If no conversion matching the type exists,
IllegalArgumentError
is thrown.
- class PagingPredicate[source]¶
Bases:
Predicate
This class is a special Predicate which helps to get a page-by-page result of a query.
It can be constructed with a page-size, an inner predicate for filtering, and a comparator for sorting. This class is not thread-safe and stateless. To be able to reuse for another query, one should call
reset()
.- next_page() int [source]¶
Sets page index to next page.
If new index is out of range, the query results that this paging predicate will retrieve will be an empty list.
- Returns:
Updated page index
- previous_page() int [source]¶
Sets page index to previous page.
If current page index is 0, this method does nothing.
- Returns:
Updated page index.
- property page: int¶
The current page index.
- Getter:
Returns the current page index.
- Setter:
Sets the current page index. If the page is out of range, the query results that this paging predicate will retrieve will be an empty list. New page index must be greater than or equal to
0
.
- property page_size: int¶
The page size.
- Getter:
Returns the page size.
- sql(expression: str) Predicate [source]¶
Creates a predicate that will pass items that match the given SQL
where
expression.The following operators are supported:
=
,<
,>
,<=
,>=
==
,!=
,<>
,BETWEEN
,IN
,LIKE
,ILIKE
,REGEX
AND
,OR
,NOT
.The operators are case-insensitive, but attribute names are case sensitive.
Example:
active AND (age > 20 OR salary < 60000)
Differences to standard SQL:
We don’t use ternary boolean logic.
field=10
evaluates tofalse
, iffield
isnull
, in standard SQL it evaluates toUNKNOWN
.IS [NOT] NULL
is not supported, use=NULL
or<>NULL
.IS [NOT] DISTINCT FROM
is not supported, but=
and<>
behave like it.
- Parameters:
expression – The
where
expression.- Returns:
The created sql predicate instance.
- equal(attribute: str, value: Any) Predicate [source]¶
Creates a predicate that will pass items if the given
value
and the value stored under the given itemattribute
are equal.- Parameters:
attribute – The attribute to fetch the value for comparison from.
value – The value to compare the attribute value against. Can be
None
.
- Returns:
The created equal predicate instance.
- not_equal(attribute: str, value: Any) Predicate [source]¶
Creates a predicate that will pass items if the given
value
and the value stored under the given itemattribute
are not equal.- Parameters:
attribute – The attribute to fetch the value for comparison from.
value – The value to compare the attribute value against. Can be
None
.
- Returns:
The created not equal predicate instance.
- like(attribute: str, pattern: Optional[str]) Predicate [source]¶
Creates a predicate that will pass items if the given
pattern
matches the value stored under the given itemattribute
.- Parameters:
attribute – The attribute to fetch the value for matching from.
pattern – The pattern to match the attribute value against. The
%
(percentage sign) is a placeholder for multiple characters, the_
(underscore) is a placeholder for a single character. If you need to match the percentage sign or the underscore character itself, escape it with the backslash, for example"\%"
string will match the percentage sign. Can beNone
.
- Returns:
The created like predicate instance.
- ilike(attribute: str, pattern: Optional[str]) Predicate [source]¶
Creates a predicate that will pass items if the given
pattern
matches the value stored under the given itemattribute
in a case-insensitive manner.- Parameters:
attribute – The attribute to fetch the value for matching from.
pattern – The pattern to match the attribute value against. The
%
(percentage sign) is a placeholder for multiple characters, the_
(underscore) is a placeholder for a single character. If you need to match the percentage sign or the underscore character itself, escape it with the backslash, for example"\%"
string will match the percentage sign. Can beNone
.
- Returns:
The created case-insensitive like predicate instance.
- regex(attribute: str, pattern: Optional[str]) Predicate [source]¶
Creates a predicate that will pass items if the given
pattern
matches the value stored under the given itemattribute
.- Parameters:
attribute – The attribute to fetch the value for matching from.
pattern – The pattern to match the attribute value against. The pattern interpreted exactly the same as described in https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html. Can be
None
.
- Returns:
The created regex predicate instance.
- and_(*predicates: Predicate) Predicate [source]¶
Creates a predicate that will perform the logical
and
operation on the given predicates.If no predicate is provided as argument, the created predicate will always evaluate to
true
and will pass any item.- Parameters:
*predicates – The child predicates to form the resulting
and
predicate from.- Returns:
The created and predicate instance.
- or_(*predicates: Predicate) Predicate [source]¶
Creates a predicate that will perform the logical
or
operation on the given predicates.If no predicate is provided as argument, the created predicate will always evaluate to
false
and will never pass any items.- Parameters:
*predicates – The child predicates to form the resulting
or
predicate from.- Returns:
The created or predicate instance.
- not_(predicate: Predicate) Predicate [source]¶
Creates a predicate that will negate the result of the given
predicate
.- Parameters:
predicate – The predicate to negate the value of.
- Returns:
The created not predicate instance.
- between(attribute: str, from_: Any, to: Any) Predicate [source]¶
Creates a predicate that will pass items if the value stored under the given item
attribute
is contained inside the given range.The range begins at the given
from_
bound and ends at the givento
bound. The bounds are inclusive.- Parameters:
attribute – The attribute to fetch the value to check from.
from – The inclusive lower bound of the range to check.
to – The inclusive upper bound of the range to check.
- Returns:
The created between predicate.
- in_(attribute: str, *values: Any) Predicate [source]¶
Creates a predicate that will pass items if the value stored under the given item
attribute
is a member of the givenvalues
.- Parameters:
attribute – The attribute to fetch the value to test from.
*values – The values set to test the membership in. Individual values can be
None
.
- Returns:
The created in predicate.
- instance_of(class_name: str) Predicate [source]¶
Creates a predicate that will pass entries for which the value class is an instance of the given
class_name
.- Parameters:
class_name – The name of class the created predicate will check for.
- Returns:
The created instance of predicate.
- false() Predicate [source]¶
Creates a predicate that will filter out all items.
- Returns:
The created false predicate.
- true() Predicate [source]¶
Creates a predicate that will pass all items.
- Returns:
The created true predicate.
- paging(predicate: Predicate, page_size: int, comparator: Optional[Any] = None) PagingPredicate [source]¶
Creates a paging predicate with an inner predicate, page size and comparator. Results will be filtered via inner predicate and will be ordered via comparator if provided.
- Parameters:
predicate – The inner predicate through which results will be filtered. Can be
None
. In that case, results will not be filtered.page_size – The page size.
comparator – The comparator through which results will be ordered. The comparision logic must be defined on the server side. Can be
None
. In that case, the results will be returned in natural order.
- Returns:
The created paging predicate.
- greater(attribute: str, value: Any) Predicate [source]¶
Creates a predicate that will pass items if the value stored under the given item
attribute
is greater than the givenvalue
.- Parameters:
attribute – The left-hand side attribute to fetch the value for comparison from.
value – The right-hand side value to compare the attribute value against.
- Returns:
The created greater than predicate.
- greater_or_equal(attribute: str, value: Any) Predicate [source]¶
Creates a predicate that will pass items if the value stored under the given item
attribute
is greater than or equal to the givenvalue
.- Parameters:
attribute – the left-hand side attribute to fetch the value for comparison from.
value – The right-hand side value to compare the attribute value against.
- Returns:
The created greater than or equal to predicate.
- less(attribute: str, value: Any) Predicate [source]¶
Creates a predicate that will pass items if the value stored under the given item
attribute
is less than the givenvalue
.- Parameters:
attribute – The left-hand side attribute to fetch the value for comparison from.
value – The right-hand side value to compare the attribute value against.
- Returns:
The created less than predicate.
- less_or_equal(attribute: str, value: Any) Predicate [source]¶
Creates a predicate that will pass items if the value stored under the given item
attribute
is less than or equal to the givenvalue
.- Parameters:
attribute – The left-hand side attribute to fetch the value for comparison from.
value – The right-hand side value to compare the attribute value against.
- Returns:
The created less than or equal to predicate.