Predicate

class Predicate

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 on first_name attribute of the value fetched by full_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 from None will produce None 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 by names attribute from the item. The index must be non-negative, otherwise IllegalArgumentError will be thrown. Reading from the index pointing beyond the end of the list will produce None 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 on first_name attribute of the value fetched by full_name attribute from every list element stored in the item itself under names 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: if None is provided, the predicate passes an item if and only if the value stored under the item attribute in question is also None.

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 to False 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

Bases: hazelcast.predicate.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().

reset()

Resets the predicate for reuse.

next_page()

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

Return type

int

previous_page()

Sets page index to previous page.

If current page index is 0, this method does nothing.

Returns

Updated page index.

Return type

int

property page

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.

Type

int

property page_size

The page size.

Getter

Returns the page size.

Type

int

sql(expression)

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 to false, if field is null, in standard SQL it evaluates to UNKNOWN.

• IS [NOT] NULL is not supported, use =NULL or <>NULL.

• IS [NOT] DISTINCT FROM is not supported, but = and <> behave like it.

Parameters

expression (str) – The where expression.

Returns

The created sql predicate instance.

Return type

Predicate

equal(attribute, value)

Creates a predicate that will pass items if the given value and the value stored under the given item attribute are equal.

Parameters

• attribute (str) – 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.

Return type

Predicate

not_equal(attribute, value)

Creates a predicate that will pass items if the given value and the value stored under the given item attribute are not equal.

Parameters

• attribute (str) – 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.

Return type

Predicate

like(attribute, pattern)

Creates a predicate that will pass items if the given pattern matches the value stored under the given item attribute.

Parameters

• attribute (str) – The attribute to fetch the value for matching from.

• pattern (str) – 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 be None.

Returns

The created like predicate instance.

Return type

Predicate

See also

ilike() and regex()

ilike(attribute, pattern)

Creates a predicate that will pass items if the given pattern matches the value stored under the given item attribute in a case-insensitive manner.

Parameters

• attribute (str) – The attribute to fetch the value for matching from.

• pattern (str) – 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 be None.

Returns

The created case-insensitive like predicate instance.

Return type

Predicate

See also

like() and regex()

regex(attribute, pattern)

Creates a predicate that will pass items if the given pattern matches the value stored under the given item attribute.

Parameters

• attribute (str) – The attribute to fetch the value for matching from.

• pattern (str) – 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.

Return type

Predicate

See also

ilike() and like()

and_(*predicates)

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 (Predicate) – The child predicates to form the resulting and predicate from.

Returns

The created and predicate instance.

Return type

Predicate

or_(*predicates)

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 (Predicate) – The child predicates to form the resulting or predicate from.

Returns

The created or predicate instance.

Return type

Predicate

not_(predicate)

Creates a predicate that will negate the result of the given predicate.

Parameters

predicate (Predicate) – The predicate to negate the value of.

Returns

The created not predicate instance.

Return type

Predicate

between(attribute, from_, to)

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 given to bound. The bounds are inclusive.

Parameters

• attribute (str) – 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.

Return type

Predicate

in_(attribute, *values)

Creates a predicate that will pass items if the value stored under the given item attribute is a member of the given values.

Parameters

• attribute (str) – 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.

Return type

Predicate

instance_of(class_name)

Creates a predicate that will pass entries for which the value class is an instance of the given class_name.

Parameters

class_name (str) – The name of class the created predicate will check for.

Returns

The created instance of predicate.

Return type

Predicate

false()

Creates a predicate that will filter out all items.

Returns

The created false predicate.

Return type

Predicate

true()

Creates a predicate that will pass all items.

Returns

The created true predicate.

Return type

Predicate

paging(predicate, page_size, comparator=None)

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 (Predicate) – The inner predicate through which results will be filtered. Can be None. In that case, results will not be filtered.

• page_size (int) – The page size.

• comparator (hazelcast.serialization.api.Portable or hazelcast.serialization.api.IdentifiedDataSerializable) – 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.

Return type

PagingPredicate

greater(attribute, value)

Creates a predicate that will pass items if the value stored under the given item attribute is greater than the given value.

Parameters

• attribute (str) – 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.

Return type

Predicate

greater_or_equal(attribute, value)

Creates a predicate that will pass items if the value stored under the given item attribute is greater than or equal to the given value.

Parameters

• attribute (str) – 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.

Return type

Predicate

less(attribute, value)

Creates a predicate that will pass items if the value stored under the given item attribute is less than the given value.

Parameters

• attribute (str) – 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.

Return type

Predicate

less_or_equal(attribute, value)

Creates a predicate that will pass items if the value stored under the given item attribute is less than or equal to the given value.

Parameters

• attribute (str) – 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.

Return type

Predicate