Services — Choosing the Right One

When you already know the Key (ID) of the document, then KV Operations is by far the simplest way to retrieve or mutate it. The binary protocol used is far quicker than streaming JSON.

If you know the path to the piece of information that you need within a JSON document, then Sub-Document operations will not only retrieve the information more quickly, but will reduce the amount of data that needs to be sent over the network.

Couchbase Analytics Service (CBAS) performs well on huge datasets, with complex aggregations, and uses the first commercial implementation of SQL++ — N1QL for Analytics — which gives a similar query experience to our SQL-like N1QL language. CBAS supports workloads involving only SELECT (not INSERT or UPDATE), and uses local secondary indexes. Scalable performance comes from multi-node partitioned-parallel join, sort, aggregate, and grouped aggregate operators, and multiple storage devices (vbuckets over several nodes).

Use the Analytics Service when you don’t know every aspect of the query in advance -- for example, if the data access patterns change frequently, or you want to avoid creating an index for each data access pattern, or you want to run ad hoc queries for data exploration or visualization.

Use KV Operations - for better performance. Where your mutations are on just a path within the document, use the Sub-Document API.

For the “update from a WHERE clause” with our Query Service, in which case you don’t know which documents would be altered, read the section on CAS and Concurrent Document Mutation to be aware of all of the implications.

Sub-Doc allows appending, prepending, and inserting into arrays. For more sophisticated array operations, use N1QL’s USEKEY.

MapReduce Views uses distributed Map-Reduce for very fast aggregation operations (fast, because the indexes are pre-computed results) — ideal for pre-grouped aggregations, such as grouping temporal data sets (by day, by month, etc.). Views’ spatial support allows for fast searching over extensive geo-spatial data in Couchbase Data Platform 5.x — however, Spatial Views are no longer supported in Couchbase Server 6.x, and so are not found in SDK 3.x. Continuing improvements to our Query Service makes the latter usually a better choice, particularly as Views does not scale as well as the other services, lacking a global Index node.

For queries over a larger number of documents, CBAS would be the best tool here, otherwise, for high throughput, simple queries, pick our Query Service.

Use the Full Text Search (FTS) service when you want to take advantage of natural-language querying. For phrase matching, over free-form text, or matching over word stems, FTS is a powerful solution.

There are more concepts to learn, as FTS offers a very flexible service. In particular, care should be taken over building indexes, to stop them becoming unnecessarily large — see our FTS documentation. Once again, the SDK abstracts away much of the complexity from deeply nested queries, and the interface is similar to our Query Service.

From Couchbase Server 6.5, Search Functions allow the use of FTS within N1QL queries.

For operational queries -- such as the front-end queries behind every page display or navigation — the Query Service is a natural fit.

The Query Service using N1QL - SQL for JSON - is ideal for retrieving multiple documents that match specific queries. Data can be joined together, and Global Secondary Indexes can be used to speed up searches. It’s a powerful and flexible way of querying, retrieving, and updating data, using a familiar language, but if you know the document’s key, then regular KV (or Sub-Doc) operations will always be faster.

Streaming in a distributed system is complex, and thus we do not make our internal streams and changes feed directly available. However, it is exposed through use of our Spark or Kafka connectors, which give you a high level API to our low level primitives.