getting-started

name	getting-started
summary	Introduction to Couchbase for new developers — mental model, core concepts (bucket/scope/collection/document), service map (KV vs SQL++ vs Search vs Analytics), choosing the right skill, and where to start
description	Introduction to Couchbase for new developers — mental model, core concepts (bucket/scope/collection/document), service map (KV vs SQL++ vs Search vs Analytics), choosing the right skill, and where to start
metadata	{"last_verified":"2026-05","handoff":[{"condition":"user asks a general Couchbase question and needs skill routing","skill":"couchbase"},{"condition":"user wants to run Couchbase locally with Docker","skill":"local-dev-setup"},{"condition":"user wants to use Couchbase Capella (cloud)","skill":"capella-quickstart"},{"condition":"user wants to connect from code","type":"variant","skill":"server-connection-python"},{"condition":"user asks about SQL++ queries","skill":"sqlpp-language"},{"condition":"user wants to model their data","skill":"server-data-modeling"},{"condition":"user asks about testing their Couchbase application","skill":"testing-patterns"},{"condition":"user is migrating from another database to Couchbase","skill":"migration"},{"condition":"user asks about backup or restore","skill":"backup"},{"condition":"user asks about disaster recovery planning or RTO/RPO","skill":"disaster-recovery"},{"condition":"user asks about timeouts, exceptions, or connection errors","skill":"error-handling"},{"condition":"user asks about using Couchbase as a cache or session store","skill":"caching-patterns"},{"condition":"user asks about IDE tooling or the VS Code extension","skill":"vscode-extension"}]}

Getting Started with Couchbase

What Couchbase is

Couchbase is a distributed document database. Documents are JSON. There are no fixed schemas — each document in a collection can have different fields.

It combines three things that usually require separate systems:

• KV store (like Redis) — sub-millisecond get/set by key
• SQL++ query engine (like PostgreSQL) — full SQL over JSON documents
• Full-text + vector search (like Elasticsearch) — FTS and semantic search

Data hierarchy

Cluster
└── Bucket          (like a database; holds data + config)
    └── Scope       (like a schema/namespace; groups collections)
        └── Collection  (like a table; holds documents)
            └── Document    (JSON object with a string key)

Every document has a key (string, you choose it) and a value (any JSON). There is no auto-increment ID — you design your keys.

// Key: "airline::137"
{
  "type": "airline",
  "name": "Air France",
  "iata": "AF",
  "country": "France"
}

Key design matters — type::id is the most common convention:

user::alice
order::2024-001
session::abc123
product::sku-9999

Services map

Service	Use when	Skill
KV	You know the document key	server-connection-*
SQL++	You need to query by field values	server-querying-*
Full-Text Search	Text search, fuzzy, geo	search-*
Vector Search	Semantic / AI similarity	search-*
Analytics	OLAP, large aggregations, slow queries OK	analytics-*
Eventing	React to document changes	eventing

Rule of thumb: KV is always fastest. Use SQL++ when you don't know the key. Use Search when you need text relevance or vectors.

Couchbase vs what you know

Concept	PostgreSQL	MongoDB	Redis	Couchbase
Database	Database	Database	—	Bucket
Schema	Schema	—	—	Scope
Table	Table	Collection	—	Collection
Row	Row	Document	Key	Document
Primary key	id column	_id field	Key	Document key
Query language	SQL	MQL	—	SQL++
Index	B-tree index	Index	—	GSI index

Key differences from MongoDB:

• SQL++ is a superset of SQL — JOINs, GROUP BY, window functions all work
• Document key is separate from the document body (not _id inside the JSON)
• KV operations bypass the query engine entirely — much faster for known keys

Key differences from Redis:

• Documents are JSON, not strings/hashes/lists
• Full query language — no need to maintain secondary data structures
• Persistence and replication built in

Where to start

Before generating any code: Confirm the user's language. If the user has not mentioned a language, ask: "Which language are you using?" Default to Python only if the user does not respond. Then route to server-connection-<lang>.

Option A — Local Docker (fastest): → local-dev-setup

Option B — Couchbase Capella free tier (no install): → capella-quickstart

Once you have a cluster, pick your language: → server-connection-{nodejs|python|java|go|dotnet|rust|scala|php|ruby}

Then write your first query: → sqlpp-language

The travel-sample dataset

Most Couchbase examples use travel-sample — a built-in dataset with airlines, airports, routes, hotels, and landmarks. It's available in the UI under Settings → Sample Buckets. All skill examples reference it.

-- Your first query (run in the Query Workbench in the UI)
SELECT name, country FROM `travel-sample`.inventory.airline
WHERE country = "United States"
LIMIT 5;