Searching with the REST API

Full Text Search can be performed by means of the Couchbase REST API.

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

Full Text Search can be performed with the Couchbase REST API; at the command-line, by means of the curl utility.

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, which when checked, 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 Query Types.

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 Administrator: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 again copied, 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 page of information on Query String Full Text Search queries.

To search securely, specify port 18094. For example:

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

For additional information on secure communication with Couchbase Server, see Encryption on the Wire.

Further REST Examples

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

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.