A newer version of this documentation is available.

Search

how-to

March 9, 2025

+ 12

You can use the Full Text Search service (FTS) to create queryable full-text indexes in Couchbase Server.

Full Text Search or FTS allows you to create, manage and query full text indexes on JSON documents stored in Couchbase buckets. It uses natural language processing for indexing and querying documents, provides relevance scoring on the results of your queries and has fast indexes for querying a wide range of possible text searches.

Some of the supported query-types include simple queries like Match and Term queries, range queries like Date Range and Numeric Range and compound queries for conjunctions, disjunctions and/or boolean queries.

Getting Started

After familiarizing yourself with how to create and query a Search index in the UI you can query it from the SDK. Intentionally the API itself is very similar to the query and analytics ones, the main difference being that you cannot cast the resulting rows into a domain object directly but rather get a SearchRow returned. The reason for this is that a search row ("hit") has more metadata associated with it than you potentially want to look at.

python
ViewCopy
from couchbase.cluster import Cluster
from couchbase.options import ClusterOptions, SearchOptions
from couchbase.auth import PasswordAuthenticator
from couchbase.exceptions import CouchbaseException
import couchbase.search as search


cluster = Cluster.connect(
    "couchbase://your-ip",
    ClusterOptions(PasswordAuthenticator("Administrator", "password")))
bucket = cluster.bucket("travel-sample")
collection = bucket.default_collection()

try:
    result = cluster.search_query(
        "travel-sample-index", search.QueryStringQuery("Paris"))

    for row in result.rows():
        print("Found row: {}".format(row))

    print("Reported total rows: {}".format(
        result.metadata().metrics().total_rows()))

except CouchbaseException as ex:
    import traceback
    traceback.print_exc()

When using a Couchbase version < 6.5 you must create a valid Bucket connection using cluster.bucket(name) before you can use Analytics.

Let’s break it down. A Search query is always performed at the Cluster level, using the search_query method. It takes the name of the index and the type of query as required arguments and then allows to provide additional options if needed (in the example above, no options are specified).

Once a result returns you can iterate over the returned rows, and/or access the SearchMetaData associated with the query.

Search Queries

The second mandatory argument in the example above used QueryStringQuery("query") to specify the query to run against the search index. The query string is the simplest form, but there are many more available. The table below lists all of them with a short description of each. You can combine them with conjuncts and disjuncts respectively. Location objects are specified as a Tuple[SupportsFloat,SupportsFloat] of longitude and latitude respectively.

Table 1. Available Search Queries
Name	Description
`QueryStringQuery(query: str)`	Accept query strings, which express query-requirements in a special syntax.
`MatchQuery(match: str)`	A match query analyzes input text, and uses the results to query an index.
`MatchPhraseQuery(match_phrase: str)`	The input text is analyzed, and a phrase query is built with the terms resulting from the analysis.
`PrefixQuery(prefix: str)`	A prefix query finds documents containing terms that start with the specified prefix.
`RegexQuery(regexp: str)`	A regexp query finds documents containing terms that match the specified regular expression.
`TermRangeQuery()`	A term range query finds documents containing a term in the specified field within the specified range.
`NumericRangeQuery()`	A numeric range query finds documents containing a numeric value in the specified field within the specified range.
`DateRangeQuery()`	A date range query finds documents containing a date value, in the specified field within the specified range.
`DisjunctionQuery(*queries: SearchQuery)`	A disjunction query contains multiple child queries. Its result documents must satisfy a configurable min number of child queries.
`ConjunctionQuery(*queries: SearchQuery)`	A conjunction query contains multiple child queries. Its result documents must satisfy all of the child queries.
`WildcardQuery(wildcard: str)`	A wildcard query uses a wildcard expression, to search within individual terms for matches.
`DocIdQuery(*ids: str)`	A doc ID query returns the indexed document or documents among the specified set.
`BooleanFieldQuery(value: bool)`	A boolean field query searches fields that contain boolean true or false values.
`TermQuery(term: str)`	Performs an exact match in the index for the provided term.
`PhraseQuery(*terms: str)`	A phrase query searches for terms occurring in the specified position and offsets.
`MatchAllQuery()`	Matches all documents in an index, irrespective of terms.
`MatchNoneQuery()`	Matches no documents in the index.
`GeoBoundingBoxQuery(top_left: Location, bottom_right: Location)`	Searches inside the given bounding box coordinates.
`GeoDistanceQuery(distance: str, location: Location )`	Searches inside the distance from the given location coordinate.

