A newer version of this documentation is available.

View Latest

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 on the local host:

    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.

      • Linux

      • macOS

      • Microsoft Windows

      $ cd /opt/couchbase/bin
      $ cd /Applications/Couchbase\ Server.app/Contents/Resources/couchbase-core/bin
      > cd C:\Program Files\Couchbase\Server\bin
    4. Run the following command to connect to the local query node and start the interactive query shell:

      • Linux / macOS

      • Microsoft Windows

      $ ./cbq
      > cbq

      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 can 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.

    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


    Move cursor to previous word


    Move cursor to next word

    Ctrl+D, Del

    (if line is not empty) Delete character under cursor


    (if line is empty) End of File - usually quits application


    Reset input (create new empty prompt)


    Clear screen (line is unmodified)


    Transpose previous character with current character

    Ctrl+H, BackSpace

    Delete character before cursor


    Delete word leading up to cursor


    Delete from cursor to end of line


    Delete from start of line to cursor

    Ctrl+P, Up

    Previous match from history

    Ctrl+N, Down

    Next match from history


    Reverse Search history (Ctrl+S forward, Ctrl+G cancel)


    Paste from Yank buffer (Alt+Y to paste next yank instead)


    Next completion


    (after Tab) Previous completion

    Source: https://github.com/peterh/liner