A newer version of this documentation is available.

View Latest

Running N1QL queries from a command line

Couchbase Server provides a tool called cbq that enables you to run N1QL queries from a command line.

To run cbq:

  1. Log in to a Couchbase Server node that has the query service enabled.

  2. Open a command window.

  3. Change to the Couchbase tools directory.

    # On Linux systems:
    $ cd /opt/couchbase/bin
    # On OS X systems:
    $ cd /Applications/Couchbase\ Server.app/Contents/Resources/couchbase-core/bin
  4. Run the following command to connect to the local query node and start the interactive query shell:

    $ ./cbq

    Run the following command to connect to a query node at and port 8093:

    ./cbq -engine=
  5. At the cbq prompt, enter a N1QL query and end the query with a semicolon. Press return to execute the query. For example:

    cbq> create primary index on `beer-sample`;
        "requestID": "fd4086fa-9ed0-465d-9a99-422c5d8e9506",
        "signature": null,
        "results": [
        "status": "success",
        "metrics": {
            "elapsedTime": "598.972353ms",
            "executionTime": "598.936382ms",
            "resultCount": 0,
            "resultSize": 0
    cbq> select * from `beer-sample` limit 1;
        "requestID": "b9f6490d-91c6-4a18-b0b9-a2345cb58b88",
        "signature": {
            "*": "*"
        "results": [
                "beer-sample": {
                    "abv": 5,
                    "brewery_id": "21st_amendment_brewery_cafe",
                    "category": "North American Ale",
                    "description": "Light golden color. Sweet dry aroma with crisp, clear bitterness. Brewed with imported German hops.The perfect beer to have when you'd like to have more than one.",
                    "ibu": 0,
                    "name": "South Park Blonde",
                    "srm": 0,
                    "style": "Golden or Blonde Ale",
                    "type": "beer",
                    "upc": 0,
                    "updated": "2010-07-22 20:00:20"
        "status": "success",
        "metrics": {
            "elapsedTime": "24.994186ms",
            "executionTime": "24.936945ms",
            "resultCount": 1,
            "resultSize": 641

Accessing a Secure Bucket

If your bucket has a password, you need to pass the bucket name and bucket password like so:

./cbq -engine="http://<bucketname>:<bucketpassword>@"

For the 'beer-sample' bucket, if you add a password to it of w1fg2Uhj89 (as by default it has none), the command to start cbq would look like this:

./cbq -engine="http://beer-sample:w1fg2Uhj89@"

If you want to access all of the buckets in the same cbq session, you would pass in the Administrator username and password instead of the bucket level.

./cbq -engine="http://Administrator:password@"
These commands execute successfully only if you have loaded sample bucket 'beer-sample' either at install or from the Settings menu in the web UI.

Exiting cbq

Type Ctrl-D to exit cbq.