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 both scopes using scope filter and use the filtering
constraint that exactly matches the unique attribute (attribute equals,
attribute in set, attribute is),
evitaDB will prefer the entity from the first scope specified in scope constraint over the entities in scopes defined
later in this scope constraint. 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 will always get the entity from the first scope you declare in your query.
This behavior is not applied, when only partial match is used (e.g. attribute starts with,
etc.).
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.
