---
title: "Counters and Other Features"
url: "https://docs.ravendb.net/6.2/document-extensions/counters/counters-and-other-features"
version: "6.2"
language: "python"
---

# Counters and Other Features

> Client language: Python. Also available for [C#](https://docs.ravendb.net/6.2/document-extensions/counters/counters-and-other-features.md), [Java](https://docs.ravendb.net/6.2/document-extensions/counters/counters-and-other-features.java.md), [PHP](https://docs.ravendb.net/6.2/document-extensions/counters/counters-and-other-features.php.md), [Node.js](https://docs.ravendb.net/6.2/document-extensions/counters/counters-and-other-features.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - This section describes the relationships between Counters and other RavenDB features:
>   - How Counters are supported by the different features.
>   - How Counters trigger features' execution.
>
> - In this page:
>   - [Counters and Indexing](#counters-and-indexing)
>   - [Counters and Queries](#counters-and-queries)
>   - [Counters and Revisions](#counters-and-revisions)
>   - [Counters and Changes API](#counters-and-changes-api)
>   - [Counters and Ongoing Tasks](#counters-and-ongoing-tasks) - `Backup`, `External replication`, `ETL`, `Data Subscription`
>   - [Counters and Other Features: summary](#counters-and-other-features-summary)
>   - [Counters Bulk-Insert](#counters-bulk-insert)

## 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](https://docs.ravendb.net/6.2/document-extensions/counters/indexing.python.md)).

- **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](https://docs.ravendb.net/6.2/document-extensions/counters/indexing.python.md#section-1).

## Counters and Queries

Create queries **using code**, or send the server **raw queries** for execution.

- Either way, you can query Counters **by name** but **not by value**.  
  This is because queries are generally [based on indexes](https://docs.ravendb.net/6.2/start/getting-started.md#example-iii---querying), and Counter values are [not indexed](#counters-and-indexing).

- Counter values **can** be [projected](https://docs.ravendb.net/6.2/indexes/querying/projections.python.md) 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 [session.query](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.python.md#sessionquery) to code queries yourself.
  - **Returned Counter Value**: **Accumulated**  
    A Counter's value is returned as a single sum, with no specification of the Counter's value on each node.

```python
_include_single_Counter
          # include a single Counter
          query = session.query(object_type=Product).include(lambda builder: builder.include_counter("ProductLikes"))
```

- Use [RawQuery](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.python.md#sessionadvancedrawquery) 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

```python
# Various RQL expressions sent to the server using counter()
# Returned Counter value is accumulated
rawquery1 = list(session.advanced.raw_query("from products as p select counter(p, 'ProductLikes')"))

rawquery2 = list(
  session.advanced.raw_query("from products select counter('ProductLikes') as ProductLikesCount")
)

rawquery3 = list(
  session.advanced.raw_query("from products where PricePerUnit > 50 select Name, counter('ProductLikes')")
)
```

### counterRaw

```python
# An RQL expression sent to the server using counterRaw()
# Returned Counter value is distributed
query = list(session.advanced.raw_query("from users as u select counterRaw(u, 'downloads')"))
```

## Counters and Revisions

A [document revision](https://docs.ravendb.net/6.2/document-extensions/revisions/overview.python.md) 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](https://docs.ravendb.net/6.2/client-api/changes/what-is-changes-api.md#changes-api) is a Push service, that can inform you of various changes on the Server, including [changes in Counter values](https://docs.ravendb.net/6.2/client-api/changes/how-to-subscribe-to-counter-changes.md#changes-api--how-to-subscribe-to-counter-changes).  
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](https://docs.ravendb.net/6.2/studio/database/tasks/ongoing-tasks/general-info.md) relates to Counters in its own way.

- **Counters** and the **Backup task**  
  There are two [backup](https://docs.ravendb.net/6.2/studio/database/tasks/backup-task.md) 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](#counters-and-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](https://docs.ravendb.net/6.2/studio/database/tasks/ongoing-tasks/external-replication-task.md) 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](https://docs.ravendb.net/6.2/server/ongoing-tasks/etl/basics.md) is used to export data from RavenDB to an external (either Raven or SQL) database.
  - [SQL ETL](https://docs.ravendb.net/6.2/server/ongoing-tasks/etl/sql.md) is **not supported**.  
    Counters cannot be exported to an SQL database over SQL ETL.
  - [RavenDB ETL](https://docs.ravendb.net/6.2/server/ongoing-tasks/etl/raven.md) **is supported**.  
    Counters [are](https://docs.ravendb.net/6.2/server/ongoing-tasks/etl/raven.md#counters) 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](https://docs.ravendb.net/6.2/server/ongoing-tasks/etl/raven.md#adding-counter-explicitly-in-a-script).  
      **Default behavior**: When an ETL script is not provided, Counters are exported.

- **Counters** and the **[Data Subscriptions](https://docs.ravendb.net/6.2/client-api/data-subscriptions/what-are-data-subscriptions.md#data-subscriptions) task**  
  Data Subscriptions can be initiated by document changes, including those caused by **Counter Name updates**.  
  Documents will **not** be delivered in reaction to Counter Value modification.

> **Note**
>
> ## Counters and Other Features: Summary
>
> Use this table to find if and how various RavenDB features are triggered by Counters,
> and how the various features handle Counter values.
>
> - In the **Triggered By** column:
>   - *Document Change* - Feature is triggered by a Counter Name update.
>   - *Countrer Value Modification* - Feature is triggered by a Counter Value modification.
>   - *Time Schedule* - Feature is invoked by a pre-set time routine.
>   - *No Trigger* - Feature is executed manually, through the Studio or by a Client.
> - In the **Counter Value** column:
>   - *Accumulated* - Counter Value is handled as a single accumulated sum.
>   - *Distributed* - Counter Value is handled as a series of values maintained by cluster nodes.
>
> | **Feature** | **Triggered by** | **Counter Value** |
> | - | :- | :- |
> | [Indexing](#counters-and-indexing) | *Document Change* | doesn't handle values |
> | [LINQ Queries](#counters-and-queries) | *No trigger* | *Accumulated* |
> | [Raw Queries](#counters-and-queries) | *No trigger* | `counter()` - *Accumulated* <br /> `counterRaw()` - *Distributed* |
> | [Smuggler](#counters-and-smuggler) | *No trigger* | *Distributed* |
> | [Backup Task](#counters-and-ongoing-tasks) | *Time Schedule* | *Distributed* |
> | [RavenDB ETL Task](#counters-and-ongoing-tasks) | *Document Change*, <br /> *Countrer Value Modification* | *Distributed* |
> | [External Replication task](#counters-and-ongoing-tasks) | *Document Change*, <br /> *Countrer Value Modification* | *Distributed* |
> | [Data Subscriptions Update Task](#counters-and-ongoing-tasks) | *Document Change* | |
> | [Changes API](#counters-and-changes-api) | *Countrer Value Modification* | *Accumulated* |
> | [Revision creation](#counters-and-revisions) | *Document Change* | *Accumulated* |

## Counters Bulk-Insert

`store.bulk_insert` is RavenDB's high-performance data insertion operation.  
Use its `counters_for` interface's `increment` method to add or update counters with great speed.

- Syntax

  - `counters_for`

```python
def counters_for(self, id_: str) -> CountersBulkInsert:
  ...
```

| Parameters | Type | Description |
| :- | :- | :- |
| **id** | `str` | Document ID |

- `Increment`

```python
def increment(self, name: str, delta: int = 1) -> None: ...
```

| Parameters | Type | Description |
| :- | :- | :- |
| **name** | `str` | Counter Name |
| **delta** | `int` | Default: 1L |

- Usage Flow

  - Create a `store.bulk_insert` instance.
  - Pass the instance's `counters_for` interface, the document ID
  - Call `increment` as many times as you like. Pass it -  
    The Counter Name and Value (delta to be added).

- Usage Sample  
  In this sample, we attach a counter to all User documents.

```python
with store.open_session() as session:
  result = list(session.query(object_type=User).where_less_than("Age", 30))
  users_ids = [session.advanced.get_document_id(user) for user in result]

with store.bulk_insert() as bulk_insert:
  for user_id in users_ids:
      # Choose document
      counters_for = bulk_insert.counters_for(user_id)

      # Add or Increment a counter
      bulk_insert.counters_for(user_id).increment("download", 100)
```

## See also

- [Studio Counters Management](https://docs.ravendb.net/6.2/studio/database/document-extensions/counters.md#counters)
- [Counters Overview](https://docs.ravendb.net/6.2/document-extensions/counters/overview.python.md)
- [Creating and Modifying Counters](https://docs.ravendb.net/6.2/document-extensions/counters/create-or-modify.python.md)
- [Deleting a Counter](https://docs.ravendb.net/6.2/document-extensions/counters/delete.python.md)
- [Retrieving Counter Values](https://docs.ravendb.net/6.2/document-extensions/counters/retrieve-counter-values.python.md)
- [Counters In Clusters](https://docs.ravendb.net/6.2/document-extensions/counters/counters-in-clusters.md)
- [Counters Operations](https://docs.ravendb.net/6.2/client-api/operations/counters/get-counters.md#operations--counters--how-to-get-counters)
