analytics-php

name	analytics-php
summary	Couchbase Analytics Service (CBAS) for PHP — 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 PHP — 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	PHP SDK 4.x. Requires couchbase>=4.0.
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-php"},{"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-php"}]}

Couchbase Analytics — PHP

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. Use it for aggregations, reports, and joins across large datasets.

---

Setup — Create an Analytics Collection

-- Link the default bucket (once, in the Analytics workbench or cbsh)
CREATE DATAVERSE myapp IF NOT EXISTS;
USE myapp;
CREATE ANALYTICS COLLECTION orders ON `myapp`.`_default`.`orders` IF NOT EXISTS;

---

Running Analytics Queries

The PHP SDK uses $cluster->analyticsQuery().

<?php
use Couchbase\ClusterOptions;
use Couchbase\Cluster;

$options = new ClusterOptions();
$options->credentials(getenv("CB_USERNAME"), getenv("CB_PASSWORD"));
$cluster = new Cluster('couchbase://localhost', $options);

// Simple aggregation
$result = $cluster->analyticsQuery(
    'SELECT country, COUNT(*) AS cnt FROM orders GROUP BY country ORDER BY cnt DESC'
);
foreach ($result->rows() as $row) {
    echo json_encode($row) . "\n";
}

Parameterized queries

<?php
use Couchbase\AnalyticsOptions;

$opts = new AnalyticsOptions();
$opts->namedParameters(['country' => 'US']);

$result = $cluster->analyticsQuery(
    'SELECT * FROM orders WHERE country = $country',
    $opts
);

Window functions

<?php
$result = $cluster->analyticsQuery(<<<SQL
    SELECT name, country, stars,
           RANK() OVER (PARTITION BY country ORDER BY stars DESC) AS rank
    FROM hotels
SQL);

---

Key differences from operational SQL++

	Analytics (analyticsQuery)	Operational (query)
Data source	Shadow copy (async replicated)	Live data
Isolation	No impact on KV/Query	Shares Query Service resources
Consistency	Eventually consistent	Configurable (request_plus)
Use case	OLAP, reports, large joins	OLTP, low-latency lookups

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"'
);
$collection = $cluster->bucket('myapp')->defaultCollection();

foreach ($result->rows() as $row) {
    $collection->upsert("summary::{$row['id']}", ['total' => $row['total']]);
}

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

Troubleshooting

Error	Cause	Fix
DataverseNotFoundException	Analytics collection not created	Run CREATE ANALYTICS COLLECTION
CompilationException	SQL++ syntax error	Check field names and dataverse
Slow query	Missing index or large dataset	Add Analytics index or filter earlier