Querying synced data

After schema approval and materialization, synced SQLite data lives in edge_state_* tables for relational rows and edge_ts_* hypertables for telemetry — not in the raw staging ledger.

Telemetry hypertables (canonical for telemetry)

Physical table naming:

Coalescing	Pattern	Example
Project coalesced (recommended)	`edge_ts_p{project8}_{source_table}`	`edge_ts_p9f8e7d6c_vrf_abc123_metrics`
Fleet coalesced	`edge_ts_f{fleet8}_{source_table}`	`edge_ts_f1a2b3c4d_sensor_timeseries`

Telemetry hypertables always include device_id and event_ts, plus the approved source columns for that SQLite table. Golain enables Timescale compression on these tables after 1 day. Use these tables as the canonical read surface for telemetry written through edge replication. The older shared telemetry table is not the primary query surface for the current edge flow.

State tables (relational)

Physical table naming:

Coalescing	Pattern	Example
Device-scoped	`edge_state_{device8}_{source_table}`	`edge_state_a1b2c3d4_device_state`
Project coalesced	`edge_state_p{project8}_{table}`	`edge_state_p9f8e7d6c_device_state`
Fleet coalesced	`edge_state_f{fleet8}_{table}`	`edge_state_f1a2b3c4d_status`

device8 / project8 / fleet8 are truncated hex prefixes of UUIDs. Rows include platform columns (device_id, version metadata) plus source columns you approved with action mirror.

HTTP API

GET /core/api/v1/projects/{project_id}/edge/lineages/{lineage_id}/mirror-rows?page=1&limit=100

Returns paginated JSON rows from the provisioned relational target for that lineage. Staged (pre-materialization) rows:

GET .../lineages/{lineage_id}/staged-rows

Use staged endpoint to debug; use mirror-rows for product queries.

platform-tui

Edge Sync → Lineages → select lineage
Press w for written data
Toggle s / w in data viewport

If mirror-rows returns 404 for a telemetry lineage, the TUI builds a QueryScript fallback against the lineage’s edge_ts_* hypertable — see below.

QueryScript (Data explorer)

Project menu → Data explorer posts QueryScript v2 JSON. Example — filter telemetry written from mapped columns:

{
  "version": 2,
  "from": "edge_ts_p9f8e7d6c_vrf_abc123_metrics",
  "select": ["device_id", "event_ts", "channel", "reading"],
  "where": {
    "and": [
      { "eq": ["device_id", "YOUR-DEVICE-UUID"] }
    ]
  },
  "limit": 100
}

Replace the table name with the actual edge_ts_* target for your Project or Fleet and use the device UUID (from console or golain devices get), not the MQTT device name, for filters. CLI equivalent: run TUI Data explorer or call POST /projects/{id}/queryscript via API.

Choosing mirror vs telemetry

You approved with	Query surface
`mirror` action on relational rows	`mirror-rows` API / `edge_state_*` table
Telemetry lineage	QueryScript against `edge_ts_*`
Mixed workflow	Read state via `mirror-rows` and telemetry via `edge_ts_*`

Authz note

Authorized read paths for mirror tables in product UI are evolving. Admin operators with project device-manage permission can read via edge API today. Customer-facing dashboards should confirm authz model before exposing mirror data broadly.

Verification queries (operators with DB access)

On Timescale (internal debugging only):

-- Batch ledger
SELECT received_at, source_table, kind, row_count, status
FROM edge_export_segments
WHERE device_id = '...'
ORDER BY received_at DESC LIMIT 10;

-- Staged bodies
SELECT source_commit_seq, staging_reason
FROM edge_staged_rows
WHERE device_id = '...'
ORDER BY source_commit_seq;

-- State table (after approve)
SELECT * FROM edge_state_a1b2c3d4_device_state
WHERE device_id = '...'
LIMIT 20;

-- Telemetry hypertable (canonical telemetry reads)
SELECT device_id, event_ts, channel, reading
FROM edge_ts_p9f8e7d6c_vrf_abc123_metrics
WHERE device_id = '...'
ORDER BY event_ts DESC
LIMIT 20;

Do not expose raw TSDB access to end customers — use API and QueryScript.

Empty results checklist

Check	Action
Schema review still `queued`?	Approve
Lineage `paused` for backpressure?	Backpressure
Only pre-Omega rows in SQLite?	Trigger new mutations after Omega start
Wrong device UUID in filter?	Use metadata UUID not MQTT name
Querying legacy `telemetry_data_point_value`?	Switch QueryScript to the lineage’s `edge_ts_*` table
Column action `ignore` on all relational fields?	Re-approve with `mirror` actions

Omega edge runtime

Device RPC

Edge SQLite sync

Edge agent (Omega)

Operate & query

Wire protocol reference

Querying synced data

Telemetry hypertables (canonical for telemetry)

State tables (relational)

HTTP API

platform-tui

QueryScript (Data explorer)

Choosing mirror vs telemetry

Authz note

Verification queries (operators with DB access)

Empty results checklist

​Telemetry hypertables (canonical for telemetry)

​State tables (relational)

​HTTP API

​platform-tui

​QueryScript (Data explorer)

​Choosing mirror vs telemetry

​Authz note

​Verification queries (operators with DB access)

​Empty results checklist

​Related

Telemetry hypertables (canonical for telemetry)

State tables (relational)

HTTP API

platform-tui

QueryScript (Data explorer)

Choosing mirror vs telemetry

Authz note

Verification queries (operators with DB access)

Empty results checklist

Related