Each time series belongs to, or extends, one particular document. The
document and the time series reference each other through:
- A reference to the time series in the document's metadata.
The time series' name is kept in the document's metadata.
The time series' data is stored in a separate location.
- A reference to the document in the time series data.
Time Series Entries
Each time series entry is composed of:
||The time of the event or data represented by the entry. Time is measured up to millisecond resolution.
||An optional tag for an entry. Can be any string up to 255 bytes. Possible uses for the tag: descriptions or metadata for individual entries; storing a document id, which can then be referenced when querying a time series. This is the only component of the entry that is not numerical.
||An array of up to 32
Doubles with higher precision - i.e. more digits after the decimal point,
are much less compressible.
In other words,
1.672 takes up more space than
- When a document has one or more time series, RavenDB automatically adds
HasTimeSeries flag in the document's metadata under
"my time series"
- When all time series are deleted from a document, RavenDB
automatically removes the flag.
At the server storage level, time series data is divided into segments.
Each segment contains a number of consecutive entries from the same time series.
Segments Size and Limitations
- Segments have a maximum size of 2 KB.
What this limit practically means, is that a segment can only contain
up to 32k entries and time series larger than that would always be stored
in multiple segments.
- In practice, segments usually contain far less than 32k entries,
depending on the size of the entries (after compression).
For example, in the Northwind sample dataset,
the Companies documents all have a time series called StockPrice.
These time series are stored in segments that have ~10-20 entries each.
- The maximum time gap between the first and last entries in a segment is
~24.86 days (
int.MaxValue milliseconds). Adding an entry that is further
than that from the first segment entry, would add it as the first entry
of a new segment. As a consequence, segments of sparsely-updated time series
can be significantly smaller than 2 KB.
- The maximum number of unique tags allowed per segment, is 127.
A higher number than that, would cause the creation of a new segment.
RavenDB automatically stores and updates aggregate values in each segment's header,
that summarize commonly-used values regarding this segment, including -
- The segment's First value
- The segment's Last value
- The segment's Max value
- The segment's Min value
- The segment's Count of values
- The segment's values Sum
The existence of aggregate values makes it worthwhile to reference individual
segments in indexes and queries.
When segment entries store multiple values, e.g. each entry contains a Latitude value
and a Longitude value, the six aggregate values are kept for each value separately.
Time series data is stored using a format called Gorilla compression.
On top of the Gorilla compression, the time series segments are compressed
using the LZ4 algorithm.