analytics-vs-query.md

Analytics Service vs Query Service

Platform-agnostic reference shared by all analytics-* skills.

---

When to use each service

Scenario	Use
Full collection scan + complex aggregation	Analytics Service
OLTP point lookups, small result sets	Query Service
Report that would need many GSI indexes	Analytics Service
Real-time data (< 1s staleness required)	Query Service
Large joins across multiple collections	Analytics Service
Low-latency application queries	Query Service

Key differences

	Analytics Service	Query Service
Data source	Shadow copy (async replicated from KV)	Live data
Isolation	Runs on dedicated Analytics nodes — no impact on KV or Query workloads	Shares Query Service resources with application traffic
Consistency	Eventually consistent (seconds to minutes lag)	Configurable — not_bounded, request_plus, at_plus
Indexing	No GSI indexes needed — full scans are the design	Requires GSI indexes for performance
Use case	OLAP, reports, window functions, large joins	OLTP, low-latency application queries

Setup: creating an Analytics collection

Before querying, mirror your operational collection into the Analytics Service:

-- Create a dataverse (namespace)
CREATE DATAVERSE `myapp` IF NOT EXISTS;

-- Mirror an operational collection
CREATE ANALYTICS COLLECTION `myapp`.orders
  ON `myapp`.`_default`.`orders`;

After creation, data replicates asynchronously. Query using cluster.analyticsQuery() / cluster.analytics_query() — the SQL++ syntax is identical to the Query Service.

Common errors

Error	Cause	Fix
DataverseNotFoundException	Analytics collection not created	Run CREATE ANALYTICS COLLECTION
CompilationException	SQL++ syntax error	Check field names and dataverse path
AmbiguousTimeoutException	Query too slow or cluster overloaded	Add LIMIT, check Analytics node resources