Full-text search with Postgres in Supabase - Step-by-Step Execution

Process Flow - Full-text search with Postgres

User inputs search query

↓

Convert query to tsquery format

↓

Postgres searches tsvector column

↓

Match rows returned

↓

Results sent back to user

The user enters a search phrase, which is converted into a format Postgres understands. Postgres then searches the indexed text data and returns matching rows.

Execution Sample

Supabase

SELECT * FROM articles
WHERE to_tsvector('english', content) @@ to_tsquery('english', 'cloud & infrastructure');

This query searches the 'content' column of 'articles' for rows matching the words 'cloud' AND 'infrastructure'.

Process Table

Step	Action	Input/Condition	Result
1	Receive search query	'cloud & infrastructure'	Query string ready
2	Convert to tsquery	to_tsquery('english', 'cloud & infrastructure')	tsquery: 'cloud' & 'infrastructure'
3	Convert content to tsvector	to_tsvector('english', content)	tsvector of content created
4	Match tsquery against tsvector	tsvector @@ tsquery	True if content matches both words
5	Return matching rows	Rows where match is True	Rows with both words in content
6	End	No more rows	Query complete

💡 All rows checked; only those matching both 'cloud' and 'infrastructure' returned

Status Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
search_query	null	'cloud & infrastructure'	'cloud & infrastructure'	'cloud & infrastructure'	'cloud & infrastructure'
tsquery	null	'cloud' & 'infrastructure'	'cloud' & 'infrastructure'	'cloud' & 'infrastructure'	'cloud' & 'infrastructure'
tsvector	null	null	tsvector of content	tsvector of content	tsvector of content
match_result	null	null	null	True or False per row	Only True rows returned

Key Moments - 3 Insights

Why do we convert the search query to tsquery format?

Because Postgres uses tsquery to understand the search terms logically (AND, OR). This is shown in step 2 of the execution_table.

What does the @@ operator do in the query?

It checks if the tsvector (document text) matches the tsquery (search terms). This matching step is step 4 in the execution_table.

Why do we convert content to tsvector before searching?

Because tsvector stores text in a searchable format optimized for full-text search, as shown in step 3.

Visual Quiz - 3 Questions

Look at the execution_table, what is the tsquery value after step 2?

A 'cloud infrastructure'

B 'cloud' | 'infrastructure'

C 'cloud' & 'infrastructure'

D 'cloud' && 'infrastructure'

💡 Hint

Check the 'Result' column in row with Step 2 in execution_table

At which step does Postgres check if the content matches the search terms?

A Step 4

B Step 3

C Step 2

D Step 5

💡 Hint

Look for the step where '@@' operator is applied in execution_table

If the search query was changed to 'cloud | infrastructure', how would tsquery change after step 2?

A 'cloud' & 'infrastructure'

B 'cloud' | 'infrastructure'

C 'cloud infrastructure'

D 'cloud' && 'infrastructure'

💡 Hint

The operator in tsquery reflects AND (&) or OR (|) logic, see step 2 in execution_table

Concept Snapshot

Full-text search in Postgres uses tsvector to store searchable text and tsquery to represent search terms.
Use @@ operator to match tsquery against tsvector.
Convert both content and query to these formats for efficient search.
Supports logical operators like & (AND) and | (OR).
Example: SELECT * FROM table WHERE to_tsvector(col) @@ to_tsquery('term1 & term2');

Full Transcript

Full-text search with Postgres works by converting the user's search phrase into a tsquery format that Postgres understands. The text content in the database is converted into a tsvector format, which is optimized for searching. Postgres then uses the @@ operator to check if the tsvector matches the tsquery. Rows that match are returned as search results. This process involves converting both the query and the content into special formats and then performing a logical match. The key steps are receiving the query, converting it, converting the content, matching, and returning results.

Practice

1. What is the main purpose of using to_tsvector in Postgres full-text search?

easy

A. To convert text into a searchable document format

B. To insert new rows into a table

C. To delete unwanted text from a column

D. To create a backup of the database

Solution

1. Step 1: Understand to_tsvector function

   to_tsvector converts plain text into a special searchable format called a tsvector, which breaks text into words and normalizes them for searching.

2. Step 2: Identify its role in full-text search

   This conversion allows Postgres to quickly find matching words during a search query.

3. Final Answer:

   To convert text into a searchable document format -> Option A

4. Quick Check:

   to_tsvector = searchable format [OK]

Hint: Remember: to_tsvector prepares text for searching [OK]

