---
name: couchbase
description: Expert Couchbase NoSQL assistance covering N1QL/SQL++ queries, memory-first caching, document scopes, and cross-datacenter replication (XDCR). Use when building ultra-low latency JSON document platforms.
---

# Couchbase

Couchbase works as a Key-Value store (managed memory cache) + Document Database. It is famous for its "memory-first" architecture and N1QL (SQL for JSON).

## When to Use

- **Memory-First NoSQL Document Store**: Applications requiring sub-millisecond document lookups powered by an integrated managed memory cache.
- **SQL for JSON (N1QL / SQL++)**: Querying JSON documents using familiar SQL syntax with joins, nested arrays, and subqueries.
- **Distributed Key-Value + Full-Text Search**: Unifying key-value caching, document storage, and vector/full-text search in a single cluster.
- **Mobile Edge Data Sync (Couchbase Lite)**: Synchronizing embedded mobile database instances with cloud clusters using Sync Gateway.

## Quick Start

```sql
-- N1QL Query
SELECT u.name, ARRAY_AGG(o.item) as orders
FROM `travel-sample`.inventory.users u
JOIN `travel-sample`.inventory.orders o ON u.id = o.user_id
WHERE u.city = "Paris"
GROUP BY u.name;
```

## Core Concepts

### Memory-First VBucket Architecture

Documents are mapped across 1024 virtual buckets (vBuckets), cached directly in RAM before being asynchronously written to disk:

```text
[ Application Client ] ──Sub-Millisecond Read/Write──→ [ Managed Memory Cache (RAM) ]
                                                                 │ (Async Flush)
                                                                 ▼
                                                        [ Append-Only Disk Storage ]
```

### SQL++ (N1QL) Declarative JSON Queries

Executes full SQL expressions over schemaless JSON structures:

```sql
-- Query nested JSON orders in Couchbase SQL++
SELECT
  meta().id AS orderId,
  customer.email,
  ARRAY_SUM(items[*].price) AS totalAmount
FROM `commerce`.`orders` AS o
WHERE status = 'PAID'
  AND ANY item IN items SATISFIES item.category = 'Electronics' END
ORDER BY totalAmount DESC
LIMIT 20;
```

### Scopes and Collections Multi-Tenancy

Organizes documents into logical namespaces mimicking relational databases:

```text
[ Bucket: enterprise ]
  ├── [ Scope: billing ]
  │   ├── [ Collection: invoices ]
  │   └── [ Collection: payments ]
  └── [ Scope: catalog ]
      └── [ Collection: products ]
```

## Common Patterns

### SQL++ (N1QL) Secondary Indexing and Querying

**Problem**: Ad-hoc JSON document filtering results in slow primary index table scans.

**Solution**:
Build covering secondary GSI indexes for high-throughput queries:

```sql
CREATE INDEX idx_orders_status ON `ecommerce`.`sales`.`orders` (customerId, orderStatus, orderDate)
WHERE orderStatus != 'cancelled';

SELECT customerId, orderDate, total
FROM `ecommerce`.`sales`.`orders`
WHERE customerId = "cust_987" AND orderStatus = "completed"
ORDER BY orderDate DESC;
```

## Best Practices

**Do**:

- Use Sub-Document API for Partial Mutations: Mutate specific JSON array items or attributes without fetching/resaving the entire document.
- Create Global Secondary Indexes (GSI) Covering Queries: Index the exact fields in `WHERE` and `SELECT` to enable index-only scans.
- Leverage Key-Value Operations for Hot Lookups: Use `get()` and `upsert()` key-value APIs for sub-millisecond reads rather than N1QL queries.
- Size Bucket RAM Quotas Carefully: Allocate sufficient RAM to ensure high active working set cache-hit ratios.

**Don't**:

- Use Primary Indexes in Production: Avoid `CREATE PRIMARY INDEX`; primary scans scan all documents in the collection.
- Store massive binary blobs in documents: Keep documents under 1MB; store images and media in object storage.
- Ignore Cross-Datacenter Replication (XDCR) lag: Monitor XDCR replication queues when synchronizing across multi-region clusters.

## Troubleshooting

| Error                               | Cause                                                                | Solution                                                                              |
| :---------------------------------- | :------------------------------------------------------------------- | :------------------------------------------------------------------------------------ |
| `No index available for query`      | Missing secondary index matching the WHERE predicate in SQL++ query. | Create an index covering query filter and projection columns.                         |
| `Temporary failure / Out of memory` | Couchbase bucket memory quota exhausted by high item count.          | Increase bucket RAM quota or configure eviction policy (value-only vs full eviction). |
| `DocumentExistsException`           | Key already exists in bucket during insert operation.                | Use `upsert` instead of `insert` if overwrite semantics are intended.                 |

## References

- [Couchbase Documentation](https://docs.couchbase.com/home/index.html)


---
Source attribution: G1Joshi
Original project: https://github.com/G1Joshi/Agent-Skills/blob/6a74cf03a8a86dc7d993ead3091b41123dbd0181/skills/databases/couchbase/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2026 G1Joshi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: G1Joshi
Original project: https://github.com/G1Joshi/Agent-Skills/blob/6a74cf03a8a86dc7d993ead3091b41123dbd0181/skills/databases/couchbase/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management
Roles: Backend Developer, Data Engineer, Growth Product Manager, Mobile Developer, Product Manager
Specialties: Database
Tools: Couchbase
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 4bd19511914e5eb891d3b6582523041dfef5a01687df14be925317f362aa4dbe