---
title: "Document Extensions: Time Series"
description: "Time series* are sets of numeric data items, associated with timestamps and ordered"
url: "https://docs.ravendb.net/6.2/studio/database/document-extensions/time-series"
version: "6.2"
---

# Document Extensions: Time Series

> 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."

## Document Extensions: Time Series

> **Note**
>
> - **Time series** are sets of numeric data items, associated with timestamps and ordered
>   by time.
>
> - The studio interface allows you to edit, query and index time series data, as well as
>   view it as a list of entries or as a graph.
>
> - An **Incremental Time Series** is a special type of time series that allows you to
>   handle time series values as counters.  
>   Read more about incremental time series [here](https://docs.ravendb.net/6.2/document-extensions/timeseries/incremental-time-series/overview.md),
>   and learn how to define them through Studio [below](#incremental-time-series).
>
> - In this page:
>   - [Document View](#document-view)
>   - [Time Series View](#time-series-view)
>     - [Create new Time Series (by Creating the First Entry)](#create-new-time-series-by-creating-its-first-entry)
>     - [Editing an Entry](#editing-an-entry)
>     - [Deleting a Range of Entries](#deleting-a-range-of-entries)
>   - [Querying Time Series](#querying-time-series)
>     - [Results in Graph View](#results-in-graph-view)
>   - [Incremental Time Series](#incremental-time-series)
>     - [Creating a new Incremental Time Series (by Creating its First Entry)](#creating-a-new-incremental-time-series-by-creating-its-first-entry)
>     - [Editing an Incremental Time Series Entry](#editing-an-incremental-time-series-entry)

## Document View

![Time Series - Document View](https://docs.ravendb.net/assets/images/document-time-series-3daf5b50cf50cff13b0c687947210b9f.png)

> **Warning:** Actions {#actions}
>
> 1. To view a document's time series, open its [document view](https://docs.ravendb.net/6.2/studio/database/documents/document-view.md)
>    and click the time series tab on the right.
> 2. Click 'Add Time Series' to create a new time series [see more below](#create-new-time-series-by-creating-its-first-entry).
> 3. Click to view and modify time series data.

> **Info:** Info {#info}
>
> - A. Time series info:
>   - B. **Name**
>     > **Note**
>     >
>     > [Incremental Time Series](#incremental-time-series)
>     > names always begin with `INC:`  
>     > E.g. **INC: Downloads** in the first time series listed above.
>   - C. **Number of entries**
>   - D. **Range of time** from first to last entry

## Time Series View

![Time Series View](https://docs.ravendb.net/assets/images/time-series-view-8e551d0f840da29e60b926cfcd95dd68.png)

> **Warning:** Actions {#actions-1}
>
> 1. Click to select another time series.
> 2. Click to add a new entry to this time series (StockPrices), or click the dropdown to create a [new time series](#create-new-time-series-by-creating-the-first-entry).
> 3. Delete all entries from a specified time range.
> 4. Edit entry.

> **Info:** Info {#info-1}
>
> 1. Time series entry info:
>    - Timestamp
>    - Numerical data (1-32 `double` values)
>    - Optional tag `string`

### Create new Time Series (by Creating its First Entry)

- A time series is created upon the creation of its first entry (and deleted
  once all entries have been deleted).

- Click the **Add Time Series** button from the
  [Document View](#document-view)
  to create the time series' first entry.

![Add Time Series](https://docs.ravendb.net/assets/images/new-time-series-4c7a98d16138c75d413e0bbd2bbcc9b9.png)
![Add Time Series Entry](https://docs.ravendb.net/assets/images/new-entry-5501c0eebc5cc5fe33d78c5eab345196.png)

> **Warning**
>
> 1. **Time Series Type**
>    - **Diasble** to create a **non-incremental time series**.  
>      (Learn now to create an incremental time series [here](#incremental-time-series))
> 2. **Time Series Name**
>    - Enter time series' name.
>    - Name cannot start with 'INC:' as this prefix is reserved for incremental time series.
> 3. **Entry Timestamp**
>    - Select a [timestamp](https://docs.ravendb.net/6.2/document-extensions/timeseries/overview.md#timestamps) for the new entry.
> 4. **Tag** (Optional)
>    - Optionally give the entry a [tag](https://docs.ravendb.net/6.2/document-extensions/timeseries/overview.md#tags).
> 5. **Values**
>    - Add one or more numerical [values](https://docs.ravendb.net/6.2/document-extensions/timeseries/overview.md#values) (up to 32 values).  
>      ![Named Values](https://docs.ravendb.net/assets/images/named-values-14105020adde1e91517eb6103e9f3f33.png)
>    - Time series entry values can be given meaningful names rather than labels like Value #0 and Value #1.  
>      To set entry values' names, use Studio's [Time Series Settings View](https://docs.ravendb.net/6.2/studio/database/settings/time-series-settings.md#add-or-edit-time-series-configuration).

### Editing an Entry

- Click the **Edit Item** button from the
  [Time Series View](#time-series-view)
  to edit a time series' entry.

![Edit Time Series](https://docs.ravendb.net/assets/images/edit-time-series-17f59376736f311286616a617b5b780c.png)
![Edit Time Series Entry](https://docs.ravendb.net/assets/images/edit-time-series-entry-6713ecd4a81232df581c607cb6ef5d2e.png)

> **Warning**
>
> 1. Edit the optional tag.
> 2. Edit a numerical value.
> 3. Delete value.
> 4. Add an additional value (up to 32 values).

### Deleting a Range of Entries

- Click the **Delete Range** button from the
  [Time Series View](#time-series-view)
  to delete a range of time series entries.

![Delete Range Button](https://docs.ravendb.net/assets/images/delete-range-button-db1e5a0085157af2bc6409981c45094c.png)
![Delete Range](https://docs.ravendb.net/assets/images/delete-range-e48537d1adb6b42c921a4a6558338f5e.png)

> **Warning**
>
> To specify a range of time series entries:
>
> 1. **Start Date**  
>    Check **Use minimum** to use the first entry's timestamp as the start of the range,
> 2. **End Date**  
>    Check **Use maximum** to use the last entry's timestamp as the end of the range.
>
> - For either option, you can click the input bar and specify some other date in the
>   date & time dialog shown below.

![Delete Range - Pick Date and Time](https://docs.ravendb.net/assets/images/delete-range-2-1addee88f92eb080bcde57ead7cd4279.png)

## Querying Time Series

![Time Series Query](https://docs.ravendb.net/assets/images/time-series-query-8ace4fff3407fe4f0d2abba9fa26f221.png)

> **Warning:** Actions {#actions-2}
>
> 1. Enter your RQL query in the query box.  
>    Depicted here is a query to get all the **StockPrices** time series values from documents in the Companies collection.  
>    Learn more about time series queries [here](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/overview-and-syntax.md).
>
>    > **Note**
>    >
>    > Make sure that the time series Name is placed within double quotes (e.g. "StockPrices",
>    > "INC:Downloads", etc.), so special characters like ":" would not interfere with the query.
>
> 2. Click to run the query.

> **Info:** Info {#info-2}
>
> 1. Query Results - A list of time series that satisfy the query, with:
>    - The ID of the associated document.
>    - Number of entries and time range.

![Time Series Query - Actions](https://docs.ravendb.net/assets/images/time-series-query-actions-ca5afb85d14623931b67a12a85e2c3b8.png)

> **Warning**
>
> 1. Click to open a tab with the time series query results shown in a table.  
>    ![Time Series Query Results Table](https://docs.ravendb.net/assets/images/query-results-table-e662b1ccc3f66e8317682e8c035d6d31.png)
> 2. Click to open a tab with the time series query results shown in a graph (see below).
> 3. Multiple documents selection  
>    ![Multiple Selection](https://docs.ravendb.net/assets/images/multiple-selection-eae869450b8c6d67eedd97348d6a8974.png)
>    - A. Select multiple documents to plot their time series.
>    - B. Click to view the selected documents' time series results in a unified graph.  
>      ![Unified Graph](https://docs.ravendb.net/assets/images/unified-graph-551d9e3a1c1548edea22d034971b351f.png)

### Results in Graph View

![Time series results in a graph](https://docs.ravendb.net/assets/images/time-series-graph-info-099d33b54fedce00c8d342046e707cfb.png)

> **Info**
>
> 1. A graph of time series results in a selected time frame.
> 2. A graph showing all the time series results over time.
> 3. The selected time frame.
> 4. A legend of time series entries' values.  
>    The entry values names are set in Studio's **Settings > Time Series** view.

![Time series results in a graph - Actions](https://docs.ravendb.net/assets/images/time-series-graph-actions-c6928db665a979f0bb7613131d5992e9.png)

> **Warning**
>
> 1. Click to go back to the query results tab.
> 2. Display tabs with graph or table results.
> 3. Drag or resize the selected time frame to view the corresponding results.
> 4. Hover your mouse over the graph to view the data of one particular entry.
> 5. Toggle viewing points or a continuous line.
> 6. Check/Uncheck to plot or hide time series entries' values on the graph.

## Incremental Time Series

- **Incremental Time Series** are time series whose values
  behave as [counters](https://docs.ravendb.net/6.2/document-extensions/counters/overview.md).

- Similar to Counters, an incremental-time-series value can be increased/decreased by some
  delta on any node.  
  Each node manages and stores its own accumulated local changes per value.

- Simultaneous updates to the same value from multiple nodes do not create any conflict.  
  The value's total contents is simply the accumulation of that value's contents stored
  per node in the cluster for the same timestamp.

- This is opposed to non-incremental time series, where a value that is modified
  is intended to replace the existing value's contents on all other nodes.

- learn more in [Incremental Time Series -vs- Non-incremental Time Series](https://docs.ravendb.net/6.2/document-extensions/timeseries/incremental-time-series/overview.md#incremental-time-series--vs--non-incremental-time-series).

### Creating a new Incremental Time Series (by Creating its First Entry)

- An incremental time series is created upon the creation of its first entry (and deleted
  once all entries have been deleted).

- Click the **Add Time Series** button from the
  [Document View](#document-view)
  to create the incremental time series' first entry.

![Add Time Series](https://docs.ravendb.net/assets/images/new-time-series-4c7a98d16138c75d413e0bbd2bbcc9b9.png)
![Add Incremental Time Series Entry](https://docs.ravendb.net/assets/images/new-incremental-entry-9aff9d3a98b4742a87cd87ae8b5a5cc9.png)

> **Warning**
>
> 1. **Time Series Type**
>    - Enable to create an Incremental time series.
> 2. **Time Series Name**
>    - Enter time series' name.
>    - Incremental time series names **must** start with **INC:** (in either upper
>      or lower case characters).
> 3. **Entry Timestamp**
>    - Select a [timestamp](https://docs.ravendb.net/6.2/document-extensions/timeseries/overview.md#timestamps) for the new entry.
> 4. **Values**
>    - Add one or more numerical [values](https://docs.ravendb.net/6.2/document-extensions/timeseries/overview.md#values) (up to 32 values).  
>      ![Named Values](https://raw.githubusercontent.com/ravendb/docs/main/versioned_docs/version-6.2/studio/database/document-extensions/assets/incremental-named-values.png)
>    - Time series entry values can be given meaningful names rather than labels like Value #0 and Value #1.  
>      To set entry values' names, use Studio's [Time Series Settings View](https://docs.ravendb.net/6.2/studio/database/settings/time-series-settings.md#add-or-edit-time-series-configuration).

### Editing an Incremental Time Series Entry

- Click the **Edit Item** button from the
  [Time Series View](#time-series-view)
  to edit a time series' entry.

![Edit Time Series](https://docs.ravendb.net/assets/images/edit-incremental-time-series-53a725ffe9a781e59d461edaf7ee2c55.png)
![Incrementall Time Series Entry Accumulated Value](https://docs.ravendb.net/assets/images/edit-incremental-time-series-entry-unified-dbd4bad8af0a3256f6ba516797fec1c1.png)

> **Warning**
>
> 1. **Show values per node**
>    - Enable to view the value's contents distribution per cluster node (see below).  
>      When disabled, only the total value (the value's total contents) is visible.
> 2. **Values**
>    - **Total Value**  
>      This is the value's total contents, which is the accumulation of this value's contents from all cluster nodes.
>    - **Increment By**  
>      The number you enter here is the **delta** that will be added to the value's
>      contents on the current node.  
>      Enter a positive number to increase the value or a negative number to decrease it.  
>      The change in the value's total contents will be visible after you click the Save button.
> 3. **Add Value**  
>    Add an additional value (up to 32 values).
> 4. **Save**  
>    Click to save your changes.

![Incrementall Time Series Entry Node Values](https://docs.ravendb.net/assets/images/edit-incremental-time-series-entry-values-8b3a2b51ec56e0edd99742cd4129a10b.png)

> **Warning**
>
> 1. **Show values per node**
>    - Enable to view the value's contents distribution per cluster node.
> 2. **Values**
>    - **Total Value**  
>      This is the value's total contents, which is the accumulation of this value's contents from all cluster nodes.
>    - **Increment By**  
>      The number you enter here is the **delta** that will be added to the value's
>      contents on the current node.  
>      Enter a positive number to increase the value or a negative number to decrease it.  
>      After clicking **Save**, both the current node and the total value will be updated
>      with the new accumulated value.  
>      The value will be modified only when you click the **Save** button.
> 3. **Add Value**  
>    Add an additional value (up to 32 values).
> 4. **Save**  
>    Click to save your changes.
