A newer version of this documentation is available.

View Latest

Searching with the REST API (cURL/HTTP)

      Full Text Search can be performed using the Couchbase REST API (cURL/HTTP), at the command-line, through the curl utility.

      Performing a Full Text Search with REST at the Command-Line

      The syntactic elements for a curl-based Full Text Search can be obtained from the Couchbase Web Console. The console allows searches performed via the UI to be translated dynamically into curl examples.

      To demonstrate this, follow the procedures for accessing the Full Text Search screen, within the Couchbase Web Console, and for performing a simple search; as described in Searching from the UI. Then, left-click on the show advanced query settings checkbox, at the right-hand side of the Search button:

      fts advanced query settings

      The JSON for Query Request panel displays the submitted query in JSON format. Note the show command-line curl example checkbox. Selecting this checkbox adds to the content of the initial JSON display to form a completed curl command:

      fts ui curl example

      This example can be copied by means of the Copy to Clipboard button, pasted into (for example) a standard console-window, and executed against the prompt. This feature , therefore, provides a useful means of extending experiments initially performed with the UI into a subsequent console-based, script-based, or program-based context. Note, however, that authentication is required for the call to be successful from any context outside the current Couchbase Web Console session. Additionally, familiarity with query strings should be acquired for the creation of more complex queries.

      Query Strings and Authentication

      A Query String combines standard alphanumeric characters with syntactic elements in order to specify complex queries in ASCII form. Query Strings can be used for Full Text Searches performed with both the Couchbase Web Console and the REST API. A detailed description of Query String-format is provided in Supported Queries.

      For example, to search for instances of both nice and view, specify "+nice +view" in a search from the Couchbase Web Console:

      fts query string query at ui

      When the search has returned, check in succession the show advanced query settings and show command-line curl example checkboxes. The JSON for Query Request now displays the following:

      fts query string results at ui

      Copy the curl command displayed by left-clicking on the Copy to Clipboard button. Before attempting to execute the command from the command-line, paste it into a text-editor, and add appropriate authentication-credentials. For example:

      curl -u username:password -XPOST -H "Content-Type: application/json" \
      http://localhost:8094/api/index/travel-sample-index/query \
      -d '{
        "explain": true,
        "fields": [
        "highlight": {},
        "query": {
          "query": "{ \"+nice +view\" }"

      (For detailed information on Couchbase Server Role-Based Access Control, see Authorization.)

      The code can now be copied again and pasted against the command-line, and executed, with the result-set appearing as standard output.

      For additional assistance on Query String composition, left-click on the full text query syntax help link that appears under the Search interactive text-field when show advanced query settings is checked:

      fts query syntax help link

      This link provides access to a page of information on Query String Full Text Search queries.

      Searching Specifically

      Searches should always be as specific as possible: this helps to avoid excessive resource-consumption, and the retrieval of unnecessarily large amounts of data. To facilitate this, the number of clauses that can be returned by a Search Service query is deliberately capped at 1024: if a larger number of clauses is to be returned by a query, an error is thrown.

      For example, the following query attempts to use the wildcard *, to return all data from documents' reviews.content field. The output is piped to the jq program, to enhance readability:

      curl -u username:password -X POST \
      -H "Content-Type: application/json" \
      http://localhost:8094/api/index/travel-sample-index/query \
      -d '{
        "explain": true,
        "fields": [
        "highlight": {},
        "query": {
          "wildcard": "*",
          "field": "reviews.content"
      }' | jq '.'

      Due to the excessive number of clauses that this query would return, an error is thrown. The initial part of the error-output is as follows:

        "status": {
          "total": 6,
          "failed": 6,
          "successful": 0,
          "errors": {
            "travel-sample-index_666185f510578977_13aa53f3": "TooManyClauses[8550 > maxClauseCount, which is set to 1024]",
            "travel-sample-index_666185f510578977_18572d87": "TooManyClauses[8731 > maxClauseCount, which is set to 1024]",
            "travel-sample-index_666185f510578977_54820232": "TooManyClauses[8130 > maxClauseCount, which is set to 1024]",
            "travel-sample-index_666185f510578977_6ddbfb54": "TooManyClauses[8694 > maxClauseCount, which is set to 1024]",
            "travel-sample-index_666185f510578977_aa574717": "TooManyClauses[8731 > maxClauseCount, which is set to 1024]",
            "travel-sample-index_666185f510578977_f4e0a48a": "TooManyClauses[8450 > maxClauseCount, which is set to 1024]"

      Therefore, to fix the problem, the wildcard match should be more precisely specified, and the query re-attempted.

      Further REST Examples

      Further examples of using the REST API to conduct Full Text Searches can be found in Supported Queries.

      The full range of features for Full Text Search, as supported by the Couchbase REST API, is documented as part of the REST API’s reference information on the page Full Text Search API.