How to Use ts_rank in PostgreSQL for Full-Text Search Ranking

In PostgreSQL, use ts_rank to calculate the relevance ranking of full-text search results by comparing a document's text vector with a search query's text query. It returns a float value where higher means more relevant, helping you order search results by importance.

Syntax

The ts_rank function calculates the relevance rank of a document based on a text search vector and a text search query.

• ts_rank(vector, query): Returns a float ranking score.
• vector: A tsvector representing the document's searchable text.
• query: A tsquery representing the search terms.
• Optional weights array can be added to give different importance to parts of the document.

sql

ts_rank(vector tsvector, query tsquery) RETURNS float

-- Optional weights:
ts_rank(weights float[], vector tsvector, query tsquery) RETURNS float

Example

This example shows how to rank documents by relevance using ts_rank with a simple full-text search.

sql

CREATE TABLE articles (id serial PRIMARY KEY, title text, body text);

INSERT INTO articles (title, body) VALUES
('PostgreSQL Tutorial', 'Learn how to use PostgreSQL full-text search.'),
('Full-Text Search Guide', 'This guide explains full-text search ranking.'),
('Cooking Tips', 'Tips for cooking delicious meals.');

SELECT id, title, ts_rank(to_tsvector(body), to_tsquery('full & text')) AS rank
FROM articles
WHERE to_tsvector(body) @@ to_tsquery('full & text')
ORDER BY rank DESC;

Output

 id |         title          |      rank      
----+------------------------+----------------
  2 | Full-Text Search Guide | 0.204545453071 
  1 | PostgreSQL Tutorial    | 0.136363640785 
(2 rows)

Common Pitfalls

Common mistakes when using ts_rank include:

• Not using to_tsvector and to_tsquery to convert text and queries properly.
• Ignoring the order of ranking results, which can lead to confusing outputs.
• Not using weights when documents have multiple fields with different importance.

Always ensure your text and query are properly converted and consider weights for better ranking.

sql

/* Wrong: Using plain text instead of tsvector and tsquery */
SELECT ts_rank('full text'::tsvector, to_tsquery('full & text'));

/* Right: Use to_tsvector and to_tsquery */
SELECT ts_rank(to_tsvector('full text'), to_tsquery('full & text'));

Quick Reference

Function	Description
ts_rank(vector, query)	Calculates relevance rank of text vector against query.
to_tsvector(text)	Converts plain text to searchable text vector.
to_tsquery(text)	Converts search string to text query.
ts_rank(weights, vector, query)	Ranks with custom weights for different document parts.

Key Takeaways

Use ts_rank with to_tsvector and to_tsquery to rank full-text search results by relevance.

Higher ts_rank values mean more relevant matches to the search query.

Apply weights in ts_rank to prioritize important document sections.

Always order your query results by ts_rank DESC to show best matches first.

Avoid passing plain text directly; always convert to tsvector and tsquery types.