How does full-text search work in PostgreSQL?

Question

Accepted Answer

PostgreSQL has **built-in full-text search** — searching documents/text for words with stemming, ranking, and language awareness, far more powerful than `LIKE`. It uses **`tsvector`** (processed document) and **`tsquery`** (search query) types, with GIN indexes for speed.

## The problem LIKE doesn't solve

```text
LIKE '%word%' → no stemming (won't match "running" for "run"), no ranking, no language
  awareness, and can't use an index well (leading wildcard) → slow and limited.
Full-text search → stems words, ignores stop words, ranks by relevance, indexable.
```

## tsvector and tsquery

```sql
-- to_tsvector — process text into searchable lexemes (stemmed, stop-words removed)
SELECT to_tsvector('english', 'The cats are running fast');
-- → 'cat':2 'fast':5 'run':4  (stemmed: cats→cat, running→run; "the"/"are" removed)

-- to_tsquery / plainto_tsquery — parse a search query
SELECT to_tsvector('english', body) @@ to_tsquery('english', 'running')
FROM articles;   -- @@ = the match operator; matches "run" stem
```

`to_tsvector` converts text into normalized **lexemes** (stems words, removes stop words), and `to_tsquery` parses the search terms. The `@@` operator tests for a match — so "running" matches documents containing "run," "runs," etc.

## A searchable column + GIN index (the practical setup)

```sql
-- add a generated tsvector column and index it with GIN
ALTER TABLE articles ADD COLUMN search_vector tsvector
  GENERATED ALWAYS AS (to_tsvector('english', title || ' ' || body)) STORED;
CREATE INDEX idx_search ON articles USING GIN (search_vector);

-- fast searches using the index
SELECT title FROM articles
WHERE search_vector @@ plainto_tsquery('english', 'machine learning');
```

## Ranking results by relevance

```sql
SELECT title, ts_rank(search_vector, query) AS rank
FROM articles, plainto_tsquery('english', 'database') query
WHERE search_vector @@ query
ORDER BY rank DESC;          -- most relevant first
```

`ts_rank` scores how well each document matches, enabling relevance-ordered results.

## Why it matters

PostgreSQL's built-in full-text search is a valuable feature that lets you implement **search functionality within your database** — without needing a separate search engine (like Elasticsearch) for many use cases — so understanding it is useful for applications needing text search.

The key value is that it's far more powerful than `LIKE` (which can't stem words, rank results, or be indexed efficiently): full-text search provides **word stemming** (matching "running" for "run"), **stop-word removal**, **language awareness**, **relevance ranking**, and crucially is **indexable** (with GIN indexes for fast searches) — delivering real search capabilities (the kind users expect: matching word variations, ranking by relevance) directly in Postgres.

Understanding the core concepts — **`tsvector`** (processed, stemmed document text), **`tsquery`** (parsed search terms), the **`@@`** match operator, and **`ts_rank`** for relevance ranking — plus the practical setup (a generated `tsvector` column indexed with GIN for performance) covers how to implement effective search.

While dedicated search engines offer more for complex needs, Postgres full-text search is sufficient and convenient for many applications (avoiding the operational complexity of a separate search system and keeping search data consistent with your relational data).

Since text search is a common application requirement, and since Postgres provides capable built-in full-text search (powerful, indexable, with stemming and ranking) that often suffices without a separate search engine, understanding it — the tsvector/tsquery model, the indexed setup, and ranking — is valuable, practically-relevant knowledge that lets you add real search functionality using PostgreSQL's built-in capabilities, a useful feature that's often overlooked in favor of more complex external solutions when Postgres would suffice.