The Search Result

Once the Search query is executed successfully, the server starts sending back the resultant hits.

python
ViewCopy
result = cluster.search_query(
    "travel-sample-index", search.PrefixQuery("swim"), SearchOptions(fields=["description"]))

for row in result.rows():
    print("Score: {}".format(row.score))
    print("Document Id: {}".format(row.id))

    # print fields included in query:
    print(row.fields)

The SearchRow contains the following methods:

Table 2. SearchRow
`index → str`	The name of the FTS index that gave this result.
`id → str`	The id of the matching document.
`score →float`	The score of this hit.
`explanation → str`	If enabled provides an explanation in JSON form.
`locations → SearchRowLocations`	The individual locations of the hits.
`fragments → Optional[Mapping[str, str]]`	The fragments for each field that was requested as highlighted.
`fields → Dict[str, Any]`	Access to the returned fields.

Note that the SearchMetaData also contains potential errors, because the SDK will keep streaming results if the initial response came back successfully. This makes sure that even with partial data usually Search results are useable, so if you absolutely need to check if all partitions are present in the result double check the error (and not only catch an exception on the query itself).

Search Options

The cluster.search_query function provides an array of named parameters to customize your query via **kwargs or SearchOptions. The following table lists them all:

Table 3. Available Search Options
Name	Description
`limit: int`	Allows to limit the number of hits returned.
`skip: int`	Allows to skip the first N hits of the results returned.
`explain: bool`	Adds additional explain debug information to the result.
`scan_consistency: SearchScanConsistency`	Specifies a different consistency level for the result hits.
`consistent_with: MutationState`	Allows to be consistent with previously performed mutations.
`highlight_style: HighlightStyle`	Specifies highlighting rules for matched fields.
`highlight_fields: List[str]`	Specifies fields to highlight.
`sort: List[str]`	Allows to provide custom sorting rules.
`facets: Map[str, SearchFacet]`	Allows to fetch facets in addition to the regular hits.
`fields: List[str]`	Specifies fields to be included.
`raw: JSON`	Escape hatch to add arguments that are not covered by these options.
`collections: List[str]`	Limits the search query to a specific list of collection names.

Limit and Skip

It is possible to limit the returned results to a maximum amount using the limit option. If you want to skip the first N records it can be done with the skip option.

python
ViewCopy
result = cluster.search_query(
    "travel-sample-index", search.TermQuery("downtown"), SearchOptions(limit=4, skip=3))

ScanConsistency and ConsistentWith

By default, all Search queries will return the data from whatever is in the index at the time of query. These semantics can be tuned if needed so that the hits returned include the most recently performed mutations, at the cost of slightly higher latency since the index needs to be updated first.

There are two ways to control consistency: either by supplying a custom SearchScanConsistency or using consistentWith. At the moment the cluster only supports consistentWith, which is why you only see SearchScanConsistency.NOT_BOUNDED in the enum which is the default setting. The way to make sure that recently written documents show up in the rfc works as follows (commonly referred to "read your own writes" — RYOW):

Scan consistency example:

python
ViewCopy
result = cluster.search_query(
    "travel-sample-index", search.TermQuery("downtown"), SearchOptions(scan_consistency=SearchScanConsistency.NOT_BOUNDED))

ConsistentWith consistency example:

python
ViewCopy
new_airline = {
    "callsign": None,
    "country": "United States",
    "iata": "TX",
    "icao": "TX99",
    "id": 123456789,
    "name": "Howdy Airlines",
    "type": "airline"
}

res = collection.upsert(
    "airline_{}".format(new_airline["id"]), new_airline)

ms = MutationState(res)

result = cluster.search_query(
    "travel-sample-index", search.PrefixQuery("howdy"), SearchOptions(consistent_with=ms))

Highlight

It is possible to enable highlighting for matched fields. You can either rely on the default highlighting style or provide a specific one. The following snippet uses HTML formatting for two fields:

