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.

Of course you need an existing index refer to either Classic Editor or Creating a Geospatial Index (type geopoint) to create an index named something like travel-sample-index or test_geopoint either index will work either index will work (the latter will also have the ability to search against geopoints).

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:

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:

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:

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:

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 -XPOST -H "Content-Type: application/json" \
-u <username>:<password> http://localhost:8094/api/index/test_geopoint/query \
-d '{
  "explain": true,
  "fields": [
    "*"
  ],
  "highlight": {},
  "query": {
    "query": "{+nice +view}"
  },
  "size": 10,
  "from": 0
}'

(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:

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 -XPOST -H "Content-Type: application/json" \
-u <username>:<password> http://localhost:8094/api/index/test_geopoint/query \
-d '{
  "explain": true,
  "fields": [
    "*"
  ],
  "highlight": {},
  "query": {
    "wildcard": "aa*",
    "field": "reviews.content"
  },
  "size": 10,
  "from": 0
}' | jq '.'

Due to the excessive number of clauses that this query would return, an error is thrown. The error-output (along with the request parameters) is as follows:

{
  "error": "rest_index: Query, indexName: test_geopoint, err: TooManyClauses over field: `reviews.content` [21579 > maxClauseCount, which is set to 1024]",
  "request": {
    "explain": true,
    "fields": [
      "*"
    ],
    "from": 0,
    "highlight": {},
    "query": {
      "field": "reviews.content",
      "wildcard": "*"
    },
    "size": 10
  },
  "status": "fail"
}

Therefore, to fix the problem, the wildcard match should be more precisely specified, and the query re-attempted. For example adjusting the wildcard specification to "aa*" will result in a query that succeeds.

curl -XPOST -H "Content-Type: application/json" \
-u <username>:<password> http://localhost:8094/api/index/test_geopoint/query \
-d '{
  "explain": true,
  "fields": [
    "*"
  ],
  "highlight": {},
  "query": {
    "wildcard": "aa*",
    "field": "reviews.content"
  },
  "size": 10,
  "from": 0
}' | jq '.'

Further REST Examples

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

List of REST Features Supporting Full Text Search

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.