analytics-dotnet

name	analytics-dotnet
summary	Couchbase Analytics Service (CBAS) for .NET — 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 .NET — 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	.NET SDK 3.x. Requires CouchbaseNetClient 3.x.
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-dotnet"},{"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-dotnet"}]}

Couchbase Analytics — .NET

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

var result = await cluster.AnalyticsQueryAsync<dynamic>(
    "SELECT country, COUNT(*) AS cnt FROM airlines GROUP BY country ORDER BY cnt DESC",
    options => options.Timeout(TimeSpan.FromMinutes(5))
);
await foreach (var row in result)
    Console.WriteLine(row);

Parameterized Query

var result = await cluster.AnalyticsQueryAsync<dynamic>(
    "SELECT * FROM orders WHERE status = $status",
    options => options.Parameter("status", "pending").Timeout(TimeSpan.FromMinutes(5))
);

Window Functions

var result = await cluster.AnalyticsQueryAsync<dynamic>(
    @"SELECT name, country, stars,
             RANK() OVER (PARTITION BY country ORDER BY stars DESC) AS rank_in_country
      FROM hotels
      WHERE stars IS NOT MISSING"
);
await foreach (var row in result.Rows)
{
    Console.WriteLine(row);
}

External Datasets

// Query an external dataset linked to S3 or another source
var result = await cluster.AnalyticsQueryAsync<dynamic>(
    "SELECT * FROM `external-dataset` LIMIT 100"
);

External datasets are created via the Analytics Service UI or REST API and appear as queryable collections.

Troubleshooting

Error	Cause	Fix
DatasetNotFoundException	Dataset not created	Run CREATE ANALYTICS COLLECTION or check name
Query timeout	Large scan, no limit	Add LIMIT, increase Timeout option
Stale data	Replication lag	Expected — Analytics is eventually consistent

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.

var result = await cluster.AnalyticsQueryAsync<dynamic>(
    "SELECT id, total FROM orders WHERE status = \"complete\""
);
var collection = await cluster.BucketAsync("myapp")
    .ContinueWith(b => b.Result.DefaultCollectionAsync().Result);

await foreach (var row in result.Rows)
{
    await collection.UpsertAsync($"summary::{row.id}",
        new { total = (double)row.total });
}

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

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