Filter examples

Filters narrow the results of search, scroll, count, and other point operations by applying conditions to payload fields. You pass a filter object in the filter parameter of these operations.

A filter object contains one or more boolean clauses that combine field conditions.

Boolean clauses

• must — all conditions must match (AND logic). Points are included only when every condition in the array evaluates to true.
• should — at least one condition must match (OR logic). Points are included when any condition in the array evaluates to true.
• must_not — no condition may match (exclusion logic). Points are excluded when any condition in the array evaluates to true.

You can combine all three clauses in a single filter. For example, require a category (must), accept multiple price ranges (should), and exclude a specific brand (must_not).

Field conditions

Each condition targets a payload field by key and applies an operator.

• match — exact value match. Supports strings, numbers, and booleans.
• range — numeric range with gt, gte, lt, lte operators. Combine multiple range operators for between queries.
• has_id — matches points by their ID. Pass an array of point IDs.

Equality filter

Match points where a field has an exact value.

curl -X POST "http://localhost:6575/collections/my_collection/points/search" \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer <admin-jwt-or-access-token>' \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "limit": 5,
    "filter": {
      "must": [
        {
          "key": "category",
          "match": { "value": "A" }
        }
      ]
    }
  }'

{
  "usage": { "hardware": null },
  "time": 0.001326298,
  "status": "ok",
  "result": [
    { "id": 1, "version": 0, "score": 1, "payload": null, "vector": null }
  ]
}

Range filter

Match points where a numeric field falls within a range.

curl -X POST "http://localhost:6575/collections/my_collection/points/search" \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer <admin-jwt-or-access-token>' \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "limit": 5,
    "filter": {
      "must": [
        {
          "key": "value",
          "range": { "gte": 5, "lte": 50 }
        }
      ]
    }
  }'

{
  "usage": { "hardware": null },
  "time": 0.001511138,
  "status": "ok",
  "result": [
    { "id": 1, "version": 0, "score": 1, "payload": null, "vector": null },
    { "id": 3, "version": 0, "score": 0.9843740463256836, "payload": null, "vector": null },
    { "id": 2, "version": 0, "score": 0.9688639640808105, "payload": null, "vector": null }
  ]
}

Combined AND filter

Require multiple conditions to all be true.

curl -X POST "http://localhost:6575/collections/my_collection/points/search" \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer <admin-jwt-or-access-token>' \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "limit": 5,
    "filter": {
      "must": [
        {"key": "category", "match": {"value": "A"}},
        {"key": "value", "range": {"gte": 5}}
      ]
    }
  }'

{
  "usage": { "hardware": null },
  "time": 0.001966431,
  "status": "ok",
  "result": [
    { "id": 1, "version": 0, "score": 1, "payload": null, "vector": null }
  ]
}

Exclusion filter

Include points matching one condition while excluding those matching another.

curl -X POST "http://localhost:6575/collections/my_collection/points/search" \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer <admin-jwt-or-access-token>' \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "limit": 5,
    "filter": {
      "must": [
        {"key": "category", "match": {"value": "A"}}
      ],
      "must_not": [
        {"key": "value", "range": {"gt": 50}}
      ]
    }
  }'

{
  "usage": { "hardware": null },
  "time": 0.001301257,
  "status": "ok",
  "result": [
    { "id": 1, "version": 0, "score": 1, "payload": null, "vector": null }
  ]
}

OR filter

Match points where at least one condition is true.

curl -X POST "http://localhost:6575/collections/my_collection/points/search" \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer <admin-jwt-or-access-token>' \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "limit": 5,
    "filter": {
      "should": [
        {"key": "category", "match": {"value": "A"}},
        {"key": "category", "match": {"value": "B"}}
      ]
    }
  }'

{
  "usage": { "hardware": null },
  "time": 0.001109878,
  "status": "ok",
  "result": [
    { "id": 1, "version": 0, "score": 1, "payload": null, "vector": null },
    { "id": 2, "version": 0, "score": 0.9688639640808105, "payload": null, "vector": null }
  ]
}

ID filter

Restrict results to specific point IDs using has_id.

curl -X POST "http://localhost:6575/collections/my_collection/points/search" \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer <admin-jwt-or-access-token>' \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "limit": 5,
    "filter": {
      "must": [
        { "has_id": [1, 2] }
      ]
    }
  }'

{
  "usage": { "hardware": null },
  "time": 0.001272852,
  "status": "ok",
  "result": [
    { "id": 1, "version": 0, "score": 1, "payload": null, "vector": null },
    { "id": 2, "version": 0, "score": 0.9688639640808105, "payload": null, "vector": null }
  ]
}

Combined boolean filter

Combine should, must, and must_not clauses in a single filter.

curl -X POST "http://localhost:6575/collections/my_collection/points/search" \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer <admin-jwt-or-access-token>' \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "limit": 5,
    "filter": {
      "should": [
        {"key": "category", "match": {"value": "A"}},
        {"key": "category", "match": {"value": "B"}}
      ],
      "must": [
        {"key": "value", "range": {"lt": 100}}
      ],
      "must_not": [
        {"key": "value", "range": {"lt": 5}}
      ]
    }
  }'

{
  "usage": { "hardware": null },
  "time": 0.004577864,
  "status": "ok",
  "result": [
    { "id": 1, "version": 0, "score": 1, "payload": null, "vector": null },
    { "id": 2, "version": 0, "score": 0.9688639640808105, "payload": null, "vector": null }
  ]
}