Get Counters Operation
This operation is used to get counters' values for a specific document.
It can be used to get the value of a single counter, multiple counters' values, or all counters' values.
Syntax
// Get single counter
const getCountersOp = new GetCountersOperation(docId, counter);
const getCountersOp = new GetCountersOperation(docId, counter, returnFullResults = false);
// Get multiple counters
const getCountersOp = new GetCountersOperation(docId, counters);
const getCountersOp = new GetCountersOperation(docId, counters, returnFullResults = false);
// Get all counters of a document
const getCountersOp = new GetCountersOperation(docId);
Parameter | Type | Description |
---|---|---|
docId | string | The ID of the document that holds the counters |
counter | string | The name of the counter to get |
counters | string[] | The list of counter names to get |
returnFullResults | boolean | A flag which indicates if the operation should include a dictionary of counter values per database node in the result |
The full results flag:
If RavenDB is running in a distributed cluster, and the database resides on several nodes,
then a counter can have a different local value on each database node.
The total counter value is the sum of all the local values of this counter from each node.
To get the counter values per database node, set the returnFullResults
flag to true
.
Return Value
The operation returns a CountersDetail
object, which holds a list of CounterDetail
objects
// The CounterDetails object:
// ==========================
{
// A list of "CounterDetail" objects;
counters;
}
// The CounterDetail object:
// =========================
{
// ID of the document that holds the counter;
documentId; // string
// The counter name
counterName; //string
// Total counter value
totalValue; // number
// A dictionary of counter values per database node
counterValues?;
// Etag of counter
etag?; // number;
// Change vector of counter
changeVector?; // string
}
Examples
Assume we have a document users/1
that holds 3 counters -
"Likes", "Dislikes" and "Downloads" - with values 10, 20 and 30 (respectively)
Example #1 : Get single counter
// Define the get counters operation
const getCountersOp = new GetCountersOperation("users/1", "Likes");
// Execute the operation by passing it to operations.send
const result = await documentStore.operations.send(getCountersOp);
const counters = result.counters;
Result:
{
"counters":
[
{
"documentId" : "users/1",
"counterName" : "Likes",
"totalValue" : 10,
"counterValues" : null
}
]
}
Example #2 : Get multiple counters
const getCountersOp = new GetCountersOperation("users/1", ["Likes", "Dislikes"]);
const result = await documentStore.operations.send(getCountersOp);
const counters = result.counters;
Result:
{
"counters":
[
{
"documentId" : "users/1",
"counterName" : "Likes",
"totalValue" : 10,
"counterValues" : null
},
{
"documentId" : "users/1",
"counterName" : "Dislikes",
"totalValue" : 20,
"counterValues" : null
}
]
}
Example #3 : Get all counters
const getCountersOp = new GetCountersOperation("users/1");
const result = await documentStore.operations.send(getCountersOp);
const counters = result.counters;
Result:
{
"counters":
[
{
"documentId" : "users/1",
"counterName" : "Likes",
"totalValue" : 10,
"counterValues" : null
},
{
"documentId" : "users/1",
"counterName" : "Dislikes",
"totalValue" : 20,
"counterValues" : null
},
{
"documentId" : "users/1",
"counterName" : "Downloads",
"totalValue" : 30,
"counterValues" : null
}
]
}
Example #4 : Include full values in the result
const getCountersOp = new GetCountersOperation("users/1", "Likes", true);
const result = await documentStore.operations.send(getCountersOp);
const counters = result.counters;
Result:
Assuming a 3-node cluster, the distribution of the counter's value to nodes A, B, and C could be as follows:
{
"counters":
[
{
"documentId" : "users/1",
"counterName" : "Likes",
"totalValue" : 10,
"counterValues" :
{
"A:35-UuCp420vs0u+URADcGVURA" : 5,
"B:83-SeCFU29daUOxfjUcAlLiJw" : 3,
"C:27-7i7GP8bOOkGYLNflO/rSeg" : 2,
}
}
]
}