> For the complete documentation index, see [llms.txt](https://docs.snackprompt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snackprompt.com/bring-your-data-into-ai/tutorials/semantic-search.md).

# Semantic Search

In this tutorial, you'll learn how to perform semantic searches in the SnackPrompt AI Engine Knowledge Base.

### What is Semantic Search?

Unlike keyword search (which looks for exact matches), **semantic search** understands the **meaning** of your question.

**Example:**

* **Traditional search:** "price product" → only finds documents with those exact words
* **Semantic search:** "how much does it cost?" → finds documents about prices, values, costs, etc.

### Prerequisites

* A valid `tenant_id`  [(See how to find it)](https://docs.snackprompt.com/how-to/how-to-obtain-your-user-id-tenant-id) 
* Data already ingested in the Knowledge Base (see Ingesting Data)

### Step 1: Make a Basic Search

```bash
curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what are the return policies?",
    "filters": {
      "tenant_id": "YOUR_TENANT_ID"
    },
    "limit": 5
  }'
```

#### Parameters

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| `query`   | string | Yes      | Your search text                        |
| `filters` | object | Yes      | Filters (includes required tenant\_id)  |
| `limit`   | number | No       | Maximum number of results (default: 10) |

### Step 2: Understand the Similarity Score

Each result includes a `score` from 0 to 1:

```json
{
  "items": [
    {
      "id": "result-uuid-1",
      "score": 0.92,
      "payload": {
        "original_text": "Our return policy allows..."
      }
    },
    {
      "id": "result-uuid-2",
      "score": 0.78,
      "payload": {
        "original_text": "To exchange a product, you must..."
      }
    }
  ]
}
```

#### How to Interpret the Score

| Score       | Interpretation                     |
| ----------- | ---------------------------------- |
| 0.90 - 1.00 | Very relevant - almost exact match |
| 0.75 - 0.89 | Relevant - good semantic match     |
| 0.60 - 0.74 | Moderate - related to the topic    |
| < 0.60      | Low - possibly not relevant        |

> **Tip:** In production, consider filtering results with scores below 0.6 or 0.7.

### Step 3: Use Filters to Refine Results

#### Filter by Specific Elemental

Search only in a specific document/table:

```bash
curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "return policies",
    "filters": {
      "tenant_id": "YOUR_TENANT_ID",
      "elemental_id": "doc-policies-123"
    },
    "limit": 5
  }'
```

#### Filter by Tags

Search only in documents with certain tags:

```bash
curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "return policies",
    "filters": {
      "tenant_id": "YOUR_TENANT_ID",
      "tag_names": ["Legal", "Policies"]
    },
    "limit": 5
  }'
```

> **Note:** When multiple tags are provided, the logic is **OR** (any of them).

#### Filter by Source Type

```bash
curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "return policies",
    "filters": {
      "tenant_id": "YOUR_TENANT_ID",
      "source": "document"
    },
    "limit": 5
  }'
```

Possible values for `source`:

* `elemental` - SnackPrompt tables
* `document` - Documents
* `file` - Uploaded files

### Available Filters

| Filter          | Type      | Required | Description                      |
| --------------- | --------- | -------- | -------------------------------- |
| `tenant_id`     | string    | **YES**  | Tenant ID (isolation)            |
| `elemental_id`  | string    | No       | Filter by specific elemental     |
| `user_id`       | string    | No       | Filter by user                   |
| `tag_ids`       | string\[] | No       | Filter by tag IDs (OR)           |
| `tag_names`     | string\[] | No       | Filter by tag names (OR)         |
| `source`        | string    | No       | Source type                      |
| `type_name`     | string    | No       | Elemental type (Table, Document) |
| `category_name` | string    | No       | Elemental category               |

### Combining Filters

Multiple filters are combined with **AND** logic:

```bash
curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "prices",
    "filters": {
      "tenant_id": "YOUR_TENANT_ID",
      "source": "elemental",
      "tag_names": ["Products", "Sales"]
    },
    "limit": 10
  }'
```

This example searches for "prices" in:

* Elementals (not documents or files) **AND**
* With tag "Products" **OR** "Sales"

### Tips for Better Results

#### 1. Be Specific in Your Query

```diff
- "information"
+ "what are the store opening hours?"
```

#### 2. Use Natural Language

```diff
- "price product X"
+ "how much does product X cost?"
```

#### 3. Limit the Results

```diff
- "limit": 100
+ "limit": 5
```

Fewer results = more relevant results.

#### 4. Use Filters When Possible

If you know where the information is, use filters to improve precision:

```json
{
  "query": "delivery time",
  "filters": {
    "tenant_id": "...",
    "tag_names": ["Logistics", "Shipping"]
  }
}
```

### Next Steps

Now that you've mastered semantic search:

1. Chat with your Data - Get elaborate answers with AI
2. Filter by Tags - Advanced filtering techniques

***

**Estimated time:** 10 minutes ✅