Historizing Dataset, Document, and Array Tags in Ignition 8.1.4

Historizing Dataset, Document, and Array Tags in Ignition 8.1.4

The Inductive Automation Ignition 8.1.4 Tag Historian does not natively store historical values for tags whose data type is Dataset, Document, or top-level Array. When history is enabled on a tag of these types, no rows are inserted into the sqlth_data_X_X history partition tables, and the On Change sample mode records NULL for the value column. The limitation is rooted in the column definitions of the historian's partition schema, not in tag configuration. This reference covers the cause, the verification procedure, and the field-proven workarounds used to capture these types in an external database or in serialized string history.

1. Overview of the Ignition Tag Historian

The Tag Historian writes timestamped tag values into a relational database (MySQL, MSSQL, PostgreSQL, or Oracle) through a fixed partition schema. The Ignition 8.1 User Manual documents the schema in the sqlth_data_X_X Ignition Database Table Reference. The principal tables are:

Each sqlth_data_X_X table contains a fixed set of typed columns. The value columns for each supported JDBC type are pre-allocated:

*Long values are written to either intvalue or floatvalue depending on driver and range.

2. Why Datasets, Documents, and Arrays Fail to Historize

A Dataset in Ignition is a tabular in-memory object (rows × columns of typed values), produced by SQL queries, calculations, and component bindings. Its binary representation does not map to a single primitive JDBC type. The Tag Historian's sqlth_data_X_X schema has no column to receive it, and the history subsystem explicitly rejects the value (writing NULL) instead of coercing.

A Document in Ignition is a structured object (a property bag with typed fields). Like Dataset, it is not a primitive type and is rejected at the history write boundary in the same way.

An Array exhibits a different behavior: the historian partially supports it by splitting the array into one new internal tag per subscript, each with its own tag_id and its own row stream in sqlth_data_X_X. The parent array tag itself stores no history rows, but each arrayTag[0], arrayTag[1], ... gets its own history record. The split is automatic and cannot be disabled from the Designer.

3. Supported Data Types for Tag History

This behavior has been documented and is consistent across the 8.0.x, 8.1.x, and 8.2.x release lines. See the Array and Dataset Tags video at Inductive University for the underlying data structures, and the Ignition 8.1 User Manual for the historian schema.

4. Verifying the Limitation in Your Project

1. Open the Tag Browser and locate the offending tag.
2. Confirm the Data Type field shows Dataset, Document, or Array.
3. Right-click the tag and select Tag History. Confirm History Enabled is checked and the tag has a valid tag_id in sqlth_tags.
4. Open your database client and run:

   SELECT tagid, time, intvalue, floatvalue, stringvalue, dataintegrity
   FROM sqlth_data_1_1
   WHERE tagid = <your_tag_id>
   ORDER BY time DESC
   LIMIT 50;

5. Expected result for Dataset / Document: every value column is NULL; only time, tagid, and dataintegrity are populated.
6. Expected result for Array: the parent tag returns no rows; query the auto-generated subscript tag IDs to see history.

5. Workarounds for Datasets

Because Dataset cannot be stored in sqlth_data_X_X, use one of the following patterns. All three bypass the in-built historian's column contract while preserving time-series semantics.

5.1 Pattern A: Serialize to a String Memory Tag

Bind a String memory tag to the Dataset via a Tag Expression or property-change script that calls system.dataset.toJSON(). Set the destination tag's data type to String and enable history on that string tag. The stringvalue column accepts the JSON serialization and the row is fully historized.

# Property-change script on the original Dataset tag
from com.inductiveautomation.ignition.common import TypeTags

if event.propertyName == "value":
    payload = system.dataset.toJSON(event.newValue)
    system.tag.writeBlocking(
        ["[default]History/DatasetAsJSON"],
        [payload]
    )

Reconstruct on read with system.dataset.fromJSON(). The string tag is queryable, replays the JSON, and uses the standard historian for retention and partitioning.

5.2 Pattern B: Transaction Group with DB Pen

Configure a Transaction Group with the Dataset as the source. The DB Pen block expands the Dataset columns into individual destination columns or into a single JSON column in a user-defined table. This bypasses the Tag Historian entirely and writes to a custom table you control. Configure Trigger as Tag Value Changed on the parent Dataset tag.

5.3 Pattern C: Gateway Timer Script with system.db

A Gateway Timer Script running every N seconds reads the Dataset, converts it to rows, and writes via system.db.runPrepUpdate(). This gives full control over schema, indexing, and partitioning:

ds = system.tag.readBlocking(["[default]Plant/RecipeTable"])[0].value
headers = ["Recipe", "Setpoint", "Tolerance"]
tstamp = system.date.format(system.date.now(), "yyyy-MM-dd HH:mm:ss")
for row in system.dataset.toPyDataSet(ds):
    system.db.runPrepUpdate(
        "INSERT INTO recipe_history (ts, name, sp, tol) VALUES (?, ?, ?, ?)",
        [tstamp, row[0], row[1], row[2]],
        "MySQL"
    )

6. Workarounds for Documents

Documents are property bags. The same three patterns apply:

• Serialize via system.util.jsonEncode(document) to a String tag for historian storage.
• Transaction Group with explicit field mapping (each Document key becomes a destination column).
• Custom DB write script iterating over document.props.

When reconstructing, system.util.jsonDecode() returns a usable Python dict, and the Document class can be rebuilt from it if needed.

7. Workarounds for Arrays

The historian splits arrays into subscript tags automatically. To get useful history:

1. Verify the array tag is a standard array, not a Dataset (use Tag Diagnostics in the Designer to confirm).
2. Enable history on the array tag. Each arrayTag[N] becomes its own history record automatically. The new internal tag IDs are visible in the Tag Browser under the array tag.
3. Reconstruct the historical array at a point in time with a query that joins the subscript tag IDs:

   SELECT a.time, a.floatvalue AS ph, b.floatvalue AS temp, c.floatvalue AS sp
   FROM sqlth_data_1_1 a
   JOIN sqlth_data_1_1 b ON a.time = b.time
   JOIN sqlth_data_1_1 c ON a.time = c.time
   WHERE a.tagid = <subscript0_id>
     AND b.tagid = <subscript1_id>
     AND c.tagid = <subscript2_id>
   ORDER BY a.time DESC
   LIMIT 1000;

If the array contains complex values, apply the JSON-serialization pattern from section 5.1 to each subscript.

8. Tag History Configuration Reference

History is configured at Gateway → Config → Tags → [provider] → [tag] → History tab. Settings are persisted in the taghistory Gateway table; the actual data lands in sqlth_data_X_X.

9. Diagnostics & Troubleshooting Matrix

10. Architecture Notes and Design Intent

The Tag Historian's design is intentionally narrow: a fixed set of typed columns optimized for high-throughput numeric and string writes at a fixed cadence. BLOB and VARBINARY storage were avoided to keep indexing, compression, partitioning, and replay simple. Datasets and Documents are designed as in-memory transport objects (produced by bindings, queries, and component calculations), not persistent storage primitives.

When you historize them, you serialize the object and write outside the historian's column contract. The string-value column is the documented escape hatch for opaque payloads, and Transaction Groups or custom Gateway scripts give full control over schema, indexing, and retention.

FAQ