Skip to content

Commit

Permalink
doc(#677): documentation with updated examples
Browse files Browse the repository at this point in the history
  • Loading branch information
@novoj
novoj committed Dec 1, 2024
1 parent 0cde711 commit 463a6dc
Show file tree
Hide file tree
Showing 213 changed files with 4,430 additions and 1,526 deletions.
39 changes: 21 additions & 18 deletions documentation/user/en/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,30 +75,33 @@ the first version to the general public.

1. [Basics](query/basics.md)
2. **Filtering**
1. [Constant](query/filtering/constant.md)
1. [Behavioral](query/filtering/behavioral.md)
2. [Comparable](query/filtering/comparable.md)
3. [Logical](query/filtering/logical.md)
4. [String](query/filtering/string.md)
3. [Constant](query/filtering/constant.md)
4. [Hierarchy](query/filtering/hierarchy.md)
5. [Locale](query/filtering/locale.md)
6. [Range](query/filtering/range.md)
6. [Logical](query/filtering/logical.md)
7. [Price](query/filtering/price.md)
8. [References](query/filtering/references.md)
9. [Hierarchy](query/filtering/hierarchy.md)
10. [Behavioral filter containers](query/filtering/behavioral.md)
8. [Range](query/filtering/range.md)
9. [References](query/filtering/references.md)
10. [String](query/filtering/string.md)
3. **Ordering**
1. [Constant](query/ordering/constant.md)
1. [Comparable](query/ordering/comparable.md)
2. [Price](query/ordering/price.md)
3. [Reference](query/ordering/reference.md)
4. [Random](query/ordering/random.md)
4. [Segmentation](query/ordering/segment.md)
1. [Behavioral](query/ordering/behavioral.md)
2. [Comparable](query/ordering/comparable.md)
3. [Constant](query/ordering/constant.md)
4. [Price](query/ordering/price.md)
5. [Random](query/ordering/random.md)
6. [Reference](query/ordering/reference.md)
7. [Segmentation](query/ordering/segment.md)
4. **Requirements**
1. [Paging](query/requirements/paging.md)
2. [Fetching](query/requirements/fetching.md)
3. [Price](query/requirements/price.md)
1. [Behavioral](query/requirements/behavioral.md)
2. [Facet](query/requirements/facet.md)
3. [Fetching](query/requirements/fetching.md)
4. [Hierarchy](query/requirements/hierarchy.md)
5. [Facet](query/requirements/facet.md)
6. [Histogram](query/requirements/histogram.md)
5. [Histogram](query/requirements/histogram.md)
6. [Paging](query/requirements/paging.md)
7. [Price](query/requirements/price.md)
8. [Telemetry](query/requirements/telemetry.md)

## Operate

Expand Down
72 changes: 40 additions & 32 deletions documentation/user/en/menu.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,58 +98,66 @@
"title": "Filtering",
"children": [
{
"title": "Constant",
"path": "/query/filtering/constant.md"
},
{
"title": "Logical",
"path": "/query/filtering/logical.md"
"title": "Behavioral",
"path": "/query/filtering/behavioral.md"
},
{
"title": "Comparable",
"path": "/query/filtering/comparable.md"
},
{
"title": "String",
"path": "/query/filtering/string.md"
"title": "Constant",
"path": "/query/filtering/constant.md"
},
{
"title": "Locale",
"path": "/query/filtering/locale.md"
},
{
"title": "Range",
"path": "/query/filtering/range.md"
"title": "Logical",
"path": "/query/filtering/logical.md"
},
{
"title": "Hierarchy",
"path": "/query/filtering/hierarchy.md"
},
{
"title": "Price",
"path": "/query/filtering/price.md"
},
{
"title": "References",
"path": "/query/filtering/references.md"
"title": "Range",
"path": "/query/filtering/range.md"
},
{
"title": "Hierarchy",
"path": "/query/filtering/hierarchy.md"
"title": "References",
"path": "/query/filtering/references.md"
},
{
"title": "Behavioral",
"path": "/query/filtering/behavioral.md"
"title": "String",
"path": "/query/filtering/string.md"
}
]
},
{
"title": "Ordering",
"children": [
{
"title": "Constant",
"path": "/query/ordering/constant.md"
"title": "Behavioral",
"path": "/query/ordering/behavioral.md"
},
{
"title": "Comparable",
"path": "/query/ordering/comparable.md"
},
{
"title": "Constant",
"path": "/query/ordering/constant.md"
},
{
"title": "Random",
"path": "/query/ordering/random.md"
},
{
"title": "Price",
"path": "/query/ordering/price.md"
Expand All @@ -158,10 +166,6 @@
"title": "Reference",
"path": "/query/ordering/reference.md"
},
{
"title": "Random",
"path": "/query/ordering/random.md"
},
{
"title": "Segmentation",
"path": "/query/ordering/segment.md"
Expand All @@ -172,29 +176,33 @@
"title": "Requirements",
"children": [
{
"title": "Paging",
"path": "/query/requirements/paging.md"
"title": "Behavioral",
"path": "/query/requirements/behavioral.md"
},
{
"title": "Fetching",
"path": "/query/requirements/fetching.md"
"title": "Facet",
"path": "/query/requirements/facet.md"
},
{
"title": "Price",
"path": "/query/requirements/price.md"
"title": "Fetching",
"path": "/query/requirements/fetching.md"
},
{
"title": "Hierarchy",
"path": "/query/requirements/hierarchy.md"
},
{
"title": "Facet",
"path": "/query/requirements/facet.md"
},
{
"title": "Histogram",
"path": "/query/requirements/histogram.md"
},
{
"title": "Paging",
"path": "/query/requirements/paging.md"
},
{
"title": "Price",
"path": "/query/requirements/price.md"
},
{
"title": "Telemetry",
"path": "/query/requirements/telemetry.md"
Expand Down
98 changes: 49 additions & 49 deletions documentation/user/en/query/filtering/behavioral.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,16 +45,56 @@ The [scope](#scope) filter constraint allows us to query entities in both scopes
we couldn't tell which filter constraint to apply to which scope. The `inScope` container is designed to handle this
situation.

<Note type="info">

It's obvious that the `inScope` container is not necessary if we are only querying entities in one scope. However, if
you do use it in this case, it must match the scope of the query. If you use the `inScope` container with the `LIVE`
scope, but the query is executed in the `ARCHIVED` scope, the engine will return an error.

</Note>


For example, in our demo dataset we have only a few attributes indexed in the archive - namely `url` and `code` and
a few others. We don't index references, hierarchy or prices. If we want to search for entities in both scopes and use
appropriate filter constraints, we can use the `inScope` container in the following way:
a few others. We don't index references, hierarchy or prices in archive scope. If we want to search for entities in both
scopes and use appropriate filter constraints, we need to use the `inScope` container in the following way:

<SourceCodeTabs requires="evita_functional_tests/src/test/resources/META-INF/documentation/evitaql-init.java" langSpecificTabOnly>

[Disginguishing filters in different scopes](/documentation/user/en/query/filtering/examples/behavioral/archived-entities-filtering.evitaql)

</SourceCodeTabs>

<Note type="info">

<NoteTitle toggles="true">

##### The result of selected entities in multiple scopes
</NoteTitle>

The result contains two entities selected by the URL attribute. The entity in the live scope also satisfies
the hierarchy and price constraints specified in the `inScope` container. However, these constraints may not be valid
for the entity in the archive scope, as can be seen by looking at the input query.

<LS to="e,j,c">

<MDInclude sourceVariable="recordPage">[The result of selected entities in multiple scopes](/documentation/user/en/query/filtering/examples/behavioral/archived-entities-filtering.evitaql.md)</MDInclude>

</LS>
<LS to="r">

<MDInclude sourceVariable="recordPage">[The result of selected entities in multiple scopes](/documentation/user/en/query/filtering/examples/behavioral/archived-entities-filtering.rest.json.md)</MDInclude>

</LS>

</Note>

<Note type="info">

Similar `inScope` containers are available for [order constraints](../ordering/behavioral.md#in-scope)
and [requirements constraints](../requirements/behavioral.md#in-scope) with the same purpose and meaning.

</Note>

## Scope

```evitaql-syntax
Expand Down Expand Up @@ -97,9 +137,10 @@ the target scope are checked and if the entity violates the unique constraint, t
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](../filtering/comparable.md#attribute-equals),
[attribute in set](../filtering/comparable.md#attribute-in-set), [attribute is](../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. This behavior is not applied, when only partial match is used (e.g. [attribute starts with](../filtering/string.md#attribute-starts-with),
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](../filtering/string.md#attribute-starts-with),
etc.).

</Note>
Expand All @@ -123,12 +164,12 @@ the primary key.

<LS to="e,j,c">

<MDInclude sourceVariable="recordPage">[The result of querying archived entities](/documentation/user/en/query/filtering/examples/fetching/archived-entities-listing.evitaql.md)</MDInclude>
<MDInclude sourceVariable="recordPage">[The result of querying archived entities](/documentation/user/en/query/filtering/examples/behavioral/archived-entities-listing.evitaql.md)</MDInclude>

</LS>
<LS to="r">

<MDInclude sourceVariable="recordPage">[The result of querying archived entities](/documentation/user/en/query/filtering/examples/fetching/archived-entities-listing.rest.json.md)</MDInclude>
<MDInclude sourceVariable="recordPage">[The result of querying archived entities](/documentation/user/en/query/filtering/examples/behavioral/archived-entities-listing.rest.json.md)</MDInclude>

</LS>

Expand All @@ -137,48 +178,7 @@ 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. See the following
example:

<SourceCodeTabs requires="evita_functional_tests/src/test/resources/META-INF/documentation/evitaql-init.java" langSpecificTabOnly>

[Resolving conflicting entities example](/documentation/user/en/query/filtering/examples/fetching/archived-entities-conflict.evitaql)

</SourceCodeTabs>

Producing the following result:

<LS to="e,j,c">

<MDInclude sourceVariable="recordPage">[The result of querying conflicting entities](/documentation/user/en/query/filtering/examples/fetching/archived-entities-conflict.evitaql.md)</MDInclude>

</LS>
<LS to="r">

<MDInclude sourceVariable="recordPage">[The result of querying conflicting entities](/documentation/user/en/query/filtering/examples/fetching/archived-entities-conflict.rest.json.md)</MDInclude>

</LS>

We can still access the archived entity via its `URL` property if we are only looking in the archived scope:

<SourceCodeTabs requires="evita_functional_tests/src/test/resources/META-INF/documentation/evitaql-init.java" langSpecificTabOnly>

[Accessing archived entity by URL](/documentation/user/en/query/filtering/examples/fetching/archived-entity-conflict-access.evitaql)

</SourceCodeTabs>

Producing the following result:

<LS to="e,j,c">

<MDInclude sourceVariable="recordPage">[The result of querying archived entity by URL](/documentation/user/en/query/filtering/examples/fetching/archived-entity-conflict-access.evitaql.md)</MDInclude>

</LS>
<LS to="r">

<MDInclude sourceVariable="recordPage">[The result of querying archived entity by URL](/documentation/user/en/query/filtering/examples/fetching/archived-entity-conflict-access.rest.json.md)</MDInclude>

</LS>
between different entities is resolved by evitaDB by favouring the live entity over the archived one.

## User filter

Expand Down
23 changes: 23 additions & 0 deletions ...mentation/user/en/query/filtering/examples/behavioral/archived-entities-filtering.evitaql
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
query(
collection("Product"),
filterBy(
scope(LIVE, ARCHIVED),
attributeInSet("url", "/en/xiaomi-redmi-note-10-pro-8", "/en/apple-iphone-14"),
entityLocaleEquals("en"),
inScope(
LIVE,
hierarchyWithin(
"categories",
attributeEquals("url", "/en/cell-phones")
),
priceInPriceLists("basic"),
priceInCurrency("EUR"),
priceValidInNow()
)
),
require(
entityFetch(
attributeContent("code")
)
)
)
6 changes: 6 additions & 0 deletions ...r/en/query/filtering/examples/behavioral/archived-entities-filtering.evitaql.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
| entityPrimaryKey | Scope | code |
| ---------------- | -------- | ---------------------------- |
| 106291 | LIVE | 'apple-iphone-14' |
| 107736 | ARCHIVED | 'xiaomi-redmi-note-10-pro-7' |

###### **Page** 1/1 **(Total number of results: 2)**
Loading

0 comments on commit 463a6dc

Please sign in to comment.