# 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 ✅


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.snackprompt.com/bring-your-data-into-ai/tutorials/semantic-search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.