analytics-go

name	analytics-go
summary	Couchbase Analytics Service (CBAS) for Go — run OLAP queries, window functions, and external data links without impacting operational workloads (Server 6.x–7.x; use columnar-analytics for Server 8+)
description	Couchbase Analytics Service (CBAS) for Go — run OLAP queries, window functions, and external data links without impacting operational workloads (Server 6.x–7.x; use columnar-analytics for Server 8+)
compatibility	Go SDK 2.x (gocb/v2). Requires github.com/couchbase/gocb/v2.
metadata	{"last_verified":"2026-05","min_server_version":"6.0","deprecated_by":"columnar-analytics","deprecated_since":"8.0","max_server_version":"7.6","handoff":[{"condition":"user asks about SQL++ queries","skill":"server-querying-go"},{"condition":"user is upgrading to Server 8.x and wants the columnar engine","skill":"columnar-analytics"},{"condition":"user wants to write results back to operational collections transactionally","type":"variant","skill":"transactions-go"}]}

Couchbase Analytics — Go

Version disambiguation: This skill covers Couchbase Server 6.x–7.x (legacy CBAS). If the user mentions Server 8, Couchbase 8, or the columnar engine, route to columnar-analytics instead. If the server version is unknown, ask before proceeding. Analytics runs OLAP queries on a shadow copy of your data, isolated from KV and Query Service workloads.

Setup

CREATE DATAVERSE myapp IF NOT EXISTS;
USE myapp;
CREATE ANALYTICS COLLECTION orders ON `myapp`.`_default`.`orders` IF NOT EXISTS;

SDK Query

import (
    "fmt"
    "time"
    "github.com/couchbase/gocb/v2"
)

result, err := cluster.AnalyticsQuery(
    "SELECT country, COUNT(*) AS cnt FROM airlines GROUP BY country ORDER BY cnt DESC",
    &gocb.AnalyticsOptions{Timeout: 5 * time.Minute},
)
if err != nil { panic(err) }
for result.Next() {
    var row map[string]interface{}
    if err := result.Row(&row); err != nil { panic(err) }
    fmt.Println(row)
}
if err := result.Err(); err != nil { panic(err) }

Parameterized Query

result, err := cluster.AnalyticsQuery(
    "SELECT * FROM orders WHERE status = $status",
    &gocb.AnalyticsOptions{
        NamedParameters: map[string]interface{}{"status": "pending"},
        Timeout:         5 * time.Minute,
    },
)

Analytics vs Query Service: See shared/server/analytics-vs-query.md for the full comparison, setup steps, and common errors.

Writing Results Back

Use transactions for atomic write-back, or individual KV upserts for non-atomic bulk writes.

result, _ := cluster.AnalyticsQuery(
    `SELECT id, total FROM orders WHERE status = "complete"`, nil,
)
collection := cluster.Bucket("myapp").DefaultCollection()

var row struct {
    ID    string  `json:"id"`
    Total float64 `json:"total"`
}
for result.Next() {
    result.Row(&row)
    collection.Upsert("summary::"+row.ID, map[string]interface{}{"total": row.Total}, nil)
}

For atomic multi-document write-back, wrap in a transaction — see transactions-go.

When to Use Analytics vs Query Service

Scenario	Use
Full collection scan + complex aggregation	Analytics
OLTP point lookups	Query Service
Report needing many GSI indexes	Analytics
Real-time data (< 1s staleness)	Query Service