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 123.45.67.89 and port 8093:

    ./cbq -engine=http://123.45.67.89:8093
  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`;
    Result
    {
        "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;
    Results
    {
        "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>@123.45.67.89:8093/"

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@123.45.67.89:8093/"

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@123.45.67.89:8093/"
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.