Couchbase FTS and N1QL: A Practical Pattern for Search-First Apps

Your Couchbase bucket holds thousands of JSON documents, and users expect search that tolerates typos, matches phrases, and ranks results by relevance. A pure N1QL query using LIKE '%term%' scans the bucket and returns rows in arbitrary order. This approach is computationally expensive at scale. The practical takeaway: treat Couchbase Full-Text Search (FTS) as a relevance-based filter that produces a shortlist of document IDs, then use N1QL to fetch the full content.

What FTS actually does

FTS is a separate engine built on an inverted index—a structure that maps each term to the documents containing it, much like the index at the back of a book. Because the index is maintained automatically as documents are created, updated, or deleted, search results reflect the current state of the bucket without manual ETL processes.

Where N1QL excels at structured predicates and joins, FTS adds capabilities that are awkward in SQL-style queries: fuzzy matching for misspellings, phrase matching, and relevance scoring that ranks how well a document matches a query. These features operate on text fields inside your JSON documents.

The ID-then-fetch pattern

FTS does not return full rows; it returns a list of hits, each carrying a score. A common and effective pattern is to run the FTS query first, extract the document IDs, and then issue a N1QL query:

SELECT *
FROM your-bucket
WHERE META().id IN($searchIds);

This keeps the expensive relevance computation inside FTS while relational logic—joins, aggregations, or filters on non-indexed fields—stays inside N1QL. Couchbase SDKs expose a fluent API that allows you to chain the search and fetch, reducing round-trip latency in your application code.

Worked example: Relevance scan vs. FTS shortlist

To see the difference, stand up a local Couchbase instance and create a bucket with a few thousand JSON documents containing a text field. Create an FTS index on that field. You can do this via the web console or the FTS REST API.

First, try a pure N1QL scan:

SELECT *
FROM sample-bucket
WHERE description LIKE '%wireless%';

Run this in the Query Workbench. Without a secondary index, the query engine must examine every document, and the results are not ranked by relevance.

Second, issue an FTS query for wireless against your index. The response contains IDs ordered by score. Copy those IDs into the N1QL query as a parameter array. The FTS step touches only the inverted index, and the N1QL step retrieves the documents by primary key.

This is a diagnostic decision: if the FTS index is missing or misconfigured, the search returns zero hits, indicating a problem in the index definition rather than the query syntax.

Trade-offs and limitations

FTS indexes consume additional RAM and disk space. Over-indexing—creating many FTS indexes or indexing every field—can degrade overall cluster performance. Choose index fields deliberately, set field weights when some matter more than others, and use the limit and skip options in your FTS query to control result size.

The hard limitation is that FTS does not support joins. Any relational logic must happen in N1QL after the search step. Additionally, the default FTS query language is JSON; constructing complex queries by hand invites syntax errors. Prefer SDK builders or validate your JSON payload against the REST API before deploying.

Verify it yourself

You can confirm this pattern on a local cluster in steps:

1. Start Couchbase Server locally, create a bucket, and load a sample data set.
2. Create an FTS index on a text field and wait for it to reach a ready state.
3. Run an FTS search for a keyword and note the returned document IDs.
4. Execute a N1QL SELECT using those IDs and confirm the full documents are returned.
5. Compare the response profile against a pure LIKE scan to observe the difference in latency and ordering.

Check the cluster logs for FTS and N1QL activity to verify that the search and fetch steps executed as expected. If the FTS index is still building, results may be incomplete until the index status shows ready.