This article was originally published on AI Study Room. For the full version with working code examples and related articles, visit the original post.
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase Guide: N1QL, Document Model, Clustering, and Caching
Couchbase is a distributed NoSQL document database that combines the flexibility of JSON documents with the query power of SQL. Its key differentiator is the integrated caching layer that automatically keeps frequently accessed data in memory.
Document Data Model
Couchbase stores data as JSON documents, organized into buckets (analogous to databases). Each document has a unique key and can contain arbitrarily nested JSON:
{
"type": "user",
"user_id": "alice_42",
"email": "alice@example.com",
"name": "Alice Smith",
"addresses": [
{"type": "home", "city": "New York", "zip": "10001"},
{"type": "work", "city": "San Francisco", "zip": "94105"}
],
"preferences": {
"theme": "dark",
"notifications": true
},
"created_at": "2026-05-12T10:00:00Z"
}
Key Operations
from couchbase.cluster import Cluster
from couchbase.options import ClusterOptions
from couchbase.auth import PasswordAuthenticator
cluster = Cluster('couchbase://localhost', ClusterOptions(
PasswordAuthenticator('admin', 'password')
))
bucket = cluster.bucket('myapp')
collection = bucket.default_collection()
Create/Update
collection.upsert('user_alice_42', {
'type': 'user',
'email': 'alice@example.com',
'name': 'Alice Smith'
})
Read
result = collection.get('user_alice_42')
user = result.content_as[dict]
CAS (Compare-And-Swap) for optimistic locking
result = collection.get('user_alice_42')
cas = result.cas
user = result.content_as[dict]
user['name'] = 'Alice Jones'
collection.replace('user_alice_42', user, cas=cas)
N1QL (SQL for JSON)
N1QL (pronounced "nickel") brings SQL semantics to JSON documents. It is Couchbase's most powerful feature: you get the flexibility of a document database with the query power of SQL.
Basic Queries
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\-- SELECT with WHERE
SELECT name, email
FROM myapp
WHERE type = 'user' AND email LIKE '%@example.com'
ORDER BY name
LIMIT 10;
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\-- JOIN across document types
SELECT u.name, o.total, o.created_at
FROM myapp u
JOIN myapp o ON KEYS ARRAY s.order_id FOR s IN u.orders END
WHERE u.type = 'user' AND u.user_id = 'alice_42';
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\-- UNNEST (flatten arrays)
SELECT u.name, addr.city, addr.zip
FROM myapp u
UNNEST u.addresses addr
WHERE u.type = 'user' AND addr.type = 'home';
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\-- Aggregation
SELECT addr.city, COUNT(*) AS user_count
FROM myapp u
UNNEST u.addresses addr
WHERE u.type = 'user'
GROUP BY addr.city
ORDER BY user_count DESC;
Secondary Indexes
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\-- Create primary index (required for N1QL queries on a bucket)
CREATE PRIMARY INDEX idx_primary ON myapp;
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
Read the full article on AI Study Room for complete code examples, comparison tables, and related resources.
Found this useful? Check out more developer guides and tool comparisons on AI Study Room.
Top comments (0)