Skip to content

Commit ccfbc4f

Browse files
davidmyrielAnush008kacperlukawski
authored
[Docs] Add Tutorials (#231)
* add tutorial incomplete * update multitenancy * Update src/components/InteractiveTutorial/TutorialSubpages.jsx Co-authored-by: Anush <[email protected]> * add more text * update filtering text * add more tutorials * add load content tutorial * advanced filtering * add filtering examples * add full text filtering * add tutorials * Update src/components/InteractiveTutorial/MdxPages/FilteringAdvanced.mdx Co-authored-by: Anush <[email protected]> * Update src/components/InteractiveTutorial/MdxPages/FilteringAdvanced.mdx Co-authored-by: Anush <[email protected]> * Update src/components/InteractiveTutorial/MdxPages/FilteringBeginner.mdx Co-authored-by: Anush <[email protected]> * Update src/components/InteractiveTutorial/MdxPages/FilteringFullText.mdx Co-authored-by: Anush <[email protected]> * Update src/components/InteractiveTutorial/MdxPages/Multitenancy.mdx Co-authored-by: Anush <[email protected]> * Update src/components/InteractiveTutorial/MdxPages/Multitenancy.mdx Co-authored-by: Anush <[email protected]> * Update src/components/InteractiveTutorial/MdxPages/Multivectors.mdx Co-authored-by: Anush <[email protected]> * Update src/components/InteractiveTutorial/MdxPages/HybridSearch.mdx Co-authored-by: Kacper Łukawski <[email protected]> * Update src/components/InteractiveTutorial/MdxPages/HybridSearch.mdx Co-authored-by: Kacper Łukawski <[email protected]> * Update src/components/InteractiveTutorial/MdxPages/HybridSearch.mdx Co-authored-by: Kacper Łukawski <[email protected]> * Update src/components/InteractiveTutorial/MdxPages/SparseVectors.mdx Co-authored-by: Kacper Łukawski <[email protected]> * update tutorials * update tutorials --------- Co-authored-by: Anush <[email protected]> Co-authored-by: Kacper Łukawski <[email protected]>
1 parent 776b662 commit ccfbc4f

12 files changed

+1143
-257
lines changed

‎src/components/InteractiveTutorial/MdxPages/FilteringAdvanced.mdx

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
export const title = "Advanced Filtering"
2+
3+
# Advanced Filtering - Nested Filters
4+
5+
## Step 1: Create a Collection
6+
7+
Start by creating a collection named `dinosaurs` with a vector size of 4 and the distance metric set to `Dot`:
8+
9+
```json withRunButton="true"
10+
PUT collections/dinosaurs
11+
{
12+
"vectors": {
13+
"size": 4,
14+
"distance": "Dot"
15+
}
16+
}
17+
```
18+
19+
## Step 2: Add Vectors with Payloads
20+
21+
You can now add points to the collection. Each point contains an `id`, `vector` and a `payload` with additional information such as the dinosaur species and diet preferences. For example:
22+
23+
```json withRunButton="true"
24+
PUT collections/dinosaurs/points
25+
{
26+
"points": [
27+
{
28+
"id": 1,
29+
"vector": [0.1, 0.2, 0.3, 0.4],
30+
"payload": {
31+
"dinosaur": "t-rex",
32+
"diet": [
33+
{ "food": "leaves", "likes": false },
34+
{ "food": "meat", "likes": true }
35+
]
36+
}
37+
},
38+
{
39+
"id": 2,
40+
"vector": [0.2, 0.3, 0.4, 0.5],
41+
"payload": {
42+
"dinosaur": "diplodocus",
43+
"diet": [
44+
{ "food": "leaves", "likes": true },
45+
{ "food": "meat", "likes": false }
46+
]
47+
}
48+
}
49+
]
50+
}
51+
```
52+
53+
## Step 3: Basic Filtering with `match`
54+
55+
You can filter points by specific payload values. For instance, the query below matches points where:
56+
57+
- The `diet[].food` contains "meat".
58+
- The `diet[].likes` is set to `true`.
59+
60+
Both points match these conditions, as:
61+
- The “t-rex” eats meat and likes it.
62+
- The “diplodocus” eats meat but doesn't like it.
63+
64+
```json withRunButton="true"
65+
POST /collections/dinosaurs/points/scroll
66+
{
67+
"filter": {
68+
"must": [
69+
{
70+
"key": "diet[].food",
71+
"match": {
72+
"value": "meat"
73+
}
74+
},
75+
{
76+
"key": "diet[].likes",
77+
"match": {
78+
"value": true
79+
}
80+
}
81+
]
82+
}
83+
}
84+
```
85+
86+
However, if you want to retrieve only the points where both conditions are true for the same element within the array (e.g., the "t-rex" with ID 1), you'll need to use a **nested filter**.
87+
88+
## Step 4: Advanced Filtering with Nested Object Filters
89+
90+
To apply the filter at the array element level, you use the `nested` filter condition. This ensures that the `food` and `likes` values are evaluated together within each array element:
91+
92+
```json withRunButton="true"
93+
POST /collections/dinosaurs/points/scroll
94+
{
95+
"filter": {
96+
"must": [
97+
{
98+
"nested": {
99+
"key": "diet",
100+
"filter": {
101+
"must": [
102+
{
103+
"key": "food",
104+
"match": {
105+
"value": "meat"
106+
}
107+
},
108+
{
109+
"key": "likes",
110+
"match": {
111+
"value": true
112+
}
113+
}
114+
]
115+
}
116+
}
117+
}
118+
]
119+
}
120+
}
121+
```
122+
123+
With this filter, only the "t-rex" (ID 1) is returned, because its array element satisfies both conditions.
124+
125+
### Explanation
126+
127+
Nested filters treat each array element as a separate object, applying the filter independently to each element. The parent document (in this case, the dinosaur point) matches the filter if any one array element meets all conditions.
128+
129+
## Step 5: Combining `has_id` with Nested Filters
130+
131+
Note that `has_id` cannot be used inside a nested filter. If you need to filter by ID as well, include the `has_id` condition as a separate clause, like this:
132+
133+
You won't get a different answer. You can see that this filter matches the "t-rex" (ID 1) by combining the `nested` diet filter with an explicit ID match.
134+
135+
```json withRunButton="true"
136+
POST /collections/dinosaurs/points/scroll
137+
{
138+
"filter": {
139+
"must": [
140+
{
141+
"nested": {
142+
"key": "diet",
143+
"filter": {
144+
"must": [
145+
{
146+
"key": "food",
147+
"match": {
148+
"value": "meat"
149+
}
150+
},
151+
{
152+
"key": "likes",
153+
"match": {
154+
"value": true
155+
}
156+
}
157+
]
158+
}
159+
}
160+
},
161+
{
162+
"has_id": [1]
163+
}
164+
]
165+
}
166+
}
167+
```
168+

‎src/components/InteractiveTutorial/MdxPages/FilteringBeginner.mdx

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
export const title = "Basic Filtering"
2+
3+
# Basic Filtering - Clauses and Conditions
4+
5+
## Step 1: Create a Collection
6+
7+
First, create a collection called `terraforming`. Each point will have vectors of size 4, and the distance metric is set to `Dot`:
8+
9+
```json withRunButton="true"
10+
PUT collections/terraforming
11+
{
12+
"vectors": {
13+
"size": 4,
14+
"distance": "Dot"
15+
}
16+
}
17+
```
18+
19+
## Step 2: Add Points with Vectors and Payloads
20+
21+
Now, add points to the collection. Each point includes an `id`, `vector` and a `payload` with various attributes like `land type`, `color`, `life presence`, and `humidity`:
22+
23+
```json withRunButton="true"
24+
PUT collections/terraforming/points
25+
{
26+
"points": [
27+
{
28+
"id": 1,
29+
"vector": [0.1, 0.2, 0.3, 0.4],
30+
"payload": {"land": "forest", "color": "green", "life": true, "humidity": 40}
31+
},
32+
{
33+
"id": 2,
34+
"vector": [0.2, 0.3, 0.4, 0.5],
35+
"payload": {"land": "lake", "color": "blue", "life": true, "humidity": 100}
36+
},
37+
{
38+
"id": 3,
39+
"vector": [0.3, 0.4, 0.5, 0.6],
40+
"payload": {"land": "steppe", "color": "green", "life": false, "humidity": 25}
41+
},
42+
{
43+
"id": 4,
44+
"vector": [0.4, 0.5, 0.6, 0.7],
45+
"payload": {"land": "desert", "color": "red", "life": false, "humidity": 5}
46+
},
47+
{
48+
"id": 5,
49+
"vector": [0.5, 0.6, 0.7, 0.8],
50+
"payload": {"land": "marsh", "color": "black", "life": true, "humidity": 90}
51+
},
52+
{
53+
"id": 6,
54+
"vector": [0.6, 0.7, 0.8, 0.9],
55+
"payload": {"land": "cavern", "color": "black", "life": false, "humidity": 15}
56+
}
57+
]
58+
}
59+
```
60+
61+
## Step 3: Filtering examples
62+
63+
### Filter by exact match
64+
65+
Finally, this query retrieves points where the `color` is `"black"`, using a straightforward `match` condition:
66+
67+
```json withRunButton="true"
68+
POST collections/terraforming/points/scroll
69+
{
70+
"filter": {
71+
"must": [
72+
{
73+
"key": "color",
74+
"match": {
75+
"value": "black"
76+
}
77+
}
78+
]
79+
},
80+
"limit": 3,
81+
"with_payload": true
82+
}
83+
```
84+
85+
### Combined filter by `must` clause
86+
87+
In this example, the query returns points where `life` is `true` and `color` is `"green"`. These must conditions both need to be met for a point to be returned.
88+
89+
```json withRunButton=true
90+
POST collections/terraforming/points/scroll
91+
{
92+
"filter": {
93+
"must": [
94+
{ "key": "life", "match": { "value": true } },
95+
{ "key": "color", "match": { "value": "green" } }
96+
]
97+
},
98+
"limit": 3,
99+
"with_payload": true
100+
}
101+
```
102+
103+
### Filter by `should` clause
104+
105+
Here, you are filtering for points where `life` is `false` and `color` is `"black"`. These conditions act as *should* clauses, meaning points meeting either or both criteria will be returned:
106+
107+
```json withRunButton=true
108+
POST collections/terraforming/points/scroll
109+
{
110+
"filter": {
111+
"should": [
112+
{
113+
"key": "life",
114+
"match": { "value": false }
115+
}, {
116+
"key": "color",
117+
"match": { "value": "black" }
118+
}
119+
]
120+
}
121+
}
122+
```
123+
124+
### Filter by `must_not` clause
125+
126+
This query filters out any points where `life` is `false`. Points matching this condition are excluded from the results.
127+
128+
```json withRunButton=true
129+
POST collections/terraforming/points/scroll
130+
{
131+
"filter": {
132+
"must_not": [
133+
{
134+
"key": "life",
135+
"match": { "value": false }
136+
}
137+
]
138+
},
139+
"limit": 3,
140+
"with_payload": true
141+
}
142+
```
143+
144+
### Filter by `range` condition
145+
146+
This query filters points based on a range of `humidity`. Here, the `humidity` value must be exactly 40:
147+
148+
```json withRunButton="true"
149+
POST collections/terraforming/points/scroll
150+
{
151+
"filter": {
152+
"must": [
153+
{
154+
"key": "humidity",
155+
"range": {
156+
"gte": 40,
157+
"lte": 40
158+
}
159+
}
160+
]
161+
},
162+
"limit": 3,
163+
"with_payload": true
164+
}
165+
```

0 commit comments

Comments
 (0)