PREPARE

PREPARE statement

prepare:

 PREPARE [ name ( FROM | AS ) ] statement

The PREPARE statement prepares a query. A name can optionally be specified. A JSON array is returned that contains one result that has the properties:

  • name: If present, this will be the name given to the PREPARE statement. If not, a name is generated.

  • operator: the execution plan of the statement being prepared.

  • signature: the signature of the statement being prepared.

  • text: the full PREPARE statement text.

  • encoded_plan: the full prepared statement in encoded format. The encoded plan can be included in addition to the prepared parameter in a request to execute a prepared statement. If the name given by the prepared parameter is unrecognized, the query engine will decode and execute the prepared statement given by the encoded_plan parameter. The decoded prepared statement will be saved by the query engine so the next request that uses its name will succeed.

Repeatedly preparing a statement with the same name will result in the statement being overwritten. A PREPARE statement that uses a name that was used for a different statement will result in a duplicate name error.

Prepared statements are stored in memory until you restart the Couchbase Server. After restarting the server, you must prepare the statements again before you can execute the prepared statements.

For information on how to use prepared statements with various SDKs, refer to java-sdk::n1ql-query.adoc#prepare-stmts and nodejs-sdk::n1ql-queries-with-sdk.adoc.

RBAC Privileges

User executing the PREPARE statement must have the privileges of the statement being prepared. For more details about user roles, see Authorization.

For example,

To execute the following statement, user must have the Query Select privilege on both keyspaces `travel-sample` and `beer-sample`.

PREPARE SELECT * FROM `travel-sample`
WHERE city = (SELECT RAW city FROM `beer-sample`)

To execute the following statement, user must have the Query Update and Query Select privileges on `travel-sample`.

PREPARE UPDATE `travel-sample`
SET city = "San Francisco" WHERE lower(city) = "sanfrancisco"
RETURNING *

EXECUTE statement

For details, see EXECUTE.