Constant filtering
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.
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.
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.