Filter by metadata

Beta

This feature is in beta. The API may change.

Search with structured filters on any metadata field. Filters are applied before results are returned — only documents that match every condition are returned.

1. Index with metadata

Filters operate on the metadata you attach at index time. Include every field you want to filter on.

import { Etoile } from "@etoile-dev/client";

const etoile = new Etoile({
apiKey: process.env.ETOILE_API_KEY,
});

await etoile.index({
id: "product-1",
collection: "products",
title: "Ultraboost 22",
content: "Lightweight running shoe with responsive cushioning...",
metadata: {
  category: "running",
  brand: "Adidas",
  price: 130,
  rating: 4.6,
  inStock: true,
},
});

const response = await fetch("https://etoile.dev/api/v1/index", {
method: "POST",
headers: {
  Authorization: `Bearer ${process.env.ETOILE_SECRET_KEY}`,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  id: "product-1",
  collection: "products",
  title: "Ultraboost 22",
  content: "Lightweight running shoe with responsive cushioning...",
  metadata: {
    category: "running",
    brand: "Adidas",
    price: 130,
    rating: 4.6,
    inStock: true,
  },
}),
});

curl -X POST "https://etoile.dev/api/v1/index" \
-H "Authorization: Bearer $ETOILE_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
  "id": "product-1",
  "collection": "products",
  "title": "Ultraboost 22",
  "content": "Lightweight running shoe with responsive cushioning...",
  "metadata": {
    "category": "running",
    "brand": "Adidas",
    "price": 130,
    "rating": 4.6,
    "inStock": true
  }
}'

2. Search with filters

Pass a filters array to narrow results by metadata. All filters are combined with AND logic.

const { results } = await etoile.search({
query: "comfortable everyday shoe",
collections: ["products"],
filters: [
  { key: "category", operator: "in", value: ["running", "training"] },
  { key: "price",    operator: "lte", value: 150 },
  { key: "rating",   operator: "gte", value: 4.0 },
],
});

const response = await fetch("https://etoile.dev/api/v1/search", {
method: "POST",
headers: {
  Authorization: `Bearer ${process.env.ETOILE_PUBLIC_KEY}`,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  query: "comfortable everyday shoe",
  collections: ["products"],
  filters: [
    { key: "category", operator: "in", value: ["running", "training"] },
    { key: "price",    operator: "lte", value: 150 },
    { key: "rating",   operator: "gte", value: 4.0 },
  ],
}),
});

const { results, appliedFilters } = await response.json();

curl -X POST "https://etoile.dev/api/v1/search" \
-H "Authorization: Bearer $ETOILE_PUBLIC_KEY" \
-H "Content-Type: application/json" \
-d '{
  "query": "comfortable everyday shoe",
  "collections": ["products"],
  "filters": [
    { "key": "category", "operator": "in",  "value": ["running", "training"] },
    { "key": "price",    "operator": "lte", "value": 150 },
    { "key": "rating",   "operator": "gte", "value": 4.0 }
  ]
}'

Supported operators

Parameter	Type	Description
`eq`	`string \| number \| boolean`	Equal to the given value.
`neq`	`string \| number \| boolean`	Not equal to the given value.
`gt`	`number`	Greater than.
`gte`	`number`	Greater than or equal.
`lt`	`number`	Less than.
`lte`	`number`	Less than or equal.
`in`	`string[]`	Matches any value in the list.
`not_in`	`string[]`	Matches none of the values in the list.
`contains_all`	`string[]`	Metadata array contains all of the given values.
`contains_any`	`string[]`	Metadata array contains at least one of the given values.
`contains_none`	`string[]`	Metadata array contains none of the given values.

Use metadata — attach fields at index time
Smart filters — let AI extract filters from the query
Search (POST) — API reference

Filter by metadata

1. Index with metadata

2. Search with filters

Supported operators

Related