Enabling Historization
Historization records the state of time series data over time. When enabled, every write operation creates a new historical layer rather than overwriting the existing data. This allows reading data as it existed at any previous point in time.
Enabling Historization on a Time Series
Section titled “Enabling Historization on a Time Series”Historization is disabled by default. To enable it, set preserveHistoricData to true when creating or updating a time series. Historization data can only be stored if preserveAuditLog is activated as well.
Enable historization on a time series
Section titled “ Enable historization on a time series”Request
POST /repositories/{repository}/timeSeriesRequest Body
{ "name": "test10", "cyclic": true, "function": 2, "interval": { "type": 3, "multiplier": 1 }, "preserveHistoricData": true, "preserveAuditLog": true}Error response for historization without audit logs
Section titled “ Error response for historization without audit logs”Response
{ "title": "HK15115", "status": 400, "detail": "An error occurred while attempting to validate the \\\"PreserveHistoricData\\\" property of a time series for storage:\\nUsing historic data.requires the preservation of audit logs..", "traceId": "00-a7fca96c2f2657aaf5206e27ab808442-cae4c1dc1b0f382c-00"}Writing Historical Data
Section titled “Writing Historical Data”When historization is enabled, every POST to the data endpoint automatically creates a new historical record. No additional parameters are needed for a standard write — the current timestamp is used as the historic date.
To write data at an explicit historic date (e.g., for backfilling or corrections), include the quotationDateTime query parameter:
Write historical data with an explicit date
Section titled “ Write historical data with an explicit date”POST /repositories/{repository}/timeSeries/{timeSeries}/data?quotationDateTime=2024-06-15T10:00:00ZThe body is identical to a normal data write operation.
Reading Historical Data
Section titled “Reading Historical Data”To read data as it existed at a specific point in time, use the historicDateTime query parameter. The response contains the data as it was recorded up to and including the specified value. If it falls between two write timestamps, the state at or before that time is returned.
GET /repositories/{repository}/timeSeries/{timeSeries}/data?from=2024-01-01&to=2024-02-01&historicDateTime=2024-06-15T10:00:00ZRetrieving Quotations
Section titled “Retrieving Quotations”Quotations are the individual historic versions of the data. To retrieve the available quotation timestamps for a period:
GET /repositories/{repository}/timeSeries/{timeSeries}/data/quotations| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
from |
string |
— | ✓ | Start of the data period (ISO 8601). |
to |
string |
— | ✓ | End of the data period (ISO 8601). |
quotation.from |
string |
— | Lower bound of the quotation range (ISO 8601). | |
quotation.to |
string |
— | Upper bound of the quotation range (ISO 8601). | |
historicDateTime |
string |
— | Historic date for which to retrieve the data. This is referring to the audit timestamp (ISO 8601). | |
limit |
integer |
— | Maximum number of quotations to return. |
Retrieving Audit Logs
Section titled “Retrieving Audit Logs”The audit log records when data was written, updated, or deleted. To retrieve the audit log for a time series:
GET /repositories/{repository}/timeSeries/{timeSeries}/data/auditlogs| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
from |
string |
— | ✓ | Start of the data period for which to retrieve audit entries (ISO 8601). |
to |
string |
— | ✓ | End of the data period (ISO 8601). |
modifiedSince |
string |
— | Retrieve entries recorded after this historic date (ISO 8601). | |
modifiedUntil |
string |
— | Retrieve entries recorded before this historic date (ISO 8601). | |
limit |
integer |
— | Maximum number of entries to return. |