Skip to content

Commit

Permalink
doc: reflected references are not allowed across scopes
Browse files Browse the repository at this point in the history
Updated documentation.
  • Loading branch information
novoj committed Dec 18, 2024
1 parent c52c00a commit cb4ad4e
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 23 deletions.
10 changes: 9 additions & 1 deletion documentation/user/en/query/filtering/behavioral.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,9 +124,17 @@ the scope in which the result is searched. Two scopes are available:

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 [Archiving](../../use/schema.md#scopes) and the reasons why this feature
process are described in the chapter [scopes](../../use/schema.md#scopes) and the reasons why this feature
exists are explained in the [dedicated blog post](https://evitadb.io/blog/15-soft-delete).

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`](../filtering/references.md#reference-having)
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`](../filtering/references.md#reference-having)
may also match entities from different scopes than the one being queried.

<Note type="warning">

<NoteTitle toggles="true">
Expand Down
34 changes: 12 additions & 22 deletions documentation/user/en/use/schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -653,28 +653,18 @@ the more indexes you maintain, the more memory and CPU resources you will consum

### Changes in reference behavior

When you move an entity from one scope to another, the original references remain intact, while reflected references are
removed if they refer to an entity that does not exist in the target scope. Reflected references are something that is
maintained by the evitaDB engine, and it requires appropriate indexes to be present in the target scope in order to work.
This cannot be guaranteed in the archive scope (on the contrary, it is expected that the indexes in the archive scope -
because that's the default behaviour).

Therefore, the reflected references are removed when the entity is moved to the archive scope. The engine can recreate
them in the archive scope if there is an index configured in the target entity type for the archive scope and the target
entity is also present in the archive scope.

### Changes in unique constraints behavior

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](../query/filtering/behavioral.md#scope) filter and use the filtering
constraint that exactly matches the unique attribute ([attribute equals](../query/filtering/comparable.md#attribute-equals),
[attribute in set](../query/filtering/comparable.md#attribute-in-set), [attribute is](../query/filtering/comparable.md#attribute-is)),
evitaDB will prefer the entity from the live scope over the entity from the archive scope. 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 live scope.
When you move an entity from one scope to another, the original references are retained, while the reflected references
are removed if either of the following conditions is not met

- the reflected reference schema is not marked as *indexed* in the target scope
- the primary reference schema (i.e. the original reference being reflected) is not marked as *indexed* in the target scope.

Reflected references are something that is maintained by the evitaDB engine, and it requires appropriate indexes to be
present in the target scope in order to work. By default, the archive scope does not maintain any indexes other than
the primary key and a few others explicitly specified by you in the entity schema.

Therefore, the reflected references are usually removed when the entity is moved to the archive scope. The engine can
recreate them if the entity is moved back to the live scope where appropriate indexes exist.

## What's next?

Expand Down

0 comments on commit cb4ad4e

Please sign in to comment.