> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.eyelevel.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.eyelevel.ai/_mcp/server.

Add [filter](/reference/api-reference/documents/ingest-documents) metadata to each document during ingest. GroundX copies it to every chunk so you can restrict which documents a search returns.

Include a filter expression when searching a bucket to return only matching documents. Without a filter expression, search includes the entire bucket.

## Supported metadata types

Filter metadata must be a JSON object with string keys. Values can be:

* String
* Number (integers and decimals are stored as 64-bit floating-point values)
* Boolean (`true` or `false`)
* List of strings or numbers
* Nested objects following the same rules

These metadata objects are valid:

**`JSON`**

```JSON JSON
{
    "security_level": 1,
    "organization": "corporate",
    "roles": ["director","executive"]
}
```

**`JSON`**

```JSON JSON
{
    "permissions": {
      "security_level": 1,
      "organization": "corporate",
      "roles": ["director","executive"]
    },
    "graph": {
      "nodes": ["corporate policy","version 1.0.112"]
    }
}
```

## Filter Metadata Size

Filter metadata is limited to 40 KB per document.

## Filter Query Syntax

Filter queries are based on [MongoDB's query and projection operators](https://docs.mongodb.com/manual/reference/operator/query/). GroundX supports a subset of these selectors:

| Filter    | Description                                                                                                                         | Supported types         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `$eq`     | Matches documents with filter values that are equal to a specified value. Example: `{"roles": {"$eq": "director"}}`                 | Number, string, boolean |
| `$ne`     | Matches documents with filter values that are not equal to a specified value. Example: `{"roles": {"$ne": "executive"}}`            | Number, string, boolean |
| `$gt`     | Matches documents with filter values that are greater than a specified value. Example: `{"security_level": {"$gt": 1}}`             | Number                  |
| `$gte`    | Matches documents with filter values that are greater than or equal to a specified value. Example:`{"security_level": {"$gte": 1}}` | Number                  |
| `$lt`     | Matches documents with filter values that are less than a specified value. Example: `{"security_level": {"$lt": 1}}`                | Number                  |
| `$lte`    | Matches documents with filter values that are less than or equal to a specified value. Example: `{"security_level": {"$lte": 1}}`   | Number                  |
| `$in`     | Matches documents with filter values that are in a specified array. Example: `{"roles": {"$in": ["director", "executive"]}}`        | String, number          |
| `$nin`    | Matches documents with filter values that are not in a specified array. Example: `{"roles": {"$nin": ["director", "executive"]}}`   | String, number          |
| `$exists` | Matches documents with the specified filter field. Example: `{"roles": {"$exists": true}}`                                          | Number, string, boolean |
| `$and`    | Joins query clauses with a logical `AND`. Example: `{"$and": [{"roles": {"$eq": "executive"}}, {"security_level": {"$gte": 1}}]}`   | -                       |
| `$or`     | Joins query clauses with a logical `OR`. Example: `{"$or": [{"roles": {"$eq": "executive"}}, {"security_level": {"$gte": 1}}]}`     | -                       |

This document's filter metadata includes a `"roles"` list:

**`JSON`**

```JSON JSON
{ "roles": ["director", "executive"] }
```

The document has both `"director"` and `"executive"` roles. All these queries match it:

**`JSON`**

```JSON JSON
{"roles":"director"}
```

**`JSON`**

```JSON JSON
{"roles": {"$in":["director","executive","employee"]}}
```

**`JSON`**

```JSON JSON
{"$and": [{"roles": "director"}, {"roles":"executive"}]}
```

This query does **not** match:

**`JSON`**

```JSON JSON
{ "$and": [{ "roles": "director" }, { "roles": "employee" }] }
```

These invalid queries return an error:

**`JSON`**

```JSON JSON
# INVALID QUERY:
{"roles": [true, false]}
```

**`JSON`**

```JSON JSON
# INVALID QUERY:
{"roles": {"$eq": ["director", "employee"]}}
```