Skip to content

Commit

Permalink
[Docs] Add Tutorials (#231)
Browse files Browse the repository at this point in the history 
* 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]>
  • Loading branch information
@davidmyriel @Anush008 @kacperlukawski
3 people authored Oct 4, 2024
1 parent 776b662 commit ccfbc4f
Show file tree
Hide file tree
Showing 12 changed files with 1,143 additions and 257 deletions.
168 changes: 168 additions & 0 deletions src/components/InteractiveTutorial/MdxPages/FilteringAdvanced.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,168 @@
export const title = "Advanced Filtering"

# Advanced Filtering - Nested Filters

## Step 1: Create a Collection

Start by creating a collection named `dinosaurs` with a vector size of 4 and the distance metric set to `Dot`:

```json withRunButton="true"
PUT collections/dinosaurs
{
"vectors": {
"size": 4,
"distance": "Dot"
}
}
```

## Step 2: Add Vectors with Payloads

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:

```json withRunButton="true"
PUT collections/dinosaurs/points
{
"points": [
{
"id": 1,
"vector": [0.1, 0.2, 0.3, 0.4],
"payload": {
"dinosaur": "t-rex",
"diet": [
{ "food": "leaves", "likes": false },
{ "food": "meat", "likes": true }
]
}
},
{
"id": 2,
"vector": [0.2, 0.3, 0.4, 0.5],
"payload": {
"dinosaur": "diplodocus",
"diet": [
{ "food": "leaves", "likes": true },
{ "food": "meat", "likes": false }
]
}
}
]
}
```

## Step 3: Basic Filtering with `match`

You can filter points by specific payload values. For instance, the query below matches points where:

- The `diet[].food` contains "meat".
- The `diet[].likes` is set to `true`.

Both points match these conditions, as:
- The “t-rex” eats meat and likes it.
- The “diplodocus” eats meat but doesn't like it.

```json withRunButton="true"
POST /collections/dinosaurs/points/scroll
{
"filter": {
"must": [
{
"key": "diet[].food",
"match": {
"value": "meat"
}
},
{
"key": "diet[].likes",
"match": {
"value": true
}
}
]
}
}
```

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**.

## Step 4: Advanced Filtering with Nested Object Filters

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:

```json withRunButton="true"
POST /collections/dinosaurs/points/scroll
{
"filter": {
"must": [
{
"nested": {
"key": "diet",
"filter": {
"must": [
{
"key": "food",
"match": {
"value": "meat"
}
},
{
"key": "likes",
"match": {
"value": true
}
}
]
}
}
}
]
}
}
```

With this filter, only the "t-rex" (ID 1) is returned, because its array element satisfies both conditions.

### Explanation

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.

## Step 5: Combining `has_id` with Nested Filters

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:

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.

```json withRunButton="true"
POST /collections/dinosaurs/points/scroll
{
"filter": {
"must": [
{
"nested": {
"key": "diet",
"filter": {
"must": [
{
"key": "food",
"match": {
"value": "meat"
}
},
{
"key": "likes",
"match": {
"value": true
}
}
]
}
}
},
{
"has_id": [1]
}
]
}
}
```

165 changes: 165 additions & 0 deletions src/components/InteractiveTutorial/MdxPages/FilteringBeginner.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
export const title = "Basic Filtering"

# Basic Filtering - Clauses and Conditions

## Step 1: Create a Collection

First, create a collection called `terraforming`. Each point will have vectors of size 4, and the distance metric is set to `Dot`:

```json withRunButton="true"
PUT collections/terraforming
{
"vectors": {
"size": 4,
"distance": "Dot"
}
}
```

## Step 2: Add Points with Vectors and Payloads

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`:

```json withRunButton="true"
PUT collections/terraforming/points
{
"points": [
{
"id": 1,
"vector": [0.1, 0.2, 0.3, 0.4],
"payload": {"land": "forest", "color": "green", "life": true, "humidity": 40}
},
{
"id": 2,
"vector": [0.2, 0.3, 0.4, 0.5],
"payload": {"land": "lake", "color": "blue", "life": true, "humidity": 100}
},
{
"id": 3,
"vector": [0.3, 0.4, 0.5, 0.6],
"payload": {"land": "steppe", "color": "green", "life": false, "humidity": 25}
},
{
"id": 4,
"vector": [0.4, 0.5, 0.6, 0.7],
"payload": {"land": "desert", "color": "red", "life": false, "humidity": 5}
},
{
"id": 5,
"vector": [0.5, 0.6, 0.7, 0.8],
"payload": {"land": "marsh", "color": "black", "life": true, "humidity": 90}
},
{
"id": 6,
"vector": [0.6, 0.7, 0.8, 0.9],
"payload": {"land": "cavern", "color": "black", "life": false, "humidity": 15}
}
]
}
```

## Step 3: Filtering examples

### Filter by exact match

Finally, this query retrieves points where the `color` is `"black"`, using a straightforward `match` condition:

```json withRunButton="true"
POST collections/terraforming/points/scroll
{
"filter": {
"must": [
{
"key": "color",
"match": {
"value": "black"
}
}
]
},
"limit": 3,
"with_payload": true
}
```

### Combined filter by `must` clause

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.

```json withRunButton=true
POST collections/terraforming/points/scroll
{
"filter": {
"must": [
{ "key": "life", "match": { "value": true } },
{ "key": "color", "match": { "value": "green" } }
]
},
"limit": 3,
"with_payload": true
}
```

### Filter by `should` clause

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:

```json withRunButton=true
POST collections/terraforming/points/scroll
{
"filter": {
"should": [
{
"key": "life",
"match": { "value": false }
}, {
"key": "color",
"match": { "value": "black" }
}
]
}
}
```

### Filter by `must_not` clause

This query filters out any points where `life` is `false`. Points matching this condition are excluded from the results.

```json withRunButton=true
POST collections/terraforming/points/scroll
{
"filter": {
"must_not": [
{
"key": "life",
"match": { "value": false }
}
]
},
"limit": 3,
"with_payload": true
}
```

### Filter by `range` condition

This query filters points based on a range of `humidity`. Here, the `humidity` value must be exactly 40:

```json withRunButton="true"
POST collections/terraforming/points/scroll
{
"filter": {
"must": [
{
"key": "humidity",
"range": {
"gte": 40,
"lte": 40
}
}
]
},
"limit": 3,
"with_payload": true
}
```
Loading

0 comments on commit ccfbc4f

Please sign in to comment.