tai/research/fuzzy-matching-selectors/postgresql-pg-trgm.md

# PostgreSQL pg_trgm documentation

## Metadata

| Field | Value |
|---|---|
| Institute | Molodetz Institute — Research & Retrieval Division |
| Subject | fuzzy-matching-selectors |
| Document type | Source Dossier |
| Tier | 1 |
| Source title | PostgreSQL pg_trgm documentation |
| Source URL | https://www.postgresql.org/docs/current/pgtrgm.html |
| Source publisher / author | PostgreSQL Global Development Group |
| Source type | vendor docs |
| Source date (published) | Unknown — not stated |
| Date researched | 2026-10-25 |
| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
| Research method | direct page fetch |
| Confidence | High |
| Status | Active |

## Summary

The documentation of PostgreSQL's trigram similarity module, the reference definition of trigram matching.

## Key findings

- A trigram is three consecutive characters; non-alphanumerics are ignored and each word is padded with two leading spaces and one trailing space: 'cat' gives '  c', ' ca', 'cat', 'at '.
- similarity() ranges from 0 to 1. The page gives no formula, but its example (word vs words: 4 shared of 7 distinct trigrams gives 0.571429) is consistent with Jaccard.
- word_similarity() is the greatest similarity between the first string and any continuous extent of the second (word_similarity('word','two words') = 0.8); strict_word_similarity forces word boundaries.
- Default thresholds: % uses 0.3, <% uses 0.6, <<% uses 0.5.

## Pros / strengths

Authoritative, with worked examples that make a test oracle (4/7).

## Cons / limitations / caveats

Formula inferred from an example rather than stated. Tuned for database indexing, defaults are not calibrated for identifier ids.

## Relevance to tai

Defines `FuzzyMatcher::Trigram` (padding and Jaccard). The test asserts the 4/7 example.

## Changelog

| Date | Change |
|---|---|
| 2026-10-25 | Initial dossier created. |