Metadata filtering¶

You can filter search results by metadata. Filters are applied after retrieving the top‑k candidates, then results are re-sorted by score.

Simple equality¶

Match metadata keys to exact values:

const results = await db.searchText('query', {
  k: 10,
  filter: { category: 'docs', lang: 'en' },
});

Only documents with metadata.category === 'docs' and metadata.lang === 'en' are returned.

Advanced operators¶

Use operators for comparisons and membership.

Operator	Meaning	Example
`$eq`	Equal	`{ x: { $eq: 5 } }`
`$ne`	Not equal	`{ deleted: { $ne: true } }`
`$gt`	Greater than	`{ views: { $gt: 100 } }`
`$gte`	Greater than or equal	`{ score: { $gte: 0.8 } }`
`$lt`	Less than	`{ views: { $lt: 1000 } }`
`$lte`	Less than or equal	`{ rank: { $lte: 10 } }`
`$in`	In array	`{ status: { $in: ['active', 'pending'] } }`
`$nin`	Not in array	`{ tag: { $nin: ['archived'] } }`

Examples¶

Numeric range¶

const results = await db.searchText('machine learning', {
  k: 20,
  filter: {
    year: { $gte: 2020, $lte: 2024 },
    views: { $gt: 100 },
  },
});

Exclude deleted¶

const results = await db.searchText('query', {
  k: 10,
  filter: { deleted: { $ne: true } },
});

Status in list¶

const results = await db.searchText('query', {
  k: 10,
  filter: { status: { $in: ['published', 'draft'] } },
});

Combined¶

const results = await db.searchText('query', {
  k: 10,
  filter: {
    category: 'articles',
    lang: 'en',
    score: { $gte: 0.7 },
    status: { $nin: ['archived'] },
  },
});

With React hooks¶

Pass filter in the options:

const { results } = useSearchText(db, query, {
  k: 5,
  filter: { category: 'docs', status: 'published' },
});

Notes¶

Filtering happens after top‑k retrieval. For strict guarantees (e.g. “only published”), use a higher k or ensure enough candidates pass the filter.
Nested object paths (e.g. user.name) are not supported; use flat keys.
Missing keys are treated as “no match” for equality. For $ne, a missing key does not match.

For full search options, see API reference.