ROSQL

website·Indexed 31 days ago

A query language that compiles to SQL to execute against ROS2 telemetry data. It provides a CLI, a WASM-based parser and validator via the @robotops/rosql npm package, and supports OpenTelemetry schema conventions for ROS2 action executions and pub/sub tracing. Documentation covers versions 0.3, 0.4, and 0.5, including command references for data source statements, syntax for query forms, and a cookbook for common observability tasks.

Tokens: 39.5K
Snippets: 292
Records: 325
Agent score: 51%

What's inside ROSQL

Overview of ROSQL robotics-native query capabilities
ROSQL provides a query language tailored for robot observability, removing the need for glue code when analyzing ROS2 systems. Key capabilities include:
- Robotics-native syntax: First-class support for ROS2 nodes, actions, topics, and named joints.
- Distributed Tracing: OpenTelemetry-native tracing across robots and fleet management systems, including recursive TRACE 'id' calls to walk parent_span_id chains.
- Cross-signal correlation: The DURING() primitive correlates events across traces, logs, metrics, and topics in a single query.
- Robot Model Understanding: Ability to query by named joint, inspect URDF-derived limits via SHOW JOINTS, and measure JOINT DEVIATION or PATH DEVIATION.
- Deployment-aware scoping: Scope queries to specific robots, versions, or environments using FOR ROBOT 'id' FOR VERSION 'v1.3.0' and SINCE last deployment.
- Unit-aware filtering: Supports physical quantities in various units (e.g., deg, m, Nm, V, mph) which are automatically converted to SI units.
https://rosql.org/
Understand the ROSQL playground simulated fleet dataset
The ROSQL playground REPL uses a simulated dataset of a 3-robot warehouse AMR fleet. The fleet consists of:
- robot-amr-01: Firmware v2.3.1 (Reliable).
- robot-amr-02: Firmware v2.4.0 (Recently upgraded, experienced 1 failure).
- robot-amr-03: Firmware v2.3.0 (Aging hardware, slow successes, battery drain).
https://rosql.org/docs/0.4/repl-dataset/
Understand the ROSQL playground simulated fleet dataset
The ROSQL playground REPL uses a simulated dataset of a 3-robot warehouse AMR fleet. The fleet consists of:
- robot-amr-01: Firmware v2.3.1 (Reliable).
- robot-amr-02: Firmware v2.4.0 (Recently upgraded; experienced a failure in its third mission trace-amr02-m3 due to a costmap update timeout).
- robot-amr-03: Firmware v2.3.0 (Aging hardware; slow successes and battery drain).
All timestamps are relative to the current time (NOW()), meaning queries using relative time intervals (e.g., SINCE 45 min ago) will always return data as the simulation is perpetually in progress.
https://rosql.org/docs/repl-dataset/

Write ROSQL queries using Standard or Pipeline form

ROSQL supports two syntactically different but functionally identical query forms: Standard form (SQL-like) and Pipeline form (using the | operator). Both compile to the same AST and produce the same results.

-- Standard form
SELECT AVG(duration) AS avg_dur FROM traces
WHERE status = 'ERROR'
FOR ROBOT 'scout_1'
SINCE 1 hour ago
FACET action_name
ORDER BY avg_dur DESC
LIMIT 5

-- Pipeline form (identical result)
FROM traces
| WHERE status = 'ERROR'
| FOR ROBOT 'scout_1'
| SINCE 1 hour ago
| SELECT AVG(duration) AS avg_dur
| FACET action_name
| ORDER BY avg_dur DESC
| LIMIT 5

Trace message causality chains
Use the TRACE command followed by a span ID to recursively walk the parent_span_id → span_id chain and return all spans in the causality chain.
```
TRACE 'a3f1c9d2e8b04f7a'
```
https://rosql.org/docs/0.4/quickstart/
Add comments to ROSQL queries
ROSQL supports single-line comments using the -- prefix. Block comments are not supported.
```
FROM traces
WHERE action_name = '/navigate_to_pose'  -- This is a comment
  AND duration > 2 s
SINCE 1 hour ago
```
https://rosql.org/docs/syntax/

Paginate query results

Use LIMIT and OFFSET to page through large result sets. This can be written in standard SQL or pipeline syntax.

-- Standard SQL pagination
FROM logs ORDER BY timestamp DESC LIMIT 20 OFFSET 40

-- Pipeline syntax pagination
FROM logs | ORDER BY timestamp DESC | LIMIT 20 | OFFSET 40

Query MySQL or MariaDB
To query MySQL or MariaDB, use the mysql feature flag and the --backend mysql CLI flag.
```
rosql query "FROM traces WHERE status = 'ERROR'" \
  --backend mysql \
  --url mysql://user:pass@localhost:3306/telemetry
```
https://rosql.org/docs/drivers/
Install ROSQL CLI
ROSQL is available for Linux (x86_64/arm64), macOS (Intel/Apple Silicon), and Windows via cargo. The installation script installs the binary to ~/.local/bin/.
```
curl -fsSL https://rosql.org/install.sh | sh
```
https://rosql.org/
Correlate data sources using DURING subqueries
ROSQL allows replacing complex multi-table JOINs with a declarative correlation using the DURING clause. This allows a primary query to be filtered by the time window of a subquery from any other data source.
```
FROM traces WHERE status = 'ERROR'
DURING(
  FROM topics WHERE topic_name = '/battery_state'
  AND fields['percentage'] < 15
)
SINCE 6 hours ago
```
https://rosql.org/docs/0.4/command-reference/
Filter telemetry by geospatial proximity
Starting in v0.4.3, you can filter odom messages based on distance. Use WITHIN {distance} m OF ({lat}, {lon}) for GPS (Haversine) distance or WITHIN {distance} m OF POSITION ({x}, {y}) for local frame (Euclidean) distance.
```
-- GPS proximity (Haversine)
FROM odom WHERE position WITHIN 500 m OF (37.7749, -122.4194) SINCE 1 hour ago

-- Local frame proximity (Euclidean)
FROM odom WHERE position WITHIN 2 m OF POSITION (1.5, 3.0) SINCE 1 hour ago
```
https://rosql.org/docs/0.4/cookbook/

Group and compare trace results

Use FACET for grouping and COMPARE operators to baseline current results against historical data or specific versions.

-- Group results by a field
SELECT AVG(duration) FROM traces FACET robot_id
FROM traces WHERE status = 'ERROR' | FACET robot_id

-- Compare current results to a historical baseline
FROM traces WHERE status = 'ERROR' SINCE 1 hour ago | COMPARE TO last week

-- Compare current results to a specific version baseline
FROM traces COMPARE TO VERSION 'v1.2.3'
FROM traces WHERE status = 'ERROR' SINCE 1 hour ago | COMPARE TO VERSION 'v1.0.0'

-- Compare two versions head-to-head
FROM traces COMPARE VERSION 'v1.0' TO VERSION 'v2.0'
FROM traces WHERE action_name = '/navigate_to_pose' COMPARE VERSION 'v1.0' TO VERSION 'v2.0'