PgORM::FullTextSearch
Full-text search support using PostgreSQL's tsvector and tsquery.
This module provides a comprehensive interface to PostgreSQL's powerful full-text search capabilities, including:
- Basic text search with multiple columns
- Weighted search (prioritize certain columns)
- Ranked search (order by relevance)
- Phrase search (exact phrase matching)
- Proximity search (words exactly N positions apart)
- Prefix search (word prefix matching)
- Pre-computed tsvector columns (for production performance)
search, search_weighted, search_ranked, search_ranked_weighted,
search_vector and search_vector_ranked pass the query to to_tsquery,
so it must be valid tsquery syntax (e.g. "crystal & programming"); plain
multi-word input raises a PostgreSQL syntax error. Use search_plain or
search_vector_plain (plainto_tsquery) for user-entered text.
Basic Usage
# Simple search across multiple columns
Article.search("crystal & programming", :title, :content)
# Plain text search (safe for user input)
Article.search_plain("crystal programming", :title, :content)
# Weighted search (title more important than content)
Article.search_weighted("crystal", {
:title => FullTextSearch::Weight::A, # Weight 1.0
:content => FullTextSearch::Weight::B, # Weight 0.4
})
# Ranked search (ordered by relevance)
Article.search_ranked("crystal & programming", :title, :content)
Advanced Usage
# Phrase search (exact phrase)
Article.search_phrase("crystal programming language", :content)
# Proximity search ("programming" exactly 5 positions after "crystal")
Article.search_proximity("crystal", "programming", 5, :content)
# Prefix search (matches crystal, crystalline, etc.)
Article.search_prefix("cryst", :title, :content)
Production Optimization
For better performance, use pre-computed tsvector columns:
-- Add tsvector column
ALTER TABLE articles ADD COLUMN search_vector tsvector;
-- Create GIN index
CREATE INDEX articles_search_idx ON articles USING GIN(search_vector);
-- Auto-update trigger
CREATE TRIGGER articles_search_update
BEFORE INSERT OR UPDATE ON articles
FOR EACH ROW EXECUTE FUNCTION
tsvector_update_trigger(search_vector, 'pg_catalog.english', title, content);
Then use the optimized search methods:
Article.search_vector("crystal & programming", :search_vector)
Article.search_vector_ranked("crystal", :search_vector)
Instance methods
Performs full-text search using to_tsvector and to_tsquery
query must be valid tsquery syntax; use search_plain for user input.
Article.search("crystal & programming", :title, :content)
Article.search("crystal | ruby", :title, config: "simple")
Article.search("cryst:*", :title) # Prefix matching
Article.search("crystal", ["title", "content"]) # Array of strings
Overload: Accepts Symbol columns
Overload: Accepts String columns
Performs phrase search (exact phrase matching)
Article.search_phrase("crystal programming language", ["content"])
Article.search_phrase("crystal programming", :title, :content)
Overload: Accepts Symbol columns
Overload: Accepts String columns
Performs plain text search using plainto_tsquery (words are ANDed and
operators are ignored), suitable for user input
Article.search_plain("crystal programming", :title, :content)
Overload: Accepts Symbol columns
Overload: Accepts String columns
Performs prefix search
Article.search_prefix("cryst", :title, :content) # Matches crystal, crystalline, etc.
Overload: Accepts Symbol columns
Overload: Accepts String columns
Performs proximity search: matches when word2 appears exactly distance
positions after word1 (tsquery word1 <distance> word2)
Article.search_proximity("crystal", "programming", 5, :content) # Exactly 5 positions apart
Overload: Accepts Symbol columns
Overload: Accepts String columns
Performs full-text search and orders by relevance rank
Article.search_ranked("crystal & programming", ["title", "content"])
Article.search_ranked("ruby", ["title", "content"], rank_normalization: 1)
Article.search_ranked("ruby", :title, :content, rank_function: RankFunction::RankCD)
Overload: Accepts Symbol columns
Overload: Accepts String columns
Performs full-text search with weighted columns and ranking
Article.search_ranked_weighted("crystal", {"title" => Weight::A, "content" => Weight::B})
Article.search_ranked_weighted("crystal", {:title => Weight::A, :content => Weight::B})
Overload: Accepts Symbol keys for weighted columns
Searches using a pre-computed tsvector column (recommended for production)
# Setup (run once):
# ALTER TABLE articles ADD COLUMN search_vector tsvector;
# CREATE INDEX articles_search_idx ON articles USING GIN(search_vector);
# CREATE TRIGGER articles_search_update BEFORE INSERT OR UPDATE ON articles
# FOR EACH ROW EXECUTE FUNCTION
# tsvector_update_trigger(search_vector, 'pg_catalog.english', title, content);
Article.search_vector("crystal & programming", "search_vector")
Article.search_vector("crystal | ruby", :search_vector, config: "simple")
Overload: Accepts Symbol for vector column
Searches using a pre-computed tsvector column with plain text query
Article.search_vector_plain("crystal programming", "search_vector")
Article.search_vector_plain("crystal programming", :search_vector)
Overload: Accepts Symbol for vector column
Searches using a pre-computed tsvector column with ranking
Article.search_vector_ranked("crystal", "search_vector")
Article.search_vector_ranked("crystal", :search_vector, rank_normalization: 1)
Article.search_vector_ranked("crystal", :search_vector, rank_function: RankFunction::RankCD)
Overload: Accepts Symbol for vector column
Performs full-text search with weighted columns
Article.search_weighted("crystal", {"title" => Weight::A, "content" => Weight::B})
Article.search_weighted("crystal", {:title => Weight::A, :content => Weight::B})