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

• Your API Key for authentication (see Authentication)

• Data already ingested in the Knowledge Base (see Ingesting Data)

Step 1: Make a Basic Search

curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -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:

{
  "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:

curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -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:

curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -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

curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -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:

curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -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

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

2. Use Natural Language

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

3. Limit the Results

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

{
  "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 ✅