Run Your First N1QL Query

N1QL (pronounced "nickel") is the Couchbase Server query language.

About N1QL

N1QL embraces the JSON document model and uses SQL-like syntax.
In N1QL, you operate on JSON documents, and the result of your operation is another JSON document.
N1QL queries can be run from the command line, using the cbq tool; or by means of the Query Workbench, provided by the Couchbase Web Console.

A basic N1QL query has the following parts:

SELECT — The fields of each document to return.

FROM — The data bucket in which to look.

WHERE — The conditions that the document must satisfy.

Here’s an example of a basic N1QL query and the JSON document it returns.
The query asks for the country associated with the airline Excel Airways — note that for all identifiers (bucket names) that contain a hyphen character, you need to enclose the name with backtick (`) characters:

This displays the cbq shell prompt, against which you can enter N1QL commands, specifying your currently installed buckets.
For example, the following query returns the different values used by documents in the travel-sample bucket for the callsign field, limiting the number of results to 5:

The result thus contains five callsign-values.
A callsign is associated with an airline; and airline is one of the document-types that the travel-sample bucket contains.
Others are airport and hotel.
You can search on a type: for example, the following query returns a maximum of one airport document, and lists all the fields it contains.

Try the Query Workbench

The Couchbase Web Console provides a Query Workbench, at which you can compose and execute N1QL queries.
Left-click on the Query tab, located on the horizontal control-bar, near the top of the Couchbase Web Console:

This brings up the Query Workbench.

The workbench has three principal areas, which are:

An upper Query Editor panel, which is where you will type your N1QL query.

A Bucket Insights panel, at the right.
This provides information on the buckets currently maintained by your system.
Right now, it shows that just one exists; the bucket travel-sample.

A Query Results panel, at the bottom-left.
This shows query-results; and provides a number of options for their display.
To start with, you will use the default option, which is selectable by the JSON button, and duly displays results in JSON-format.

You can now use the Query Workbench to enter a N1QL query.
In the upper panel, enter the following:

To execute your query, left-click on the Execute button, at the upper-left:

Query-results now appear in the Results panel:

As you can see, a single document was found to match your specified criterion: which was the document whose name value is 40-Mile Air (which is, in fact, the document you took an initial look at, during the previous stage of the Getting Started sequence).

Next

In the final stage of this Getting Started sequence, Choose Your Next Steps suggestions are provided as to locations you can visit next.

Other Destinations

In addition to following this brief tutorial, you can learn more about N1QL by looking at these in-depth resources:

The online interactive tutorial allows you to learn about N1QL without having Couchbase Server installed in your own environment.
It’s a self-contained tutorial that runs in a web browser and lets you modify the sample queries.
The tutorial covers SELECT statements in detail, including examples of JOIN, NEST, GROUP BY, and other typical clauses.

The N1QL cheat sheet provides a concise summary of the basic syntax elements.
Print it out and keep it on your desk where it’ll be handy for quick reference.