If you need to retrieve entities by their entity primary keys, or verify that entities with particular primary keys
exist in the database, the constant filter constraint is the place to go. Filtering entities by their primary keys is
the fastest way to access entities in evitaDB.
Entity primary key in set
argument:int+
a mandatory set of entity primary keys representing the entities to be returned
The constraint limits the list of returned entities by exactly specifying their entity primary keys.
The sample query returns products whose primary keys are declared in the entityPrimaryKeyInSet constraint. The order
of the primary keys in the constraint doesn't matter. The returned entities are always returned in ascending order of
their primary keys, unless the orderBy clause is used in the query.
If you want the entities to be returned in the exact order of the primary keys used in the argument
of the entityPrimaryKeyInSet constraint, use the
entityPrimaryKeyInFilter
ordering constraint.
Scope
argument:enum(LIVE|ARCHIVED)+
mandatory one or more enum arguments representing the scope to be searched for the result
The scope (
) filtering allows you to specify
the scope in which the result is searched. Two scopes are available:
LIVE - the default scope, which searches the live data for the result
ARCHIVED - the scope that searches for the result in the archived data.
Scopes represent the means how evitaDB handles so called "soft deletes". The application can choose between a hard
delete and archiving the entity, which simply moves the entity to the archive scope. The details of the archiving
process are described in the chapter scopes and the reasons why this feature
exists are explained in the dedicated blog post.
By default, all queries behave as if the scope(LIVE) is present in the filter part, unless you explicitly specify
the scope constraint yourself. This means that no entity from the archive scope will be returned. If the entity has
a reference to an entity in the archive scope, the referenceHaving
won't be satisfied if only entities in the LIVE scope are queried. If you change the scope to scope(ARCHIVE), you
will only get entities from the archive scope. You can also mix entities from both scopes by specifying
scope(LIVE, ARCHIVE), and in such a case the referenceHaving
may also match entities from different scopes than the one being queried.
The constraint selects the scopes of the whole entity level: the filter root or the body of an entityHaving /
groupHaving. It may appear once per level, directly at the root or below a chain of and containers. An or
with one child is transparent. A second scope in the same level is refused even if identical; name all the scopes
in one constraint, in the order you prefer them. Repeated values inside that one constraint are allowed.
Inside not, an or with several children, inScope, userFilter or any other container outside this root path,
scope is refused. Keep the scope selection at the root of the same level and use inScope for conditions specific
to one scope. A hierarchy node filter and a segment's entityHaving validate their root scope but do not apply
it. See behavioral filtering for the level boundaries, advice and exceptions.
The hierarchy filters hierarchyWithin and
hierarchyWithinRoot read the hierarchy tree of every queried
scope. Each tree is searched exactly as in a query over its scope alone, and an entity of any queried scope matches
when it references a node selected in any of those trees - so scope(LIVE, ARCHIVED) returns both an archived product
placed in a live category and an archived product placed in an archived category.
Unique constraints are only enforced within the same scope. This means that two entities in different scopes can have
the same unique attribute value. When you move an entity from one scope to another, the unique constraints within
the target scope are checked and if the entity violates the unique constraint, the move is refused.
If you query entities in several scopes and use a filtering constraint that exactly matches the unique attribute
(attribute equals,
attribute in set), evitaDB prefers the entity from the first scope
specified in the scope constraint over the entities in scopes listed later in it. This means that if you query
a single entity by its unique attribute value (e.g. URL) and search for the entity in both scopes, you always get
the entity from the first scope you declare in your query: scope(LIVE, ARCHIVED) returns the live entity,
scope(ARCHIVED, LIVE) the archived one. The same applies to globally unique attributes and to unique reference
attributes inside referenceHaving, where the owner of the matching
reference in the first listed scope wins.
A negation of such a constraint (e.g. not(attributeEquals('code', 'ABC-123'))) is the complement of the preferred
answer. It therefore returns the entity from the later scope, even though that entity carries the very value.
The parent filter of hierarchyWithin is resolved in each queried scope
separately, in the hierarchy tree of that scope, and so are the having, anyHaving and excluding filters of
hierarchyWithin and
hierarchyWithinRoot. A unique value held by one category in the
live scope and by another in the archived scope therefore selects both categories, each in the tree of its own scope.
This behavior is not applied when only a partial match is used (e.g.
attribute starts with, etc.), nor to
attribute is, which considers all requested scopes.
There are a few archived entities in our demo dataset. Our schema is configured to index only the URL and code
attributes in the archived scope, so we can search for archived entities using only these attributes and, of course,
the primary key.
When we need to look up by the URL attribute, which is usually unique, there's an important difference, and that is
that the URL is only unique within its scope. This means that the same URL can be used for different entities in
different scopes. This is the case for some of our entities in our demo data set. The conflict for the unique key
between different entities is resolved by evitaDB by favouring the live entity over the archived one.