Time Series (timeseries)

Category: data | Form: | Symbol: Ts

Store and query time-indexed data

Time series storage for temporal data. Supports insert, range queries, downsampling, and retention policies. Backed by TimescaleDB (PostgreSQL extension). Attach to action elements to inject the connection.

Guide

Store and query time-indexed data

What It Does

Time Series is a data storage element for temporal, time-indexed values. It stores numeric data points — each with a metric name, a value, optional key-value tags, and an RFC3339 timestamp — and serves them back through time-range queries, time-bucketed aggregation, downsampling, and retention. It is a leaf data atom: it holds data (has_data: true) and other elements attach to it to read or write.

Storage is backed by TimescaleDB (a PostgreSQL extension). Each element gets a dedicated ts_{slug} hypertable inside the circle’s schema; when TimescaleDB is unavailable, it falls back to a plain Postgres table with a btree index. Multiple named metrics live co-located in one hypertable with tag-based partitioning, so a single Time Series element can hold many distinct series.

The executor (TimeseriesOpsExecutor) resolves all per-operation parameters — metric, time range, bucket, aggregate, retention interval — from each operation’s input at call time. It does not read configuration from the element’s spec; the only configurable property is a human-readable description. Attach this element to action elements to inject the connection so they can insert and query points.

Element Definition

Property	Value
Type	timeseries
Category	data
Form	atom
Storage backend	timescaledb
Symbol	Ts
Icon	timeline / #EF4444
Wirable	false
LLM role	data

Properties

Field	Type	Constraints	Description
description	string	max 512 chars	Human-readable description of what this timeseries element measures

No properties are required. Per-operation behavior is driven entirely by operation input, not by spec fields.

States

State	Meaning
provisioned	Initial state — element created, storage being prepared
active	Storage ready and serving operations
error	Backend error state

Capabilities

Capability	Description
time-range-query	Efficient time-range queries with optional metric and tag filters
aggregation	Time-bucketed aggregation (avg, sum, min, max, count) via time_bucket
downsampling	Time-bucketed query aggregation via date_trunc + GROUP BY. Returns aggregated points — a SQL query, not a TimescaleDB continuous-aggregate materialized view
retention-policy	Manual data expiry: a SQL DELETE WHERE time < NOW() - INTERVAL (not TimescaleDB drop_chunks); falls back gracefully without TimescaleDB
change-subscription	Subscribe-op placeholder — returns {status: not_implemented}; real-time LISTEN/NOTIFY wiring is not yet connected
multi-metric	Multiple named metrics co-located in one hypertable with tag-based partitioning

Attachable Modifiers

Modifier	Purpose
rate-limit	Throttle per-op invocation rate (high-frequency insert paths)
auth-policy	Element-scoped auth requirements

Error Codes

Code	Class	Retryable	Description
TS_INVALID_INTERVAL	validation	No	Unrecognized interval string — use numeric+suffix (30d, 1h) or full names (day, hour, minute)
TS_INVALID_TIMESTAMP	validation	No	Timestamp present but not parseable as RFC3339 — use 2024-01-15T12:00:00Z
TS_MISSING_VALUE	validation	No	Each data point requires a numeric value field
TS_INVALID_AGGREGATE	validation	No	Aggregate must be one of: avg, sum, min, max, count
TS_TABLE_CREATE_FAILED	internal	Yes	Failed to create the hypertable — transient backend error
TS_DELETE_REQUIRES_FILTER	validation	No	delete requires at least one of metric, from, to — unbounded delete is rejected

Operations

insert — POST insert

Insert one or more data points. Each point has a value (required, numeric), a metric name (default value), optional tags (key-value object), and an optional time (RFC3339 timestamp, defaults to now). Points are stored in the hypertable for efficient time-range queries. Returns {inserted: <integer>}.

Auth: write

query — POST query

Query data points with optional time range, metric filter, tag filter, and aggregation. Supports time bucketing (e.g. 1 hour, 5 minutes, 1 day) with an aggregate function (avg, sum, min, max, count — default avg). limit defaults to 1000. Returns {points: [...], count: <integer>}.

Auth: read

range — POST range

Return raw (non-aggregated) data points within a time range, filtered by optional metric, from, and to. Faster than query when aggregation is not needed. limit defaults to 1000. Returns {points: [...]}.

Auth: read

retention — POST retention

Configure data retention. Takes a required interval (e.g. 30 days, 1 year); data older than the interval is removed. Implemented as a SQL DELETE WHERE time < NOW() - INTERVAL rather than TimescaleDB drop_chunks. Returns {retention_set: <boolean>, interval: <string>}.

Auth: admin

downsample — POST downsample

Produce downsampled data at a coarser resolution. Takes a required bucket interval (e.g. 1 hour, 1 day) and an aggregate (avg, sum, min, max — default avg). This runs a date_trunc + GROUP BY aggregation query and returns aggregated points; it does not create a TimescaleDB continuous-aggregate materialized view. Returns {created: <boolean>}.

Auth: admin

subscribe — POST subscribe

Placeholder for real-time data-point subscription. Currently returns {status: not_implemented} (output schema: {subscribed: <boolean>, channel: <string>}); LISTEN/NOTIFY wiring is not yet connected — poll query/range instead.

Auth: read

delete — DELETE delete

Delete data points matching a filter (metric, from, and/or to). At least one filter is required — an unbounded delete is rejected (TS_DELETE_REQUIRES_FILTER). Deleted data cannot be recovered. Returns {deleted: <integer>}.

Auth: admin

Quick Start

Creating via API

POST /api/{circle}/{project}/
Content-Type: application/json

{
  "element_type": "timeseries",
  "slug": "app-metrics",
  "name": "Application Metrics",
  "spec": {
    "description": "Per-request latency and error counters"
  }
}

