Full-Text Search

$text searches natural-language text using each database’s own full-text engine. It goes at the top level of $where, alongside regular field conditions.

You write

const items = await querier.findMany(Item, {
  $where: {
    $text: { $fields: ['name', 'description'], $value: 'wireless keyboard' },
    isActive: true,
  },
});

$fields lists the columns to search; $value is the user’s query text.

Per-Dialect SQL

Generated SQL (PostgreSQL / CockroachDB)

SELECT * FROM "Item"
WHERE to_tsvector("name" || ' ' || "description") @@ websearch_to_tsquery($1)
  AND "isActive" = $2

Generated SQL (MySQL / MariaDB)

SELECT * FROM `Item` WHERE MATCH(`name`, `description`) AGAINST(?) AND `isActive` = ?

Generated SQL (SQLite)

SELECT * FROM `Item` WHERE `Item` MATCH {`name` `description`} : ? AND `isActive` = ?

MongoDB maps $text to its own $text operator ({ $text: { $search: value } }).

websearch_to_tsquery, not to_tsquery

Until 0.20.0 PostgreSQL used to_tsquery, which raises syntax error in tsquery for anything it cannot parse - including a plain two-word search like 'wireless keyboard'. websearch_to_tsquery accepts free-form input the way a search box does: quoted phrases ("wireless keyboard"), or, and -negation. It never raises a syntax error.

Text-Search Configuration (PostgreSQL)

$config selects the text-search configuration - the dictionary that drives stemming and stop-words - and is applied to both the document and the query. It defaults to the server’s default_text_search_config.

You write

const items = await querier.findMany(Item, {
  $where: { $text: { $fields: ['name'], $value: 'running shoes', $config: 'english' } },
});

Generated SQL (PostgreSQL)

SELECT * FROM "Item" WHERE to_tsvector($1::regconfig, "name") @@ websearch_to_tsquery($1::regconfig, $2)

The value is bound as a parameter (never interpolated) and its placeholder is reused by both calls. Other dialects ignore $config.

Index Requirements

Full-text search needs dialect-specific setup - $text generates the query, not the index:

Dialect	Requirement
PostgreSQL / CockroachDB	Works without an index, but to_tsvector(col) computed per row cannot use one. For large tables, add a stored tsvector column (or expression index) with a GIN index.
MySQL / MariaDB	Requires a FULLTEXT index covering exactly the columns listed in $fields, in that order - otherwise the query errors.
SQLite	Requires an FTS5 virtual table; MATCH only applies to one.
MongoDB	Requires a text index on the searched fields.

Combining with semantic search

Full-text search finds exact term matches; vector search finds semantically similar text. Hybrid search runs both and fuses the rankings - MongoDB does this natively with $rankFusion, and on PostgreSQL it is a reciprocal-rank-fusion query over a tsvector match plus a pgvector distance sort.