columnar-analytics

name	columnar-analytics
summary	Couchbase Server 8.x columnar analytics — native column store for OLAP queries, direct collection access without shadow datasets, SQL++ analytics queries, and migration from legacy CBAS
description	Couchbase Server 8.x columnar analytics — native column store for OLAP queries, direct collection access without shadow datasets, SQL++ analytics queries, and migration from legacy CBAS
compatibility	Couchbase Server 8.x. Not available on Server 7.x or earlier — use the analytics-* skills for CBAS on Server 6.x–7.x.
metadata	{"last_verified":"2026-05","min_server_version":"8.0","handoff":[{"condition":"user is on Server 7.x or earlier and needs legacy CBAS","type":"variant","skill":"analytics-python"},{"condition":"user asks about SQL++ queries","skill":"sqlpp-language"},{"condition":"user asks about slow queries or index recommendations","skill":"server-query-optimizer"},{"condition":"user needs the Query Service instead of columnar analytics","type":"variant","skill":"server-querying-python"}]}

Couchbase Columnar Analytics (Server 8.x)

Version disambiguation: This skill covers Server 8.x only. If the user has not stated their server version, ask: "Which version of Couchbase Server are you on?" Server 6.x–7.x users should be routed to the appropriate analytics-<language> skill instead.

Couchbase Server 8.x introduces a native columnar analytics engine — a column-oriented store built directly into the cluster. It replaces the legacy CBAS (Couchbase Analytics Service) architecture for new deployments.

SDK code examples — the analytics_query() / analyticsQuery() API is identical across all SDKs. For language-specific connection setup and SDK imports, load the appropriate analytics-* skill (e.g. analytics-python, analytics-java).

Key differences from legacy CBAS (Server 6.x–7.x)

Area	Columnar (8.x)	Legacy CBAS (6.x–7.x)
Data access	Direct — reads from KV service	Shadow datasets — async copy from KV
Freshness	Near real-time	Eventual (dataset sync lag)
Setup	No dataset creation needed	Must CREATE ANALYTICS DATASET first
Query endpoint	Port 8095 (analytics)	Port 8095 (same port, different engine)
SQL++ dialect	SQL++ with columnar extensions	SQL++ (N1QL for Analytics)
Indexes	Columnar indexes (automatic)	No user-defined indexes
Transactions	Read-only	Read-only
SDK API	analytics_query() — unchanged	analytics_query() — same API

Direct collection access (8.x only)

On Server 8.x, query collections directly — no dataset creation needed:

-- No CREATE ANALYTICS DATASET needed on 8.x
SELECT COUNT(*), SUM(total), AVG(total)
FROM `myapp`.`_default`.`orders`
WHERE createdAt > "2024-01-01"
GROUP BY status

On legacy CBAS (7.x), you would first need:

-- Legacy CBAS only — not needed on 8.x
CREATE ANALYTICS DATASET orders ON `myapp`.`_default`.`orders`;
CONNECT LINK Local;

Window functions

SELECT
    orderId,
    customerId,
    total,
    SUM(total) OVER (
        PARTITION BY customerId
        ORDER BY createdAt
        ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
    ) AS running_total,
    RANK() OVER (PARTITION BY customerId ORDER BY total DESC) AS rank_by_value
FROM `myapp`.`_default`.`orders`
WHERE status = 'completed'

Parameterized queries

-- Named parameters (syntax is the same across all SDKs)
SELECT * FROM `myapp`.`_default`.`orders`
WHERE status = $status AND total > $min

Pass parameters via AnalyticsOptions / AnalyticsQueryOptions in your SDK. See the analytics-* language skill for the exact API.

Scan consistency

Mode	Behaviour	Use when
not_bounded (default)	Fastest — may miss very recent writes	Dashboards, reporting
request_plus	Waits for all pending mutations to be indexed	Auditing, post-write reads

When to use columnar vs operational SQL++

Use case	Use
Aggregations over millions of rows	Columnar analytics
Real-time dashboards	Columnar analytics
JOIN across large collections	Columnar analytics
Point lookups by document key	KV (collection.get())
Transactional reads with low latency	Operational SQL++
Full-text or semantic search	Search service

Migrating from legacy CBAS (7.x -> 8.x)

1. Remove CREATE ANALYTICS DATASET statements — not needed on 8.x
2. Replace FROM DatasetName with FROM bucket.scope.collection
3. Remove CONNECT LINK Local — automatic on 8.x
4. SDK code (analytics_query()) is unchanged — no SDK changes required

Troubleshooting

Symptom	Cause	Fix
Dataset not found error	Legacy CBAS query on 8.x	Remove dataset reference, query collection directly
Stale results	not_bounded consistency	Use request_plus scan consistency
Slow aggregation	Missing columnar index	Check query plan with EXPLAIN ANALYTICS
Connection refused on port 8095	Analytics service not enabled	Enable Analytics service on the node

---

Capella Columnar

Capella Columnar is a separate, fully-managed columnar analytics DBaaS on Couchbase Capella. It is distinct from both Capella Operational (the standard Capella cluster) and self-managed Couchbase Server 8.x.

What it is

• A dedicated columnar cluster provisioned independently from your operational cluster
• Ingests data from Capella Operational clusters, S3, or other sources via Links
• Optimised for OLAP workloads — not for KV or transactional operations
• Billed and managed separately from Capella Operational

Connection

In the Capella UI: Columnar → Connect → Connection String. The connection string uses the couchbases:// scheme (TLS required):

couchbases://cb.<columnar-cluster-id>.cloud.couchbase.com

Authenticate with Capella Columnar database credentials (created in the Columnar UI under Connect → Database Access). These are separate from your Capella Operational credentials.

SDK entry point

The SDK API is identical to legacy CBAS — use analytics_query() / analyticsQuery():

# Python — same API as CBAS, different connection string
from couchbase.cluster import Cluster
from couchbase.options import ClusterOptions
from couchbase.auth import PasswordAuthenticator

cluster = Cluster(
    "couchbases://cb.<columnar-cluster-id>.cloud.couchbase.com",
    ClusterOptions(PasswordAuthenticator("db-user", "db-password"))
)
result = cluster.analytics_query("SELECT * FROM `mystore`.`_default`.`orders` LIMIT 10")
for row in result:
    print(row)

Capella Columnar vs Server 8.x columnar vs legacy CBAS

Area	Capella Columnar	Server 8.x Columnar	Legacy CBAS (6.x–7.x)
Deployment	Managed DBaaS (Capella)	Self-managed Server 8.x	Self-managed Server 6.x–7.x
Data source	Links to Capella Operational, S3	Direct KV service access	Shadow datasets (async copy)
Setup	Provision in Capella UI	Enable Analytics service	CREATE ANALYTICS DATASET
Connection string	couchbases://cb.<columnar-id>.cloud.couchbase.com	couchbase:// or couchbases://	couchbase:// or couchbases://
Credentials	Columnar database credentials	Server RBAC users	Server RBAC users
SDK API	analytics_query() — unchanged	analytics_query() — unchanged	analytics_query() — unchanged
Billing	Separate from Operational	Included in Server license	Included in Server license