Counters and Other Features

Counters and Indexing

Indexing Counters can speed-up finding them and the documents that contain them.

• Indexing Counter Values Dynamic indexes (aka auto-indexes) cannot index counter values. To index counter values, create a static index that inherits from AbstractCountersIndexCreationTask (see here).

• Indexing Counter Names
  Re-indexing due to Counter-name modification is normally rare enough to pause no performance issues.
  To index a document's Counters by name, use CounterNamesFor.

Counters and Queries

Send the server raw queries for execution.

• You can query Counters by name but not by value.
  This is because queries are generally based on indexes, and Counter values are not indexed.

• Counter values can be projected from query results, as demonstrated in the following examples.
  This way a client can get counter values from a query without downloading whole documents.

• Use RawQuery to send the server raw RQL expressions for execution.

  • You can use the counter method.
    Returned Counter Value: Accumulated

  • You can use the counterRaw method.
    Returned Counter Value: Distributed
    A Counter's value is returned as a series of values, each maintained by one of the nodes.

    • It is not expected of you to use this in your application.
      Applications normally use the Counter's overall value, and very rarely refer to the value each node gives it.

  counter and counterRaw samples:
  

  • counter
  • counterRaw

  //Various RQL expressions sent to the server using counter()
  //Returned Counter value is accumulated
  $rawQuery1 = $session->advanced()
      ->rawQuery(CounterResult::class, "from products as p select counter(p, \"ProductLikes\")")
      ->toList();
  
  $rawQuery2 = $session->advanced()
      ->rawQuery(CounterResult::class,"from products select counter(\"ProductLikes\") as ProductLikesCount")
      ->toList();
  
  $rawQuery3 = $session->advanced()
      ->rawQuery(CounterResult::class,"from products where PricePerUnit > 50 select Name, counter(\"ProductLikes\")")
      ->toList();

  //An RQL expression sent to the server using counterRaw()
  //Returned Counter value is distributed
  $query = $session->advanced()
      ->rawQuery(CounterResultRaw::class, "from users as u select counterRaw(u, \"downloads\")")
      ->toList();

Counters and Revisions

A document revision stores all the document Counters' names and values when the revision was created.

• Stored Counter Values: Accumulated
  A revision stores a Counter's value as a single sum, with no specification of the Counter's value on each node.

• Revisions-creation can be initiated by Counter-name modification.

  • When the Revisions feature is enabled, the creation or deletion of a Counter initiates the creation of a new document revision.
  • Counter value modifications do not cause the creation of new revisions.

Counters and Changes API

Changes API is a Push service, that can inform you of various changes on the Server, including changes in Counter values.
You can target all Counters, or specify the ones you wish to follow.

• Pushed Counter Value: Accumulated
  Changes API methods return a Counter's value as a single sum, without specifying its value on each node.
• The service is initiated by Counter Value Modification.

Counters and Ongoing Tasks:

Each ongoing task relates to Counters in its own way.

• Counters and the Backup task
  There are two backup types: logical-backup and snapshot.
  Both types store and restore all data, including Counters.
  Both types operate as an ongoing backup routine, with a pre-set time schedule.

  • Logical Backup:
    Backed-up Counter values: Distributed
    A logical backup is a higher-level implementation of Smuggler.
    As with Smuggler, Counters are backed-up and restored including their values on all nodes.
  • Snapshot:
    A snapshot stores all data and settings as a single binary image. All components, including Counters, are restored to the exact same state they've been at during backup.

• Counters and the External Replication task
  The ongoing external replication task replicates all data, including Counters.

  • Replicated Counter Value: Distributed
    Counters are replicated along with their values on all nodes.
  • Replication can be initiated by both Counter-name update and Counter-value modification.

• Counters and the ETL task
  ETL is used to export data from RavenDB to an external (either Raven or SQL) database.

  • SQL ETL is not supported.
    Counters cannot be exported to an SQL database over SQL ETL.
  • RavenDB ETL is supported.
    Counters are exported over RavenDB ETL.
    • Export can be initiated by both Counter-name update and Counter-value modification.
    • Exported Counter Value: Distributed
      Counters are exported along with their values on all nodes.
    • Counters can be exported using a script.
      Default behavior: When an ETL script is not provided, Counters are exported.

Including Counters

You can include Counters while loading a document.
An included Counter is retrieved in the same request as its owner-document and is held by the session, so it can be immediately retrieved when needed with no additional remote calls.

• Including Counters when using session.load:

  • Include a single Counter using include_counter
  • Include multiple Counters using include_counters

  include_counter and include_counters usage samples:
  

  • IncludeCounter
  • IncludeCounters

  //include single Counters
  $productPage = $session->load(Product::class, "products/1-C", function($includeBuilder) {
      return $includeBuilder
              ->includeCounter("ProductLikes")
              ->includeCounter("ProductDislikes")
              ->includeCounter("ProductDownloads");
  });

  //include multiple Counters
  //note that you can combine the inclusion of Counters and documents.
  $productPage = $session->load(Product::class, "products/1-C", function($includeBuilder) {
      return $includeBuilder
          ->includeDocuments("products/1-C")
          ->includeCounters(["ProductLikes", "ProductDislikes"]);
  });

• Including Counters when using Session.Query:

  • Include a single Counter using include_counter.
  • Include multiple Counters using include_counters.

  include_counter and include_counters usage samples:
  

  • IncludeCounter
  • IncludeCounters

  //include a single Counter
  $query = $session->query(Product::class)
          ->include(function($includeBuilder) {
              return $includeBuilder->includeCounter("ProductLikes");
          });

  //include multiple Counters
  $query = $session->query(Product::class)
          ->include(function($includeBuilder){
              return $includeBuilder->includeCounters(["ProductLikes", "ProductDownloads"]);
          });