Learn N1QL with Real Code Examples

N1QL brings the power of SQL to JSON documents inside Couchbase.

Supports SELECT, JOIN, WHERE, GROUP BY, and complex expressions on semi-structured data.

Used for real-time applications, high-performance caching, and scalable NoSQL analytics.

SELECT, INSERT, UPDATE, DELETE

JOIN support across JSON documents

Index creation (primary, secondary, GSI)

Subqueries and nested queries

Array indexing and search predicates

Buckets, Scopes, and Collections

JSON document modeling

Primary and secondary indexes

SELECT and WHERE for filtering

JOINs on document keys

Array indexing for nested data

Bucket -> Scope -> Collections

Index definitions for each collection

Analytics datasets

FTS indexes

Eventing functions for triggers

Model data in JSON documents

Create required primary/secondary indexes

Run N1QL queries to manipulate and read data

Optimize queries using EXPLAIN

Integrate with SDK (Node, Java, Python, etc.)

Beginner: Basic SELECT queries

Intermediate: Joins and subqueries

Advanced: Array indexing and complex predicates

Expert: Distributed performance tuning across clusters

More powerful JOIN support than MongoDB MQL

More SQL-like than Cassandra CQL

Better indexing flexibility than DynamoDB

More scalable than relational SQL databases

2015 – N1QL GA release

2017 – Advanced JOIN + Index enhancements

2019 – Couchbase 6.x performance upgrades

2021 – N1QL for Analytics introduced

2023–2025 – Improvements in indexing, clustering, Capella cloud

Bucket: Top-level data container

Scope: Logical grouping inside bucket

Collection: Stores JSON documents

UNNEST: Flattens array field for filtering

GSI: Global Secondary Index