A newer version of this documentation is available.

View Latest

N1QL Queries Using the Go SDK with Couchbase Server

Simple Queries

You can issue N1QL queries by first creating a N1qlQuery via gocb.NewN1qlQuery(), and submitting the query to Bucket.ExecuteN1qlQuery

The following example shows how to send a simple N1QL query:

myQuery := gocb.NewN1qlQuery("SELECT * FROM default")
rows, err := myBucket.ExecuteN1qlQuery(myQuery, nil)
var row interface{}
for rows.Next(&row) {
        fmt.Printf("Row: %+v\n", row)
if err = rows.Close(); err != nil {
        fmt.Printf("Couldn't get all the rows: %s\n", err);

The returned value (QueryResults) may be iterated over using the QueryResults.Next() method, which may be passed a pointer to an object which may be converted from each row. You may use an empty interface or a custom object containing JSON tags. Note that the JSON fields in the row are controlled by the query string itself: See https://github.com/couchbaselabs/devguide-examples/blob/server-4.5/go/query-marshalling-rest.go for an example of using typed query rows.

Querying with Placeholders

You can use N1QL placeholders in the query. Placeholders allow you to specify variable constraints for an otherwise constant query. To use placeholders, insert the placeholders themselves in the query string - these may be positional (e.g. $1, $2, etc.) or named (e.g. $age, $lname, etc). A named or positional parameter is a placeholder for a value in the WHERE, LIMIT or OFFSET clause of a query. To set the value for the placeholders, construct an object of an appropriate type and pass it as the second argument to the ExecuteN1qlQuery() method:

  • For positional placeholders, pass an array. $1 refers to the the first array element, and so on.

  • For named placeholders, pass a Map. The Map keys should match up to the named placeholders, without the sigil ($). To specify a value for the $age placeholder, the Map should contain a value for age.

Note that placeholder values may be anything JSON serializable - meaning things such as Maps and arrays are accepted.

myQuery := gocb.NewN1qlQuery("SELECT airportname, city, country FROM `travel-sample` " +
        "WHERE type='airport' AND city=$1 ")
myParams = append(myParams, []interface{}{"Reno"})
rows, err := bucket.ExecuteN1qlQuery(myQuery, myParams)

Query Options

You may configure the N1qlQuery object with various options to control query behavior. These options may be configured using various setter/getting methods

  • N1qlQuery.Adhoc() controls whether the query will be prepared.

  • N1qlQuery.Timeout() allows you to set the per-query timeout. This is useful for long-running queries

  • N1qlQuery.Consistency() allows you to modify the query index consistency.


Index Creation

In order to query a bucket, it must have an index defined. You can create indexes using raw N1QL statements (e.g. CREATE INDEX) or via the Go SDK’s cluster management interface