Historian

The Historian module lets you log and retrieve tag history using a variety of storage options. When history is enabled on a tag, its values are stored through a configured historian provider. These providers include embedded options, external databases, and other storage types, each with different capabilities depending on your system’s needs. For a full overview of available providers, see the History Providers page.

Tag history can be displayed in charts and tables, or accessed via bindings, reports, and scripting.

How the Historian System Works

This section provides an overview of how the Historian system evaluates tag changes, stores them, and later retrieves those values.

Deciding When to Store

The system determines whether a sample should be stored based on sample mode, timer settings, and deadband evaluation.

When history is enabled on a tag, several checks occur. These are handled by components called actors. The key ones are sample mode, min/max timer, and deadband, which align with similarly named tag settings.

Sample mode

The system first detects value changes using the sample mode actor.

• Periodic and Tag Group modes evaluate storage at regular intervals.
• On Change mode triggers evaluation whenever the tag changes.
• On Change mode also includes a timer that ensures a sample is collected if the tag has stayed static longer than the configured maximum time.

Tags are evaluated together if they share the same tag provider, history provider, and rate. Tags with different sample rates are evaluated independently.

Min/Max timer

The min/max timer checks if the minimum or maximum time between samples has been met.

• If the minimum time hasn’t elapsed, the new value is discarded.
• If the maximum time is exceeded, a sample is collected, even if the deadband is not exceeded.

If using a Tag Group mode, maximum time values on the Tag Group override those on the tag unless left at default.

Deadband

The deadband actor compares the new value to the previous one. If the change exceeds the configured deadband, the system stores the new value.

Storing a Value

When a sample is collected, it’s added to a history set. A history set contains a collection of samples from tags that share a history configuration. Periodic sample mode tags are grouped into a special "exempt" group.

The set is then sent to the Store and Forward system or written directly to disk, depending on the historian provider.

Memory buffer

When a history set reaches the memory buffer, it checks the current cache state. If no backlog is detected, the system immediately writes the data to the database sink. But if other sets are waiting to be written, the system routes this set to disk to wait its turn.

Disk store

The disk store holds records temporarily and separates them based on their condition:

• The local cache holds data that’s ready to be written once the configured write time or size threshold is reached.
• The quarantine area stores records that couldn’t be written successfully due to issues like database errors. These entries remain in quarantine until the user intervenes or the system retries.

Database sink

The database sink is responsible for the final write to the database and performs the following tasks:

• Bundles records from the history set into a single transaction.
• Performs the insert using a prepared query.
• Caches tag identifiers in memory so repeated inserts don’t require lookup queries.
• Retries failed records one at a time before sending them to quarantine.

Querying Historical Data

Historical values are stored in a database, but you should use Ignition’s built-in tools to query them. These tools handle time alignment, interpolation, deduplication, and aggregation. The QuestDB-based historian supports native aggregation directly in the database engine.

You can query history using:

• Tag History bindings in Perspective and Vision

• Data sources in the Report Data tab of the Reporting module.

• Scripting functions under the system.historian namespace:

  • system.historian.queryValues
  • system.historian.storeDataPoints
  • system.historian.queryMetadata
  • system.historian.storeAnnotations

Deprecated

Custom Tag History Aggregates are deprecated and only work with the legacy system.tag.queryTagHistory and system.tag.queryTagCalculations functions, which are also deprecated. These features still work for older projects but aren’t supported by the newer system.historian API and aren’t recommended for new development.

You can still view the original guide in the Deprecated Pages section.

Request Origin

When data is requested, the system first identifies where the request came from. Queries from Perspective and Vision components often use caching to speed up repeated access. These requests are routed through a cache. Queries from scripting functions like system.historian.queryValues skip caching entirely and always pull directly from the database.

Cache

If the request supports caching, the system checks for matching data already stored in the cache. If all requested data is present, the system moves directly to processing. If the cache is missing values, the system retrieves just the missing data from the database.

Query Data from Database

The system prepares and executes one or more queries to gather the historical records. Since the Historian stores data in partitioned tables, this often involves checking which partitions fall within the requested time window.

If pre-processed partitions are enabled and the query qualifies, the system uses them instead of raw data tables. This significantly improves performance, but is not supported by the Internal Historian - QuestDB.

Processor

The processor combines any cached and queried records into a unified dataset. It then slices the data based on the sample size and applies aggregation or interpolation where needed. For instance, if a query spans 10 minutes and requests 10 values, the processor creates ten 1-minute slices and evaluates the values in each.

Store in Cache

If the query originated from a component that uses caching, the final result is stored in the cache after processing. Otherwise, the result is returned immediately to the requesting component or script.

Display Historian Data

Both Vision and Perspective include Chart components designed for displaying historical tag data. Drag tags directly onto these charts to create pens. They support features like multiple axes, moving averages, subplots, and runtime controls for adjusting trends.

• Easy Chart in Vision

  

• Power Chart in Perspective

  

Store and Forward

The Store and Forward system stages historical data before writing it to the Internal Historian - SQLite or external SQL historians. This buffering protects against data loss if the database is temporarily unavailable.

• The Internal Historian - SQLite and external SQL providers always route historical data through Store and Forward. If the database cannot be reached, Store and Forward will temporarily queue records until the connection is restored.

• The Internal Historian – QuestDB writes directly to disk using a write-ahead log (WAL) and does not use Store and Forward.

Data Storage

Each historical record includes the tag value, quality, and timestamp (to the millisecond). Whether a value is stored depends on the tag’s sample mode, deadband settings, and min/max time configuration.

For technical details on the tables used by the Historian, see the Ignition Database Table Reference.