Inserting points

POST /api/{circle}/{project}/app-metrics/ops/insert
Content-Type: application/json

{
  "points": [
    { "metric": "latency_ms", "value": 42.0, "tags": { "route": "/login" } },
    { "metric": "latency_ms", "value": 55.5, "tags": { "route": "/login" }, "time": "2024-01-15T12:00:00Z" }
  ]
}

Querying with aggregation

POST /api/{circle}/{project}/app-metrics/ops/query
Content-Type: application/json

{
  "metric": "latency_ms",
  "from": "2024-01-15T00:00:00Z",
  "to": "2024-01-16T00:00:00Z",
  "bucket": "1 hour",
  "aggregate": "avg",
  "limit": 100
}

Reading raw points

POST /api/{circle}/{project}/app-metrics/ops/range
Content-Type: application/json

{
  "metric": "latency_ms",
  "from": "2024-01-15T12:00:00Z",
  "to": "2024-01-15T13:00:00Z"
}

Common Mistakes

Omitting value on a data point. Every point in points must include a numeric value. A missing value fails with TS_MISSING_VALUE. metric is optional (defaults to value).

Sending a non-RFC3339 timestamp. If time is present it must parse as RFC3339 (e.g. 2024-01-15T12:00:00Z), or the insert fails with TS_INVALID_TIMESTAMP. Omit time entirely to default to now.

Using an unsupported aggregate. query and downsample accept only avg, sum, min, max, count (downsample omits count). Anything else fails with TS_INVALID_AGGREGATE.

Malformed interval strings. retention intervals and bucket values must use a recognized form — numeric+suffix (30d, 1h) or full names (day, hour, minute). An unrecognized string fails with TS_INVALID_INTERVAL.

Calling delete without a filter. delete requires at least one of metric, from, or to. An unbounded delete is rejected with TS_DELETE_REQUIRES_FILTER.

Expecting subscribe to deliver events. subscribe is a placeholder that returns {status: not_implemented}. Poll query or range for new data instead.

Expecting downsample/retention to use TimescaleDB primitives. downsample runs a one-shot aggregation query (no materialized continuous aggregate), and retention runs a SQL DELETE (not drop_chunks). Both work whether or not TimescaleDB is present.

Relationships

• Attaches to: rate-limit, auth-policy

Capabilities

• time-range-query: Efficient time-range queries with optional metric and tag filters
• aggregation: Time-bucketed aggregation: avg, sum, min, max, count via time_bucket
• downsampling: Time-bucketed query aggregation via date_trunc + GROUP BY (avg, sum, min, max, count) via the downsample op. Returns aggregated data points — a SQL query, not a TimescaleDB continuous aggregate materialized view.
• retention-policy: Manual data expiry via the retention op which executes a SQL DELETE WHERE time < NOW() - INTERVAL. Uses plain SQL DELETE, not TimescaleDB drop_chunks. Falls back gracefully when TimescaleDB is unavailable.
• change-subscription: Subscribe op placeholder — returns {status: not_implemented} with a note to use polling. Real-time LISTEN/NOTIFY wiring is not yet connected. Ops: subscribe.
• multi-metric: Multiple named metrics co-located in one hypertable with tag-based partitioning

Properties

Property	Type	Default	Description
description	string	—	Human-readable description of what this timeseries element measures

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete data points matching a filter

Deletes data points matching the specified time range and/or metric filter. Use with caution – deleted data cannot be recovered.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

downsample

Post /ops/downsample | Auth: Admin

Create a continuous aggregate for downsampled data

Creates a continuous aggregate that automatically maintains downsampled views of the data at a coarser time resolution.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

insert

Post /ops/insert | Auth: Write

Insert time series data points

Inserts one or more data points. Each point has a metric name, numeric value, optional tags (JSON), and optional RFC3339 timestamp (defaults to now). Points are stored in a TimescaleDB hypertable for efficient time-range queries.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

query

Post /ops/query | Auth: Read

Query time series data with aggregation

Queries data points with optional time range, metric filter, and aggregation. Supports time bucketing (e.g., ‘1 hour’, ‘1 day’) with aggregate functions (avg, sum, min, max, count).

range

Post /ops/range | Auth: Read

Query raw data points in a time range

Returns raw (non-aggregated) data points within a time range. Faster than query when aggregation is not needed.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

retention

Post /ops/retention | Auth: Admin

Configure data retention policy

Sets the retention policy for this time series. Data older than the specified interval is automatically dropped by TimescaleDB.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_fixtures

Post /ops/source/fixtures | Auth: Write

Dry-run or apply approved Source seed fixtures

Scans .triform/fixtures/ manifests from the addressed data element Source repo. Defaults to dry_run=true and never imports live runtime data. Apply requires dry_run=false plus confirm=true and dispatches approved records through existing generated element ops.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

subscribe

Post /ops/subscribe | Auth: Read

Subscribe to real-time data point events

Sets up a NATS subscription for real-time notification when new data points are inserted into this time series.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
TS_INVALID_INTERVAL	validation	no	Unrecognized interval string — use numeric+suffix (e.g. ‘30d’, ‘1h’) or full names (day, hour, minute)
TS_INVALID_TIMESTAMP	validation	no	Timestamp field is present but cannot be parsed as RFC3339 — use ‘2024-01-15T12:00:00Z’ format
TS_MISSING_VALUE	validation	no	Each data point requires a numeric ‘value’ field
TS_INVALID_AGGREGATE	validation	no	Unsupported aggregate function — must be one of: avg, sum, min, max, count
TS_TABLE_CREATE_FAILED	internal	yes	Failed to create the timeseries hypertable — transient backend error
TS_DELETE_REQUIRES_FILTER	validation	no	delete op requires at least one of: metric, from, to — unbounded delete is rejected