EXECUTE

The EXECUTE statement executes a prepared statement.

Syntax

execute ::= EXECUTE name
execute ::= 'EXECUTE' name
name

The name of the prepared statement. This may be a UUID that was assigned automatically, or a name that was user-specified when the statement was created.

An error is returned if the name does not identify a prepared statement.

If the name of the prepared statement contains hyphens, wrap the entire name in backticks (`) or double quotation marks (").

Usage

You can execute a prepared statement in three ways:

  • Using the EXECUTE statement in the Query Workbench.

  • Using the EXECUTE statement in the the cbq command line shell.

  • Using the Query REST API (/query/service endpoint).

All of these methods require you to specify the name of the prepared statement. With the last method, you can also include the encoded plan.

If the name of the prepared statement is unrecognized, the query engine will decode and execute the prepared statement given by the encoded plan. The decoded prepared statement will be saved by the query engine so the next request that uses its name will succeed.

When specified, the encoded plan should be the result of a prepared statement. An error is returned if the encoded plan cannot be converted to a valid plan.

Examples

Example 1. Executing a prepared statement in N1QL

The following example shows how to execute a prepared statement in N1QL.

Request
EXECUTE `[127.0.0.1:8091]24734829-c793-4b90-b8bd-74ff788be493`;
Example 2. Executing a prepared statement without a name using the REST API

The following example shows how to prepare the statement without specifying a name.

Request
$ curl -v http://localhost:8093/query/service -d 'statement=PREPARE SELECT text FROM tweets WHERE rating > $r AND created_at > $date'
Response
< HTTP/1.1 200 OK
{
  "requestID": "a339a496-7ed5-4625-9c64-0d7bf584a1bd",
  "signature": "json",
  "results": [
  {  "encoded_plan": "H4sIAAAJbogA/5yRQU/6QBDFvwpZ/gdIIAAA==",
    "name": "a1355198-2576-4e3d-af04-5acc77d8a681",
     "operator": {
            "#operator": "Sequence",
            "~children": [
            // Content redacted
            ]
            },
     "signature": {
     "text": "json"
  },
  "text": "PREPARE SELECT text FROM tweets WHERE rating > $r AND created_at > $date"
  }
  ],
  "status": "success",
  "metrics": {
  "elapsedTime": "1.970679ms",
  "executionTime": "1.889351ms",
  "resultCount": 1,
  "resultSize": 2261
 }
}

The following example uses the server-generated name of the prepared statement to execute the statement.

Request:
$ curl -v http://localhost:8093/query/service -d 'prepared="a1355198-2576-4e3d-af04-5acc77d8a681"&$r=9.5&$date="1-1-2014"'
Response:
< HTTP/1.1 200 OK
{
 "requestID": "1bd9956b-bc8e-478a-bd84-3955fe2db047",
 "signature": {
 "text": "json"
 },
 "results": [
 {
  "text": "Couchbase is my favorite database"
 }
 ],
 "status": "success",
 "metrics": {
 "elapsedTime": "1.527795ms",
 "executionTime": "1.443748ms",
 "resultCount": 0,
 "resultSize": 0
 }
}
Example 3. Executing a prepared statement with a name using the REST API

The following example specifies a name for the prepared statement.

Request:
$ curl -v http://localhost:8093/query/service -d 'statement=PREPARE fave_tweets FROM SELECT text FROM tweets WHERE rating >= $r'
Response:
< HTTP/1.1 200 OK
 {
        "requestID": "a339a496-7ed5-4625-9c64-0d7bf584a1bd",
        "signature": "json",
        "results": [
        {   "encoded_plan": "H4sIAAAJbogA/5yRQU/6QBDFvwpZ/gdIIAAA==",
        "name": "fave_tweets",
        "operator": {
        // and so on
        ...

The following example uses the name specified in the example above to run the prepared statement.

Request:
$ curl -v http://localhost:8093/query/service -d 'prepared="fave_tweets"&$r=9.5'
Response
< HTTP/1.1 200 OK
{
 "requestID": "1bd9956b-bc8e-478a-bd84-3955fe2db047",
 "signature": {
 "text": "json"
 },
 "results": [
 {
   "text": "Couchbase is my favorite database"
  }
  ],
 "status": "success",
 "metrics": {
 "elapsedTime": "1.527795ms",
 "executionTime": "1.443748ms",
 "resultCount": 0,
 "resultSize": 0
 }
 }
Example 4. Executing a prepared statement with the encoded plan using the REST API

The following example specifies a name for the prepared statement and the response includes an encoded_plan.

Request:
$ curl -v http://localhost:8093/query/service -d 'statement=PREPARE fave_tweets FROM SELECT text FROM tweets WHERE rating >= $r'
Response
< HTTP/1.1 200 OK
{
  "requestID": "a339a496-7ed5-4625-9c64-0d7bf584a1bd",
  "signature": "json",
  "results": [
  {   "encoded_plan": "H4sIAAAJbogA/5yRQU/6QBDFvwpZ/gdIIAAA==",
        "name": "fave_tweets",
        "operator": {
        // and so on
        ...

The following example uses the name and encoded_plan from the example above to run the prepared statement.

Request
$ curl -v http://localhost:8093/query/service -H "Content-Type: application/json" -d '{ "prepared":"fave_tweets", "encoded_plan":"H4sIAAAJbogA/5yRQU/6QBDFvwpZ/gdIIAAA==", "$r":9.5 }'
Response
< HTTP/1.1 200 OK
{
 "requestID": "1bd9956b-bc8e-478a-bd84-3955fe2db047",
 "signature": {
 "text": "json"
 },
 "results": [
  {
   "text": "Couchbase is my favorite database"
   }
   ],
  "status": "success",
  "metrics": {
  "elapsedTime": "1.527795ms",
  "executionTime": "1.443748ms",
  "resultCount": 0,
  "resultSize": 0
   }
 }
  • For information on preparing a statement for execution, refer to PREPARE.