> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata Filtering

> Filter reference for search and retrieval

Filter search results by metadata attributes using comparison and logical operators.

## Operators Reference

| Operator         | Description                      | Example                                             |
| ---------------- | -------------------------------- | --------------------------------------------------- |
| `$eq`            | Equals (default)                 | `{"status": "active"}`                              |
| `$ne`            | Not equals                       | `{"status": {"$ne": "archived"}}`                   |
| `$gt`            | Greater than                     | `{"score": {"$gt": 80}}`                            |
| `$gte`           | Greater than or equal            | `{"priority": {"$gte": 7}}`                         |
| `$lt`            | Less than                        | `{"age": {"$lt": 30}}`                              |
| `$lte`           | Less than or equal               | `{"count": {"$lte": 100}}`                          |
| `$in`            | Value in list                    | `{"status": {"$in": ["a", "b"]}}`                   |
| `$nin`           | Not in list                      | `{"status": {"$nin": ["x", "y"]}}`                  |
| `$like`          | Pattern match (case-sensitive)   | `{"title": {"$like": "Important%"}}`                |
| `$ilike`         | Pattern match (case-insensitive) | `{"email": {"$ilike": "%@company.com"}}`            |
| `$overlap`       | Array has any                    | `{"tags": {"$overlap": ["urgent", "important"]}}`   |
| `$contains`      | Array has all                    | `{"skills": {"$contains": ["python", "ml"]}}`       |
| `$json_contains` | JSONB structural match           | `{"config": {"$json_contains": {"enabled": true}}}` |
| `$and`           | All conditions match             | `{"$and": [{...}, {...}]}`                          |
| `$or`            | Any condition matches            | `{"$or": [{...}, {...}]}`                           |

<Tip>Use `%` as wildcard in `$like` and `$ilike` patterns.</Tip>
<Tip>Target metadata fields with the `metadata.` prefix (e.g., `metadata.status`). Nested fields are supported.</Tip>

<Info>Set `verbose: true` in `search_settings` to include full metadata and internal IDs in search results.</Info>

## Examples

<CodeGroup>
  ```python Python theme={null}
  from nebula import Nebula
  nebula = Nebula()

  # Simple equality
  results = nebula.memories.search(
      query="machine learning",
      collection_ids=["docs"],
      filters={"metadata.category": "research"},
  ).results

  # Multiple conditions with $and
  results = nebula.memories.search(
      query="reports",
      collection_ids=["tasks"],
      filters={
          "$and": [
              {"metadata.priority": {"$gte": 7}},
              {"metadata.status": {"$in": ["pending", "active"]}},
              {"created_at": {"$gte": "2024-01-01"}},
          ]
      },
  ).results

  # Array operations
  results = nebula.memories.search(
      query="candidates",
      collection_ids=["hr"],
      filters={"metadata.skills": {"$contains": ["python", "ml"]}},
  ).results
  ```

  ```javascript JavaScript theme={null}
  import Nebula from '@nebula-ai/sdk';
  const client = new Nebula({ apiKey: process.env.NEBULA_API_KEY });

  // Simple equality
  const { results } = await client.memories.search({
    query: 'machine learning',
    collection_ids: ['docs'],
    filters: { 'metadata.category': 'research' },
  });

  // Multiple conditions with $and
  const { results: results2 } = await client.memories.search({
    query: 'reports',
    collection_ids: ['tasks'],
    filters: {
      $and: [
        { 'metadata.priority': { $gte: 7 } },
        { 'metadata.status': { $in: ['pending', 'active'] } },
        { created_at: { $gte: '2024-01-01' } },
      ],
    },
  });

  // Array operations
  const { results: results3 } = await client.memories.search({
    query: 'candidates',
    collection_ids: ['hr'],
    filters: { 'metadata.skills': { $contains: ['python', 'ml'] } },
  });
  ```

  ```bash cURL theme={null}
  # Simple equality
  curl -X POST "https://api.zeroset.com/v1/memories/search" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "query": "machine learning",
      "collection_ids": ["docs"],
      "filters": {"metadata.category": "research"}
    }'

  # Multiple conditions with $and
  curl -X POST "https://api.zeroset.com/v1/memories/search" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "query": "reports",
      "collection_ids": ["tasks"],
      "filters": {
        "$and": [
          {"metadata.priority": {"$gte": 7}},
          {"metadata.status": {"$in": ["pending", "active"]}},
          {"created_at": {"$gte": "2024-01-01"}}
        ]
      }
    }'
  ```
</CodeGroup>

## Common Patterns

### Date Ranges

```python theme={null}
from datetime import datetime, timedelta

# Last 30 days (filters on the row's created_at column)
start = (datetime.now() - timedelta(days=30)).isoformat()
filters = {"created_at": {"$gte": start}}

# Date range
filters = {
    "$and": [
        {"created_at": {"$gte": "2024-01-01"}},
        {"created_at": {"$lte": "2024-12-31"}}
    ]
}
```

### Multi-Status

```python theme={null}
# Include specific statuses
filters = {"metadata.status": {"$in": ["pending", "in_progress", "review"]}}

# Exclude specific statuses
filters = {"metadata.status": {"$nin": ["archived", "deleted"]}}
```

### Nested Properties

```python theme={null}
# Filter nested object properties
filters = {
    "metadata.user.profile.age": {"$gte": 25},
    "metadata.user.location.city": "San Francisco"
}
```

## Next Steps

* [Search Guide](/guides/search) - Semantic search strategies
* [Memory Operations](/guides/memory-operations) - Core CRUD operations