Counters: Overview

Convenient Counting Mechanism

Counters are very easy to manage, using simple API methods or through the Studio.

E.g. Use counters when you want to -

• Keep track of the number of times a document has been viewed or rated.
• Count how many visitors from certain countries or regions read a document.
• Continuously record the number of visitors on an event page.
• Avoid having to update the whole document for just a numeric value change.
• Have a need for a high-throughput counter (also see Distributed Values below).

Distributed Values

A Counter's value is distributed between cluster nodes.
Among the advantages of this:

• The cluster remains available even when nodes crash.
• Any node can provide or modify a Counter's value immediately, without checking or coordinating this with other nodes.

High Performance, Low Resources

A document includes the Counter's name, while the Counter's actual value is kept in a separate location.
Modifying a Counter's value doesn't require the modification of the document itself.
This results in a performant and uncostly operation.

High-Frequency Counting

Counters are especially useful when a very large number of counting operations is required,
because of their speed and low resources usage.

E.g. Use Counters -

• For an online election page, to continuously update a Number-Of-Votes Counter for each candidate.
• To continuously update Counters with the number of visitors in different sections of a big online store.

Design

A document's metadata contains only the Counters' names-list for this document.
Counter Values are not kept in the document's metadata, but in a separate location.

Therefore, changes like adding a new counter or deleting an existing counter trigger a document change,
while simply modifying the Counter Value does not.

Cumulative Counter Actions

• Counter value-modification actions are cumulative, the order in which they are executed doesn't matter.
  E.g., It doesn't matter if a Counter has been incremented by 2 and then by 7, or by 7 first and then by 2.
• When a Counter is deleted, the sequence of Counter actions becomes non-cumulative and may require special attention.

Counters and Conflicts

Counter actions (for either name or value) do not cause conflicts.

• Counter actions can be executed concurrently or in any order, without causing a conflict.
• You can successfully modify Counters while their document is being modified by a different client.

Counters Cost

Counters are designated to lower the cost of counting, but do come with a price.

• All the names of a document's Counters are added to its content, increasing its size.
• Counter values occupy storage space.

Counters Naming Convention

• Valid characters: All visible characters, including Unicode symbols
• Length: Up to 512 bytes
• Encoding: UTF-8

Counter Values

• Valid range: Signed 64-bit integer (-9223372036854775808 to 9223372036854775807)
• Only integer additions are supported (no floats or other mathematical operations).

Number of Counters Per Document

RavenDB doesn't limit the number of Counters you can create.

The HasCounters Flag

When a Counter is added to a document, RavenDB automatically sets a HasCounters Flag in the document's metadata.
When all Counters are removed from a document, the server automatically removes this flag.

Enabling the Counters Feature

Counters management is an experimental feature and is disabled by default.
To activate it you need to edit RavenDB's configuration file and enable experimental features.

Counter Methods and the CountersFor Object

Managing Counters is performed using the CountersFor Session object.

• Counter methods:

  • CountersFor.Increment: Increment the value of an existing Counter, or create a new Counter if it doesn't exist.
  • CountersFor.Delete: Delete a Counter.
  • CountersFor.Get: Get the current value of a Counter.
  • CountersFor.GetAll: Get all the Counters of a document and their values.

• Usage Flow:

  • Open a session.
  • Create an instance of CountersFor.
    • Either pass CountersFor an explicit document ID, -or-
    • Pass it an entity tracked by the session, e.g. a document object returned from session.query or from session.Load.
  • Use Counter methods to manage the document's Counters.
  • If you execute Increment or Delete, call session.SaveChanges for the action to take effect on the server.

• Success and Failure:

  • As long as the document exists, Counter actions (Increment, Get, Delete etc.) always succeed.
  • When a transaction that includes a Counter modification fails for any reason (e.g. a document concurrency conflict), the Counter modification is reverted.

• CountersFor Usage Samples
  You can Use CountersFor by explicitly passing it a document ID (without pre-loading the document).
  You can also use CountersFor by passing it the document object.
  

  • Pass-CountersFor-Document-ID
  • Pass-CountersFor-Document-Object

  // Use CountersFor without loading a document
  
  // 1. Open a session
  using (var session = docStore.OpenSession())
  {
      // 2. pass an explicit document ID to the CountersFor constructor 
      var documentCounters = session.CountersFor("products/1-C");
  
      // 3. Use `CountersFor` methods to manage the product document's Counters
      documentCounters.Delete("ProductLikes"); // Delete the "ProductLikes" Counter
      documentCounters.Increment("ProductModified", 15); // Add 15 to Counter "ProductModified"
      var counter = documentCounters.Get("DaysLeftForSale"); // Get "DaysLeftForSale"'s value
  
      // 4. Save changes to the session
      session.SaveChanges();
  }

  // Use CountersFor by passing it a document object
  
  // 1. Open a session
  using (var session = docStore.OpenSession())
  {
      // 2. Use the session to load a document.
      var document = session.Load<Product>("products/1-C");
  
      // 3. Create an instance of `CountersFor`
      //   Pass the document object returned from session.Load as a param.
      var documentCounters = session.CountersFor(document);
  
      // 4. Use `CountersFor` methods to manage the product document's Counters
      documentCounters.Delete("ProductLikes"); // Delete the "ProductLikes" Counter
      documentCounters.Increment("ProductModified", 15); // Add 15 to Counter "ProductModified"
      var counter = documentCounters.Get("DaysLeftForSale"); // Get value of "DaysLeftForSale"
  
      // 5. Save the changes to the session
      session.SaveChanges();
  }

Managing Counters Using Operations

• In addition to working with the high-level Session, you can manage Counters using the low-level Operations.

• CounterBatchOperation can operate on a set of Counters of different documents in a single request.