> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ilyama.golain.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Querying synced data

> Read materialized mirror rows, telemetry fallbacks, and QueryScript.

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

```bash theme={null}
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:

```bash theme={null}
GET .../lineages/{lineage_id}/staged-rows
```

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

## platform-tui

1. Edge Sync → Lineages → select lineage
2. Press **`w`** for written data
3. 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:

```json theme={null}
{
  "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):

```sql theme={null}
-- 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](/edge/data-sync/schema-review-workflow)     |
| Lineage `paused` for backpressure?               | [Backpressure](/edge/data-sync/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                      |

## Related

* [Schema review workflow](/edge/data-sync/schema-review-workflow)
* [platform-tui TUI guide](/tools/platform-tui/tui-guide)