Filters

Compose filter conditions with logical operators

Filters narrow results using logical operators to combine conditions. They operate on document payloads (metadata, enrichments, passthrough fields) and can be applied in retriever execution or as dedicated filter@v1 stages.

Logical Operators

Mixpeek filters support three logical operators for composing conditions:

Operator	Description	Usage
AND	All conditions must be true	Combine multiple required constraints
OR	At least one condition must be true	Match any of several alternatives
NOT	Inverts the condition	Exclude matching documents

AND Operator

Requires all nested conditions to match:

{
  "AND": [
    { "field": "metadata.status", "operator": "eq", "value": "published" },
    { "field": "metadata.price", "operator": "lte", "value": 100 }
  ]
}

OR Operator

Matches if any nested condition is true:

{
  "OR": [
    { "field": "metadata.category", "operator": "eq", "value": "video" },
    { "field": "metadata.category", "operator": "eq", "value": "audio" }
  ]
}

NOT Operator

Excludes documents matching the condition:

{
  "NOT": {
    "field": "metadata.status", "operator": "eq", "value": "draft"
  }
}

Nesting Operators

Logical operators can be nested to create complex filter logic:

{
  "AND": [
    { "field": "metadata.status", "operator": "eq", "value": "published" },
    {
      "OR": [
        { "field": "metadata.category", "operator": "eq", "value": "video" },
        { "field": "metadata.category", "operator": "eq", "value": "audio" }
      ]
    },
    {
      "NOT": {
        "field": "metadata.restricted", "operator": "eq", "value": true
      }
    }
  ]
}

This filter matches documents that are:

• Published AND
• Either video or audio AND
• Not restricted

Comparison Operators

Use these operators within conditions:

Operator	Description
eq	Equals
ne	Not equals
gt	Greater than
gte	Greater than or equal
lt	Less than
lte	Less than or equal
in	Value in list
nin	Value not in list
exists	Field exists
is_null	Field is null
contains	String contains substring
starts_with	String starts with prefix
ends_with	String ends with suffix
regex	Matches regular expression

Lineage Shortcuts

Every Mixpeek document carries a _internal.lineage block recording where it came from. To filter by lineage you don’t have to use the underscore-prefixed paths — use the friendly aliases below in any field position.

Alias	Resolves to	Use for
from_object	_internal.lineage.root_object_id	”Everything derived from this bucket object”
from_bucket	_internal.lineage.root_bucket_id	”Everything derived from this bucket”
from_document	_internal.lineage.source_document_id	Direct children of one upstream document
from_collection	_internal.lineage.source_collection_id	Documents whose immediate parent was in this collection

{
  "AND": [
    { "field": "from_object", "operator": "eq", "value": "obj_video_123" }
  ]
}

You can mix lineage aliases with regular fields and templates:

{
  "AND": [
    { "field": "from_object", "operator": "eq", "value": "{{INPUT.object_id}}" },
    { "field": "metadata.scene_score", "operator": "gte", "value": 0.8 }
  ]
}

The aliases are also accepted by document list endpoints and retriever filter stages — the same vocabulary works everywhere field is used.

Using Templates

Reference request inputs or stage outputs in filter values:

{
  "AND": [
    { "field": "metadata.category", "operator": "eq", "value": "{{INPUT.category}}" },
    { "field": "metadata.price", "operator": "lte", "value": "{{INPUT.max_price}}" }
  ]
}

Filter Stage Example

{
  "stage_name": "filter",
  "version": "v1",
  "parameters": {
    "strategy": "structured",
    "structured_filter": {
      "AND": [
        { "field": "metadata.category", "operator": "eq", "value": "audio" },
        { "field": "metadata.price", "operator": "lte", "value": "{{INPUT.max_price}}" }
      ]
    }
  }
}

Options

Option	Default	Description
case_sensitive	false	Enable case-sensitive string comparisons

{
  "field": "metadata.title",
  "operator": "contains",
  "value": "AI",
  "case_sensitive": true
}