python
ViewCopy
result = cluster.search_query(
    "travel-sample-index", search.TermQuery("downtown"), SearchOptions(highlight_style=HighlightStyle.Html, highlight_fields=["description", "name"]))

Sort

By default the Search Engine will sort the results in descending order by score. This behavior can be modified by providing a different sorting order which can also be nested.

python
ViewCopy
result = cluster.search_query(
    "travel-sample-index", search.TermQuery("downtown"), SearchOptions(sort=["_score", "description"]))

Facets are aggregate information collected on a result set and are useful when it comes to categorization of result data. The SDK allows you to provide many different facet configurations to the Search Engine, the following example shows how to create a facet based on a term. Other possible facets include numeric and date ranges.

python
ViewCopy
facet_name = 'activity'
facet = TermFacet('activity')
query = TermQuery('home')
q_res = cluster.search_query('travel-sample-index',
                            query,
                            SearchOptions(limit=10, facets={facet_name: facet}))

for row in q_res.rows():
    print(f'Found row: {row}')

print(f'facets: {q_res.facets()}')

Fields

You can tell the Search Engine to include the full content of a certain number of indexed fields in the response.

python
ViewCopy
result = cluster.search_query(
    "travel-sample-index", search.TermQuery("swanky"), SearchOptions(fields=["name", "description"]))

Collections

It is now possible to limit the search query to a specific list of collection names.

Note that this feature is only supported with Couchbase Server 7.0 or later.

python
ViewCopy
result = cluster.search_query(
    "travel-sample-index", search.TermQuery("downtown"), SearchOptions(collections=["hotel", "airport"]))

Async APIs

In addition to the blocking API on Cluster, the SDK provides asyncio and Twisted APIs on ACluster or TxCluster respectively. If you are in doubt of which API to use, we recommend looking at the asyncio API first.

Simple queries with both asyncio and Twisted APIs look similar to the blocking one:

ACouchbase

python
ViewCopy
from acouchbase.cluster import Cluster, get_event_loop
from couchbase.options import ClusterOptions
from couchbase.auth import PasswordAuthenticator
from couchbase.exceptions import CouchbaseException
import couchbase.search as search


async def get_couchbase():
    cluster = Cluster(
        "couchbase://your-ip",
        ClusterOptions(PasswordAuthenticator("Administrator", "password")))
    bucket = cluster.bucket("travel-sample")
    await bucket.on_connect()
    collection = bucket.default_collection()

    return cluster, bucket, collection

# NOTE: the travel-sample-index search index might need to be created
async def simple_query(cluster):
    try:
        result = cluster.search_query(
            "travel-sample-index", search.QueryStringQuery("swanky"))

        async for row in result:
            print("Found row: {}".format(row))
        
    except CouchbaseException as ex:
        print(ex)


loop = get_event_loop()
cluster, bucket, collection = loop.run_until_complete(get_couchbase())
loop.run_until_complete(simple_query(cluster))

TxCouchbase

python
ViewCopy
# **IMPORTANT** need to do this import prior to importing the reactor (new to the Python 4.x SDK)
import txcouchbase
from twisted.internet import reactor

from txcouchbase.cluster import TxCluster
from couchbase.options import ClusterOptions
from couchbase.auth import PasswordAuthenticator
import couchbase.search as search


def handle_query_results(result):
    for r in result.rows():
        print("query row: {}".format(r))
    print("loop finished")
    reactor.stop()


def on_streaming_error(error):
    print("Streaming operation had an error.\nError: {}".format(error))
    reactor.stop()

# NOTE: the travel-sample-index search index might need to be created
def on_connect_ok(result, cluster):
    # create a bucket object
    bucket = cluster.bucket("travel-sample")
    # create a collection object
    cb = bucket.default_collection()

    d = cluster.search_query("travel-sample-index", search.QueryStringQuery("swanky"))
    d.addCallback(handle_query_results).addErrback(on_streaming_error)


def on_connect_err(error):
    print(f"Unable to connect.\n{error}")


cluster = TxCluster("couchbase://your-ip",
                    ClusterOptions(PasswordAuthenticator("Administrator", "password")))

# wait for connect
cluster.on_connect().addCallback(on_connect_ok, cluster).addErrback(on_connect_err)

reactor.run()