A newer version of this documentation is available.

N1QL Language Reference

concept

March 23, 2025

+ 12

The N1QL reference guide describes the N1QL language structure and syntax. It provides reference information about the basic elements in N1QL which can be combined to build N1QL statements.

N1QL Language Structure

The N1QL language structure is composed of statements, expressions, and comments.

Statements

N1QL statements are categorized into the following groups:

Data Definition Language (DDL) statements to create indexes, modify indexes, and drop indexes.
Data Manipulation Language (DML) statements to select, insert, update, delete, and upsert data into JSON documents.

Expressions

The following are the different types of N1QL expressions:

Comments

N1QL supports block comments and line comments.

Block Comments

/*  [ [text] | [newline] ]+  */

A block comment starts with /* and ends with */. The query engine ignores the start and end markers /* */, and any text between them.

A block comment may start on a new line, or in the middle of a line after other N1QL statements. A block comment may contain line breaks.

There may also be further N1QL statements on the same line after the end of a block comment — the query engine does not ignore these.

Line Comments

-- [text]

You can use line comments in Couchbase Server 6.5 and later. A line comment starts with two hyphens --. The query engine ignores the two hyphens, and any text following them up to the end of the line.

A line comment may start on a new line, or in the middle of a line after other N1QL statements. A line comment may not contain line breaks.

Nested Path Expressions

In N1QL, nested paths indicate an expression to access nested sub-documents within a JSON document or expression.

For example, the latitude of a location in the airport keyspace is in the geo sub-document, and can be addressed as the nested path geo.lat:

n1ql
Copy
SELECT airportname, city, geo, ROUND(geo.lat) AS latitude
FROM `travel-sample`.inventory.airport t1
LIMIT 1;

json
Copy
[
  {
    "airportname": "Calais Dunkerque",
    "city": "Calais",
    "geo": {
      "alt": 12,
      "lat": 50.962097,
      "lon": 1.954764
    }
    "latitude": 51,
  }
]

You can use nested operators to access sub-document fields within a document.