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

# 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"
  }
}
```