N1QL

N1QL is a declarative query language designed for querying JSON data stored in Couchbase Server. It combines familiar SQL-like syntax with extensions tailored to JSON, enabling data retrieval, modification, and aggregation within a single language. N1QL is often described as SQL for JSON and is the primary query language for Couchbase’s data platform. It supports SELECT, INSERT, UPDATE, DELETE, and UPSERT operations.

N1QL queries are executed against buckets in Couchbase, with optional scopes and collections in newer versions. The language uses standard SQL constructs such as SELECT, FROM, WHERE, GROUP BY, ORDER BY, and LIMIT, augmented by JSON-specific features. Path expressions allow access to nested fields, arrays, and subdocuments. Special operators like UNNEST and NEST enable traversal of arrays and nested objects, while JOINs allow relationships to be expressed across documents.

Query planning and performance rely on indexes. Primary indexes enable arbitrary queries, but performance often requires Global Secondary Indexes (GSI) or other index types. Indexes can be created on document fields or expressions, and covering indexes can satisfy queries without touching data. The EXPLAIN plan helps understand optimization, and the query engine supports profiling and prepared statements.

N1QL integrates with Couchbase components such as the query service, the index service, and consistency settings. It is used for operational queries, data discovery, and lightweight analytics on JSON datasets.

Example: SELECT name, email FROM `travel-sample` WHERE country = "France"; Another example: SELECT u.name, f.city FROM `users` AS u UNNEST u.friends AS f WHERE f.city = "Paris";