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:

    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 the cluster, the IP address can be any node in the cluster as cbq will automatically discover the query nodes:

      ./cbq -engine=http://123.45.67.89:8091
    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:8091/"

    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:8091/"

    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:8091/"
    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

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