Search API

Added in v1.5.0. The Search API provides a simple, reliable keyword search across the documents of a collection. It is separate from the normal find() query system and is designed for free-text / “contains” style searches.

When to use Search vs find()
Use find() for exact filters, operators ($gt, $in, $regex …) and indexed lookups.
Use search() when the user types a keyword and you want to look for that text inside one or more fields.

Basic usage

const results = users.search({
  keyword: "john"
}).toArray();

The method returns a QueryBuilder, so you can still chain .limit(), .skip(), .sort(), .project(), .toArray(), .first() and .count().

Options

Option	Type	Default	Description
`keyword`	string	—	The text to search for (required).
`fields`	string[] \| null	`null`	Fields to search. `null` / omitted = search all fields.
`exclude`	string[]	`[]`	Fields that should never be searched.
`caseInsensitive`	boolean	`true`	Perform a case-insensitive contains match.

Examples

Search specific fields

users.search({
  keyword: "alice",
  fields: ["name", "email", "bio"]
}).toArray();

Exclude sensitive fields

users.search({
  keyword: "secret",
  exclude: ["password", "token", "ssn"]
}).toArray();

Case-sensitive search

users.search({
  keyword: "Alice",
  caseInsensitive: false
}).toArray();

With limit, sort and project

const page = users.search({ keyword: "dev" })
  .sort({ name: 1 })
  .limit(20)
  .project({ name: 1, email: 1 })
  .toArray();

Count matches

const total = users.search({ keyword: "engineer" }).count();

Async version

const builder = await users.searchAsync({ keyword: "john" });
const docs = builder.limit(10).toArray();

Matching rules

Matching is a simple contains (substring) check.
By default it is case-insensitive.
Only string and number values are considered (other types are skipped).
Nested fields can be targeted by passing the dotted path in fields.

Migration / What changed

This is a pure addition. Existing find() / findAsync() code continues to work exactly as before. No breaking changes.