Running N1QL Queries from a Command Line

Running N1QL Queries from a Command Line

cbq is the command line shell that you can use to issue N1QL queries on Couchbase Server.

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\
  4. Run the following command to connect to the local query node and start the interactive query shell:
    $ ./cbq
    Note: Run the following command to connect to the cluster, the IP address can be any node in the cluster as cbq will automatically discover the query nodes:
    ./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@"
Note: 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.

Keyboard Shortcuts for cbq

The following table lists the keyboard shortcuts for N1QL commands. These shortcuts are similar to those used in the Emacs text editor.

Table 1. Shortcut Keys for cbq Shell
Keystroke Action
Ctrl-A, Home Move cursor to beginning of line
Ctrl-E, End Move cursor to end of line
Ctrl-B, Left Move cursor one character left
Ctrl-F, Right Move cursor one character right
Ctrl-Left Move cursor to previous word
Ctrl-Right Move cursor to next word
Ctrl-D, Del (if line is not empty) Delete character under cursor
Ctrl-D (if line is empty) End of File - usually quits application
Ctrl-C Reset input (create new empty prompt)
Ctrl-L Clear screen (line is unmodified)
Ctrl-T Transpose previous character with current character
Ctrl-H, BackSpace Delete character before cursor
Ctrl-W Delete word leading up to cursor
Ctrl-K Delete from cursor to end of line
Ctrl-U Delete from start of line to cursor
Ctrl-P, Up Previous match from history
Ctrl-N, Down Next match from history
Ctrl-R Reverse Search history (Ctrl-S forward, Ctrl-G cancel)
Ctrl-Y Paste from Yank buffer (Alt-Y to paste next yank instead)
Tab Next completion
Shift-Tab (after Tab) Previous completion