Filters

Embedd uses a unified filter language across all storage providers. Write your filters once — Embedd translates them to the correct query syntax for Qdrant, PostgreSQL, or Snowflake behind the scenes. Filters are passed in the filters field of a query request.

curl -X POST https://api.embedd.to/v1/vector-tables/{id}/query \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "machine learning frameworks",
    "limit": 10,
    "filters": {
      "category": {"eq": "education"},
      "price": {"lte": 50}
    }
  }'

Operators

Operator	Description	Example
eq	Equals	{"status": {"eq": "active"}}
neq	Not equals	{"status": {"neq": "archived"}}
gt	Greater than	{"price": {"gt": 10}}
gte	Greater than or equal	{"price": {"gte": 10}}
lt	Less than	{"price": {"lt": 100}}
lte	Less than or equal	{"price": {"lte": 100}}
in	In array	{"category": {"in": ["tools", "gadgets"]}}
nin	Not in array	{"category": {"nin": ["archived", "deleted"]}}
exists	Field exists or doesn't	{"notes": {"exists": true}}

Shorthand Equality

A direct value without an operator is treated as eq:

{"category": "tools"}

is equivalent to:

{"category": {"eq": "tools"}}

Value Types

Filter values are auto-detected based on the JSON type you provide:

Type	Example Value	Notes
String	"active"	Exact match, case-sensitive
Integer	42	Whole numbers
Float	9.99	Decimal numbers
Boolean	true / false	Used with eq or as shorthand

Combining Filters

AND (implicit)

Multiple conditions at the same level are combined with AND. All conditions must be true for a row to match.

{
  "category": {"eq": "footwear"},
  "price": {"gte": 50, "lte": 200},
  "in_stock": {"eq": true}
}

This returns rows where the category is "footwear" and the price is between 50 and 200 and the item is in stock.

OR (explicit)

Use $or with an array of filter objects. A row matches if any of the filter objects in the array match.

Simple example — items that are either footwear or gear:

{
  "$or": [
    {"category": {"eq": "footwear"}},
    {"category": {"eq": "gear"}}
  ]
}

Complex example — each OR branch can contain multiple conditions:

{
  "$or": [
    {
      "category": {"eq": "footwear"},
      "price": {"lte": 150},
      "in_stock": {"eq": true}
    },
    {
      "category": {"eq": "gear"}
    }
  ]
}

This returns rows that are either (in-stock footwear under $150) or (any gear).

Range Filters

Apply multiple range operators to the same field to define a range:

{
  "price": {"gte": 10, "lte": 100}
}

This matches rows where price is between 10 and 100, inclusive.

Field Existence

Check whether a metadata field is present or absent on a row:

{"notes": {"exists": true}}

Returns rows where the notes field is present.

{"notes": {"exists": false}}

Returns rows where the notes field is missing or null.

Filtering a Search Table

Filters operate on the metadata columns of your vector table. To see how this works end to end, consider a products source table:

id	name	description	category	brand	price	in_stock
1	Trail Runner Pro	Lightweight trail running shoe with grip sole	footwear	TrailMax	129.99	true
2	Summit Hiking Boot	Waterproof leather hiking boot for rough terrain	footwear	PeakGear	189.99	true
3	Ultralight Rain Jacket	Packable rain jacket with sealed seams	clothing	StormLite	79.99	false
4	Trekking Pole Set	Adjustable carbon fiber trekking poles	gear	TrailMax	64.99	true
5	GPS Sport Watch	Multi-sport GPS watch with heart rate monitor	gear	PeakGear	249.99	true

When creating the vector table, you configure columns like this:

• Embedding columns: name, description — concatenated and embedded for semantic search
• Metadata columns: category, brand, price, in_stock — stored as filterable metadata

Find trail running gear in stock under $200

{
  "query": "trail running gear",
  "limit": 10,
  "filters": {
    "in_stock": {"eq": true},
    "price": {"lt": 200}
  }
}

Matches rows 1, 4 — in stock and under $200. The semantic ranking then orders them by relevance to "trail running gear".

Find gear or footwear (not clothing)

{
  "query": "outdoor equipment",
  "limit": 10,
  "filters": {
    "category": {"in": ["gear", "footwear"]}
  }
}

Matches rows 1, 2, 4, 5 — everything except clothing.

In-stock footwear under $150 OR any gear regardless

{
  "query": "outdoor products",
  "limit": 10,
  "filters": {
    "$or": [
      {
        "category": {"eq": "footwear"},
        "price": {"lt": 150},
        "in_stock": {"eq": true}
      },
      {
        "category": {"eq": "gear"}
      }
    ]
  }
}

Matches row 1 (in-stock footwear under $150) and rows 4, 5 (gear regardless of price or stock).

Provider Notes

Embedd translates your filters to the native query syntax of each storage provider. Nearly everything works identically, with one exception:

Feature	Qdrant (Managed)	PostgreSQL (Platform)	Snowflake (Platform)
All comparison operators	Supported	Supported	Supported
in / nin	Supported	Supported	Supported
$or	Supported	Supported	Supported
exists: true	Supported	Supported	Supported
exists: false	Not supported	Supported	Supported

For full endpoint details including response format and pagination, see the Query API Reference.