# Filters

Complete reference for filters available in the SnackPrompt AI Engine API.

### Overview

Filters are used to restrict the scope of searches, chats, and deletions. They are passed in the `filters` object of the request body.

```json
{
  "query": "your search",
  "filters": {
    "tenant_id": "required",
    "elemental_id": "optional",
    ...
  }
}
```

### Filter List

| Filter          | Type      | Required | Description            |
| --------------- | --------- | -------- | ---------------------- |
| `tenant_id`     | string    | **YES**  | Multi-tenant isolation |
| `elemental_id`  | string    | No       | Elemental ID           |
| `user_id`       | string    | No       | User ID                |
| `tag_ids`       | string\[] | No       | Tag IDs                |
| `tag_names`     | string\[] | No       | Tag names              |
| `source`        | string    | No       | Source type            |
| `type_name`     | string    | No       | Elemental type         |
| `category_name` | string    | No       | Category               |

***

### Details

#### tenant\_id

Tenant identifier for data isolation. **Required in all operations.**

| Property | Value             |
| -------- | ----------------- |
| Type     | `string`          |
| Required | **Yes**           |
| Example  | `"tenant-abc123"` |

**Behavior:**

* Ensures complete isolation between tenants
* A tenant cannot access another tenant's data
* Optimized in Qdrant with `is_tenant=True`

**Example:**

```json
{
  "filters": {
    "tenant_id": "tenant-abc123"
  }
}
```

**Error if missing:**

```json
{
  "detail": "tenant_id is required in filters"
}
```

***

#### elemental\_id

Filters by a specific elemental (table/document).

| Property | Value           |
| -------- | --------------- |
| Type     | `string`        |
| Required | No              |
| Example  | `"elem-xyz789"` |

**Example:**

```json
{
  "filters": {
    "tenant_id": "tenant-abc123",
    "elemental_id": "elem-xyz789"
  }
}
```

***

#### user\_id

Filters by data from a specific user (within the tenant).

| Property | Value        |
| -------- | ------------ |
| Type     | `string`     |
| Required | No           |
| Example  | `"user-123"` |

**Example:**

```json
{
  "filters": {
    "tenant_id": "tenant-abc123",
    "user_id": "user-123"
  }
}
```

***

#### tag\_ids

Filters by tag IDs. **OR** logic (any of the tags).

| Property | Value                |
| -------- | -------------------- |
| Type     | `string[]`           |
| Required | No                   |
| Logic    | OR                   |
| Example  | `["tag-1", "tag-2"]` |

**Example:**

```json
{
  "filters": {
    "tenant_id": "tenant-abc123",
    "tag_ids": ["tag-marketing", "tag-sales"]
  }
}
```

Returns documents that have the tag "tag-marketing" **OR** "tag-sales".

***

#### tag\_names

Filters by tag names. **OR** logic (any of the tags).

| Property | Value                    |
| -------- | ------------------------ |
| Type     | `string[]`               |
| Required | No                       |
| Logic    | OR                       |
| Example  | `["Marketing", "Sales"]` |

**Example:**

```json
{
  "filters": {
    "tenant_id": "tenant-abc123",
    "tag_names": ["Marketing", "Sales"]
  }
}
```

Returns documents that have the tag "Marketing" **OR** "Sales".

***

#### source

Filters by data source type.

| Property | Value                           |
| -------- | ------------------------------- |
| Type     | `string`                        |
| Required | No                              |
| Values   | `elemental`, `document`, `file` |

**Possible values:**

| Value       | Description        |
| ----------- | ------------------ |
| `elemental` | SnackPrompt tables |
| `document`  | Documents          |
| `file`      | Uploaded files     |

**Example:**

```json
{
  "filters": {
    "tenant_id": "tenant-abc123",
    "source": "document"
  }
}
```

***

#### type\_name

Filters by elemental type.

| Property | Value                     |
| -------- | ------------------------- |
| Type     | `string`                  |
| Required | No                        |
| Values   | `Table`, `Document`, etc. |

**Example:**

```json
{
  "filters": {
    "tenant_id": "tenant-abc123",
    "type_name": "Table"
  }
}
```

***

#### category\_name

Filters by elemental category.

| Property | Value       |
| -------- | ----------- |
| Type     | `string`    |
| Required | No          |
| Example  | `"Finance"` |

**Example:**

```json
{
  "filters": {
    "tenant_id": "tenant-abc123",
    "category_name": "Finance"
  }
}
```

***

### Combining Filters

#### Combination Logic

* **Between different filters:** AND
* **Within arrays (tags):** OR

**Example:**

```json
{
  "filters": {
    "tenant_id": "tenant-abc123",
    "source": "elemental",
    "tag_names": ["Marketing", "Sales"]
  }
}
```

This means:

* `tenant_id` = "tenant-abc123" **AND**
* `source` = "elemental" **AND**
* (`tag_names` contains "Marketing" **OR** "Sales")

***

### Usage by Endpoint

| Endpoint             | Supported Filters                                                        |
| -------------------- | ------------------------------------------------------------------------ |
| `/v1/kb/search`      | All                                                                      |
| `/v1/kb/chat`        | All                                                                      |
| `/v1/kb/chat/stream` | All                                                                      |
| `/v1/kb/delete`      | `tenant_id`, `elemental_id`, `user_id`, `tag_ids`, `tag_names`, `source` |

***

### Practical Examples

#### Search in a Specific Document

```json
{
  "query": "delivery time",
  "filters": {
    "tenant_id": "tenant-123",
    "elemental_id": "doc-logistics-001"
  }
}
```

#### Search by Multiple Tags

```json
{
  "query": "benefits",
  "filters": {
    "tenant_id": "tenant-123",
    "tag_names": ["HR", "Benefits", "Policies"]
  }
}
```

#### Search Only in Tables

```json
{
  "query": "products",
  "filters": {
    "tenant_id": "tenant-123",
    "source": "elemental",
    "type_name": "Table"
  }
}
```

#### Delete User Data

```json
{
  "filters": {
    "tenant_id": "tenant-123",
    "user_id": "user-456"
  }
}
```


---

# 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/reference/filters.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.