---
title: "Tags"
description: "Overview of tags and data points in Koios"
source_url: https://ai-ops.com/docs/tags/introduction
---

# Tags

A **tag** in Koios represents an individual data point — a temperature reading, a motor speed, a pressure setpoint, a database column value, or a calculated result. Tags are where real data enters and leaves the platform: AI models read from input tags and write predictions to output tags, trends chart tag values over time, and events fire when tag states change.

Tags can get their value from three different sources — a connected device, a computed expression, or an in-memory write from a service. See [Tag Source Types](#tag-source-types) below for details.

## Input vs Output

Every tag has a **usage** that determines how Koios interacts with it:

| Usage | Direction | Description |
|-------|-----------|-------------|
| **Input** | Read from device | Koios reads this tag's value from the device on each scan cycle. This is the default for most tags — sensor readings, status registers, database values. |
| **Output** | Read and write | Koios can write values _back_ to the device through this tag. Output tags receive values from AI models, mappings, or components, and push them to the device on the next scan. |

> [!NOTE] Output tags still read
> Output tags read their current value from the device on every scan, just like input tags. The difference is they can also _receive_ a value to write back. This means you can see both the output value (what Koios wants to write) and the current value (what the device is actually reporting).

> [!TIP] Usage is fixed for expression and in-memory tags
> Expression tags are always **read-only** — they compute their value from a formula and have no device to write to. In-memory tags are always **read/write** — they receive output values from services (AI models, mappings, components) which write through them. Only device tags let you choose between input and output.

## Tag Lifecycle

Tags follow a straightforward lifecycle:

1. **Create** — add a tag and configure its settings (device and protocol fields for device tags, an expression for expression tags, or just general settings for in-memory tags)
2. **Enable** — activate the tag so it begins collecting or computing values
3. **Live** — the tag's value updates on each scan or evaluation, is recorded to the time-series database, and is available to models, trends, and the rest of the platform
4. **Stopped / Failed** — a tag stops when disabled (or when its parent device stops, for device tags). It enters a failed state if it encounters an error.

> [!TIP] Device tags follow their device
> A device tag can only collect data when its parent device is enabled and running. If the device is stopped, all of its tags stop too — regardless of each tag's own enabled setting. Expression and in-memory tags have no parent device, so they operate independently.

## Tag Status

Like devices, every tag has a real-time status:

| Status | Meaning |
|--------|---------|
| **Running** | The tag is actively producing values — being scanned from a device, evaluated from an expression, or relayed from a service |
| **Stopped** | The tag is disabled (or its parent device is disabled, for device tags) |
| **Failed** | An error occurred — check the error code and message for details |

When a device tag fails, the parent device may continue scanning its other tags normally. Tag errors are isolated — one bad tag doesn't bring down the whole device.

## What You See on a Tag

### Tag List

The tag list table shows all tags across the platform. Key columns include:

- **Status** — colored icon showing running, stopped, or failed
- **Name** — the tag's unique name
- **Source** — device, expression, or in-memory
- **Device** — the parent device (device tags only)
- **Value** — the current live value
- **Units** — engineering units (°C, PSI, RPM, etc.)
- **Usage** — input or output icon

You can filter by device, protocol, or search by name. Tags can be enabled, disabled, duplicated, or deleted in bulk.

### Tag Detail

Clicking a tag opens its detail page with four tabs:

- **Overview** — live status, current value with sparkline chart, device info, and recent events
- **Configuration** — all editable settings (general, protocol-specific, and advanced)
- **Parameters** — read-only table of every tag field, organized into live data, config, and protocol sections
- **Cross References** — shows where this tag is used (AI models, mappings, components, etc.)

## Configuration

### General Settings

| Setting | Description | Default |
|---------|-------------|---------|
| **Name** | Unique identifier for the tag | — |
| **Description** | Optional note about the tag's purpose | — |
| **Enabled** | Whether the tag is actively collecting or computing values | Off |
| **Usage** | Input (read-only) or Output (read/write) | Input |
| **Decimal Places** | How many decimal places to show for numeric values (0–3) | 1 |
| **Units** | Engineering units displayed alongside the value (e.g. °C, PSI) | — |
| **Range Min / Max** | Expected value range — used for normalization in AI models and display scaling | 0–100 |

### Protocol-Specific Settings

Device tags have additional configuration that depends on their protocol. These settings tell Koios _where_ to find the data point within the device:

| Protocol | Key Settings |
|----------|-------------|
| **OPC-UA** | Namespace, node identifier, identifier type, data type |
| **Modbus TCP** | Register address, register type, data type, byte/word swap |
| **EtherNet/IP (Logix)** | Logix tag name, tag type |
| **EtherNet/IP (Generic CIP)** | Assembly instance, byte offset, data type, bit number |
| **SOAP (RDM)** | RDM device address, RDM parameter |
| **REST (BOSS)** | BOSS device address, variable code, variable type |
| **Microsoft SQL** | SQL query |
See the protocol-specific tag creation guides for details on each.

### Advanced Settings

| Setting | Description | Default |
|---------|-------------|---------|
| **Value Mapping** | Maps raw device values to numeric outputs using ordered match rules | Off |
| **Test Output** | For output tags — write a fixed test value instead of the live output, useful for commissioning | Off |
| **Write Always** | For output tags — retry the last output value on every scan, even if no new value has been received | Off |
| **Redundancy** | Read from a device set instead of a single device, enabling automatic failover | Off |

### History Compression

By default, every tag uses the global compression settings configured on the [Data Retention](https://ai-ops.com/docs/system/retention.md#history-compression) page. Global compression uses **Swinging Door Trending (SDT)** to discard values that don't meaningfully change the trend, reducing storage consumption while preserving the shape of the data.

If a specific tag needs different compression behavior, the **History Compression** section on the Configuration tab provides an **Override global compression settings** toggle. When enabled, three tag-specific settings appear:

| Setting | Description | Default |
|---------|-------------|---------|
| **Compression Enabled** | Whether to compress this tag's history | On |
| **Compression Deviation** | Maximum deviation from the trend line, as a percentage of the tag's range | 0.1% |
| **Maximum Time Between Samples** | Force a sample after this many seconds regardless of compression | 60s |

When the override is off, the tag follows whatever the global settings are — a link on the Configuration tab takes you directly to the Retention page to view or change them.

> [!TIP] When to use per-tag overrides
> Most tags work well with the global defaults. Use per-tag overrides when a tag has specific fidelity requirements — for example, a critical control signal that must record every change, or a slow-moving temperature sensor that can tolerate aggressive compression. Overrides are fully independent: changes to the global settings have no effect on overridden tags.

> [!WARNING] Range affects compression
> SDT calculates the tolerance band as a percentage of the tag's **Range Min / Max**. If the range is left at the default 0–100 but the tag's actual values span a much narrower band (e.g. 0–1 or 4–20 mA), the tolerance band will be wider than the signal and almost nothing gets recorded. Always set each tag's range to match the actual expected value range. See [Tag Range and Compression](https://ai-ops.com/docs/system/retention.md#tag-range-and-compression) for details.

## Tag Source Types

Every tag has a **source type** that determines where its value comes from. You choose the source type when creating a tag.

| Source Type | Description | Has Device? | Usage |
|-------------|-------------|-------------|-------|
| **Device** | Reads and writes values from a connected industrial device (OPC-UA, Modbus, etc.) | Yes | Input or Output |
| **Expression** | Computes its value from a formula that references other tags | No | Read-only |
| **In Memory** | Receives its value from a service — the predict engine, mapping service, or component engine | No | Read/Write |

### Device Tags

The most common type. A device tag belongs to a device and inherits its protocol. The device handles the connection, and the tag defines _what_ to read or write within that connection — an OPC-UA node, a Modbus register, an EtherNet/IP controller tag, a SQL query, and so on.

### Expression Tags

Expression tags compute their value from a formula evaluated by the **Expression Evaluator** service. Expressions can reference:

- **Tag values and status** — the live value, status, or error code of any other tag
- **Device status** — whether a device connection is running or failed
- **Model status** — whether an AI model is running or failed
- **Binding values** — the raw prediction value from a model output binding

This makes expressions useful for more than simple math — you can build logic that reacts to the health of devices or models, not just their data. Expressions support arithmetic, comparison, and logical operators, plus built-in math and statistical functions.

Expressions are evaluated in one of two ways:

- **Reactive** — when any referenced tag's value changes, the expression re-evaluates immediately (within milliseconds)
- **Timer-based** — if the expression has no reactive tag dependencies, it evaluates on a configurable interval (the **Evaluation Rate** field)

See [Expression Tags](https://ai-ops.com/docs/tags/expressions.md) for the full syntax reference.

### In-Memory Tags

In-memory tags historize values written by the **predict engine**, **mapping service**, or **component engine**. These services write an `output_value` to the live data cache when they produce a result (e.g. a model prediction or a mapped value). Without an in-memory tag, that output value lives only in the cache and is never recorded.

The **Expression Evaluator** service monitors in-memory tags and relays `output_value` to the tag's live `value`, writing each update to the time-series database for historical storage. This relay happens two ways:

- **Event-driven** — the producing service publishes a notification after writing, and the relay happens within milliseconds
- **Timer fallback** — a periodic check (default 10 seconds) catches any missed notifications

In-memory tags also provide:

- **Status monitoring** — the tag shows running/stopped/failed status like any other tag
- **Stale detection** — if the source service stops writing, the tag enters a failed state after a configurable timeout (default 60 seconds), with a clear error message showing how long ago the last write occurred
- **Waiting state** — before the source service writes for the first time, the tag shows a running status with an informational "Waiting for output value" message

> [!TIP] When to use in-memory tags
> Use an in-memory tag when you need to **chart in trends** or **monitor the health** of a value produced by the predict engine, mapping service, or component engine. If you only need the live value in the cache (for example, as an intermediate step in a pipeline), you don't need an in-memory tag — the output value is already available in the live data cache without one.

## Output Conflicts

When multiple sources (an AI model, a mapping, and a component) all try to write to the same output tag, Koios flags an **output conflict** on the tag's overview page. This is a warning — only one source's value will be written per scan. Review the tag's cross references to understand what's writing to it and resolve any unintended overlaps.

## Key Concepts

| Concept | Description |
|---------|-------------|
| **Value** | The tag's current reading — from a device, a computed expression, or a service write |
| **Quality** | For OPC-UA tags, the server-reported data quality (Good, Bad, Uncertain) |
| **Timestamp** | When the value was last updated |
| **Range** | The expected min/max values — used by AI models for normalization and compression band calculation |
| **Compression override** | Per-tag compression settings that override the global defaults |
| **Value mapping** | An ordered list of match rules that convert raw values to numeric outputs |
| **Test output** | A mode that writes a fixed value for commissioning output tags |
| **Expression** | A formula that computes a tag's value from other tags |
| **Cross references** | A view of everything that reads from or writes to a tag |

## What's Next

- [Creating a Tag](https://ai-ops.com/docs/tags/creating-getting-started.md) — step-by-step guide to adding a new tag
- [Expression Tags](https://ai-ops.com/docs/tags/expressions.md) — syntax reference for expression formulas
- [Value Mapping](https://ai-ops.com/docs/tags/value-mapping.md) — mapping raw device values to numeric outputs
- [Troubleshooting a Tag](https://ai-ops.com/docs/tags/troubleshooting.md) — diagnosing errors and testing tag reads