Common Mistakes:

• Confusing to_tsvector with data insertion
• Thinking it deletes text
• Assuming it backs up data

2. Which of the following is the correct syntax to perform a full-text search using to_tsquery in Postgres?

easy

A. SELECT * FROM articles WHERE to_tsquery('search & term') @@ content;

B. SELECT * FROM articles WHERE to_tsquery(content) @@ 'search & term';

C. SELECT * FROM articles WHERE to_tsquery('search & term') = content;

D. SELECT * FROM articles WHERE content @@ to_tsquery('search & term');

Solution

1. Step 1: Understand to_tsquery usage

   to_tsquery creates a search query from a string like 'search & term'. It should be on the right side of the @@ operator.

2. Step 2: Check correct operator usage

   The @@ operator checks if the tsvector (usually a column) matches the tsquery. So the column (tsvector) is on the left, and to_tsquery is on the right.

3. Final Answer:

   SELECT * FROM articles WHERE content @@ to_tsquery('search & term'); -> Option D

4. Quick Check:

   tsvector @@ tsquery = correct syntax [OK]

Hint: Remember: tsvector column @@ to_tsquery('query') [OK]

Common Mistakes:

• Putting to_tsquery on the left side
• Using = instead of @@ operator
• Passing column name inside to_tsquery

3. Given the table products with a column description, what will this query return?

SELECT id FROM products WHERE to_tsvector(description) @@ to_tsquery('red & apple');

medium

A. All products with descriptions containing both 'red' and 'apple'

B. All products with descriptions containing either 'red' or 'apple'

C. All products with descriptions containing the exact phrase 'red apple'

D. No products because the syntax is incorrect

Solution

1. Step 1: Analyze the query logic

   The query uses to_tsvector(description) to convert descriptions into searchable format, then checks if it matches to_tsquery('red & apple').

2. Step 2: Understand the & operator in tsquery

   The & means AND, so it matches rows containing both 'red' and 'apple' anywhere in the description, not necessarily as a phrase.

3. Final Answer:

   All products with descriptions containing both 'red' and 'apple' -> Option A

4. Quick Check:

   'red & apple' means both words present [OK]

Hint: Use & for AND, | for OR in to_tsquery [OK]

Common Mistakes:

• Thinking & means OR
• Assuming exact phrase match
• Confusing syntax causing no results

4. You wrote this query but it returns no results:

SELECT * FROM feedback WHERE to_tsvector(comment) @@ to_tsquery('happy | sad');

What is the most likely reason?

medium

A. The to_tsquery syntax is invalid

B. The comment column is not indexed with a tsvector column

C. The @@ operator is used incorrectly

D. The query should use LIKE instead of full-text search

Solution

1. Step 1: Check query correctness

   The syntax and operator usage are correct for full-text search with to_tsvector and to_tsquery.

2. Step 2: Identify performance and result issues

   If no results appear, often the comment column is not indexed as a tsvector, so the search is slow or ineffective.

3. Final Answer:

   The comment column is not indexed with a tsvector column -> Option B

4. Quick Check:

   Missing tsvector index causes no results [OK]

Hint: Always create a tsvector index for fast full-text search [OK]

Common Mistakes:

• Assuming syntax error when query is correct
• Using LIKE instead of full-text search
• Misusing @@ operator

5. You want to build a search feature on a blog using Supabase and Postgres full-text search. Which approach best improves search speed and accuracy for large text columns?

hard

A. Store search keywords in a separate table and join on it

B. Use LIKE '%keyword%' queries on the text column without indexes

C. Create a generated tsvector column indexed with GIN and query using @@ operator

D. Use regular expressions to scan text columns at query time

Solution

1. Step 1: Understand full-text search optimization

   Creating a generated column that stores the tsvector form of the text allows fast searching without recalculating on each query.

2. Step 2: Use GIN index for fast lookup

   Adding a GIN index on the tsvector column speeds up searches dramatically, making queries efficient and scalable.

3. Step 3: Query with @@ operator for accuracy

   Using the @@ operator with to_tsquery on the indexed tsvector column ensures accurate full-text matching.

4. Final Answer:

   Create a generated tsvector column indexed with GIN and query using @@ operator -> Option C

5. Quick Check:

   Generated tsvector + GIN index = fast, accurate search [OK]

Hint: Index tsvector columns with GIN for best full-text search [OK]

Common Mistakes:

• Using LIKE instead of full-text search
• Not indexing tsvector columns
• Relying on regex for large text search