Searching from the SDK
Edit this article in GitHub
Version 2.3

Searching from the SDK

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 querying documents, provides relevence 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. The .NET SDK exposes an API for performing FTS queries which abstracts some of the complexity of using the underlying REST API.

Important: The FTS feature is a developer preview in Couchbase Server 4.6. As such, the support in the SDK is still uncomitted and the API is subject to change (although no major changes are expected as of this writing).
Querying a FTS index using the .NET SDK is performed through the Query(SearchQuery query) method on the CouchbaseBucket class. This method returns a ISearchQueryResult that when enumerated yields the results of the query (in the form of ISearchQueryRow objects). Additionally, you can access the rows via the Hits property, which returns list containing all rows returned. Other important ISearchQueryResult properties include:
  • Status: a SearchStatus value indicating the result of the query - Success or Failed.
  • Errors: a list of any errors that may have occurred
  • Facets: a list of SearchFacet objects if any were returned
The ISearchQueryRow interface is implemented as a SearchQueryRow object and contains the Index, Id and Score properties, respectively identifying the exact FTS index that returned the hit, the id of the document that matched and a score for the match. It also contains optional properties depending on the request and the availability of all relevant settings in the FTS mapping. Those are:
  • Explanation: an explanation of the plan followed by the FTS index to execute the query as a dynamic Type.
  • Locations: a map-like listing of the location of all matching terms inside each relevant field that was queried as a dynamic Type.
  • Fragments: a map-like listing of occurrences of the search terms in each field, with the context of the terms.
  • Fields: a map of the complete value of each requested field). Most of these need that the index be configured to store the data of a searched field

Here is an example of a very simple example using a MatchQuery, which is a very generic Full Text Search that will search within the text of the fields that were indexed:

Querying and FTS index
ClusterHelper.Initialize(new ClientConfiguration());
var bucket = ClusterHelper.GetBucket("travel-sample");
var results = bucket.Query(new SearchQuery
{
    Index = "idx_travel_content",
    Query = new MatchQuery("inn"),
    SearchParams = new SearchParams().Limit(10).Timeout(TimeSpan.FromMilliseconds(10000))
});

foreach (var result in results)
{
    Console.WriteLine(result);
}

First we open a CouchbaseBucket, in this case we are opening the "travel-sample" bucket which comes is a sample bucket and dataset that comes pre-installed with Couchbase server (but must be configured via the Management Console). In the bucket, using the Management Console, we have created an index named "idx_travel_content" which will index on the "content" field of the "landmark" document type.

We then create a high-level SearchQuery object with our parameters to apply to the entire request. A SearchQuery can be composed of one or more queries, thus the parameters on the SearchQuery apply to all queries within that instance. Here are some of the more important parameters:
  • Limit: limits the number of matching results from a returned result-set by "n".
  • Skip: indicates how many matching results to skip on the result set before returning matches.
  • Explain: if true, the response will include additional search score explanations.
  • Highlighting: allows setting of additional highlighting on the result set of matching terms.
  • Fields: a list of fields values that should be returned in the result assuming that they were indexed.
  • Facets: a list of facets used to aggregate information collected on a particluar result set.
  • Timeout: a server side timeout allows to specify an upper boundary of request execution so that it potentially doesn't run infinitely.
The SearchQuery is a "fluent" interface, so you can chain method calls togather making it a bit easier to see which options you have available using IntelliSense in Visual Studio. The index we defined above "idx_travel_content" is assigned to the Index property and the MatchQuery is defined, which will search for the letters "inn" in the "content" field of every "landmark" document in the "travel-sample" bucket.

We then call the CouchbaseBucket.Query(SearchQuery query) method and iterate over the ISearchQueryResult object which will gives the results of the query.