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

# Migrate metadata filters to v5

> Convert legacy Query filters into strict, type-safe v5 filter expressions

## Migration details

v5 uses one optional singular `filter` field for search, profiles, and list operations.

### Shape

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
type Filter =
  | { field: string; operator: "eq" | "neq"; value: string; caseSensitive?: boolean }
  | { field: string; operator: "eq" | "neq"; value: number | boolean }
  | { field: string; operator: "gt" | "gte" | "lt" | "lte"; value: number }
  | { field: string; operator: "contains" | "notContains"; value: string; caseSensitive?: boolean }
  | { field: string; operator: "arrayContains" | "arrayNotContains"; value: string }
  | { operator: "and" | "or"; operands: Filter[] };
```

Fields may contain letters, numbers, `_`, `.`, and `-`. Expressions allow up to five nested levels and 200 operands per logical group.

### Operator mapping

| Legacy condition | v5 predicate |
| - | - |
| `{ key, value }` | `{ field: key, operator: "eq", value }` |
| `negate: true` equality | `operator: "neq"` |
| `filterType: "string_contains"` | `operator: "contains"` |
| contains + `negate: true` | `operator: "notContains"` |
| `filterType: "array_contains"` | `operator: "arrayContains"` |
| array contains + `negate: true` | `operator: "arrayNotContains"` |
| numeric `=` / numeric `=` + `negate: true` | `eq` / `neq` with a JSON number |
| numeric `>`, `>=`, `<`, `<=` | `gt`, `gte`, `lt`, `lte` |
| `AND` / `OR` arrays | lowercase `and` / `or` with `operands` |
| `ignoreCase: true` | `caseSensitive: false` |

### Before and after

<CodeGroup>
  ```json Legacy theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "AND": [
      { "key": "category", "value": "research" },
      { "key": "score", "value": 0.8, "filterType": "numeric", "numericOperator": ">=" }
    ]
  }
  ```

  ```json v5 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "operator": "and",
    "operands": [
      { "field": "category", "operator": "eq", "value": "research" },
      { "field": "score", "operator": "gte", "value": 0.8 }
    ]
  }
  ```
</CodeGroup>

### With the SDK

<CodeGroup>
  ```ts Legacy theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  await client.search.execute({
    q: "research notes",
    containerTags: ["user_1"],
    filters: JSON.stringify({
      AND: [
        { key: "category", value: "research" },
        { key: "score", value: 0.8, filterType: "numeric", numericOperator: ">=" },
      ],
    }),
  })
  ```

  ```ts v5 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  await supermemory.search("user_1", {
    query: "research notes",
    filter: {
      operator: "and",
      operands: [
        { field: "category", operator: "eq", value: "research" },
        { field: "score", operator: "gte", value: 0.8 },
      ],
    },
    searchMode: "chunks",
  })
  ```
</CodeGroup>

`filter` is a typed object under `body`, not a JSON string. The same shape works in `supermemory.list` and `supermemory.profile`. Keys are literal: `customer.plan` is one field name, not a nested path.

### Deterministic conversion

1. Rename outer `filters` to `filter`.
2. Recursively replace `AND`/`OR` objects with `{ operator, operands }`.
3. Rename `key` to `field`.
4. Convert legacy flags into one explicit operator.
5. Keep numeric values as JSON numbers rather than numeric strings.
6. Remove legacy `filterType`, `negate`, `numericOperator`, and `ignoreCase` keys.

### Verification

* Compare result IDs for equality, inequality, contains, numeric, array, nested AND, and nested OR fixtures.
* Add negative tests: legacy shapes, empty operands, incompatible value types, and unknown keys must return `400`.
* Confirm omitted `filter` preserves unfiltered behavior.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.