---
name: data
description: 'Slice, filter, and reshape structured data with jq and SQL. Tools: jq, sql. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: engineering, computation
  tools: jq.py, sql.py
---

# Data

Slice, filter, and reshape structured data with jq and SQL.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/jq.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `jq.py`

Slice, transform, filter, and extract JSON data using jq query expressions on JSON text or JSON files.

Use when the user wants to filter, reshape, or pull fields out of JSON, or an API payload needs trimming before it enters context.

```sh
<skill-dir>/jq.py -p filter="<filter>" [-p json_source="<json_source>"] [-p json_text="<json_text>"]
```

Parameters:
- `filter` (string, required) — jq filter expression, e.g. .items[].name
- `json_source` (file, optional) — Host JSON file mounted at /input/json_source
- `json_text` (string, optional) — Inline JSON text (or pipe stdin)
- stdin (optional) — piped input is read in full and hashed into the run's receipt

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `sql.py`

Run SQL queries on CSV, TSV, or tabular data, outputting results as Markdown, JSON, or CSV.

Use when the user wants to query, filter, aggregate, or slice tabular CSV or TSV data with SQL, or large tabular files must be summarized before entering context.

```sh
<skill-dir>/sql.py -p query="<query>" [-p table_source="<table_source>"] [-p table_text="<table_text>"] [-p delimiter=auto] [-p format=markdown]
```

Parameters:
- `query` (string, required) — SQL query to run against the table named 'data' (e.g. 'SELECT status, count(*) FROM data GROUP BY status')
- `table_source` (file, optional) — Host CSV/TSV file mounted at /input/table_source
- `table_text` (string, optional) — Inline CSV/TSV text (or pipe stdin)
- `delimiter` (string, optional, default `auto`) — Column delimiter: auto, comma, tab, pipe, semicolon
- `format` (string, optional, default `markdown`) — Output format: markdown, json, csv
- stdin (optional) — piped input is read in full and hashed into the run's receipt

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.
