SearchFilter

Type

A pre-ranking filter: every condition ANDs, and it can only ever narrow the corpus.

Narrows a search before ranking: every condition ANDs with the others, and a filter only ever narrows, since it runs inside the corpus rather than across it. It is the right tool for scoping retrieval per user or per category: tag documents with metadata at add time and match it here. A metadata value can also be a { gte, lte } numeric range; to range on dates, store them as sortable integers at add time (epoch seconds, or a 20250101-style YYYYMMDD) and range on those. It is not a substitute for a SQL query over structured data.

SearchFilter.ts

interface SearchFilter {
  metadata?: Record<string, Scalar | Scalar[] | MetadataRange>
  filename?: string | string[]
  documentIds?: string[]
  pages?: { min?: number; max?: number }
  contains?: string
  phrase?: string
}

Fields

metadata?

Record<string, Scalar | Scalar[] | MetadataRange>

Match tags set at add time. A scalar must equal; an array matches any of its values; a { gte?, lte? } object matches a numeric range; keys AND together.

filename?

string | string[]

Exact filename, or any of several.

documentIds?

string[]

Restrict to specific documents.

pages?

{ min?, max? }

Inclusive page range, for paged formats like PDF.

contains?

string

Chunk text must contain ALL of these words, in any order.

phrase?

string

Chunk text must contain this exact word sequence, adjacent and in order.

Scope to a tenant, and a date range

await Docs.search(q, {
  // dates stored as sortable integers (YYYYMMDD) at add time
  filter: { metadata: { userId, publishedAt: { gte: 20250101 } } },
});