sparql

Files (13)

• SKILL.md
• catalog.json · queries/
• count_spatial.rq · queries/
• dataset_by_name.rq · queries/
• datasets_sample.rq · queries/
• depth_assay.rq · queries/
• depth_minmax.rq · queries/
• list_graphs.rq · queries/
• list_types.rq · queries/
• probe_triples.rq · queries/
• providers_from_graphs.rq · queries/
• variable_measured.rq · queries/
• sparql_query.py · scripts/

SKILL.md (first lines)

# SPARQL Query

Run **portable SPARQL 1.1** against a user-supplied endpoint. Prefer curated
templates in `queries/`; when none fit, author new SPARQL from the **schema.org
cookbook** below and execute with `query` or `file`.

Adapted from the DOOS `doos-sparql` skill. Templates still target schema.org +
GeoSPARQL patterns used in DOOS/Oxigraph named graphs.

## Required: endpoint URL

Every network command needs:

```text
--endpoint <SPARQL_URL>
```

**Local test (Oxigraph):** `http://localhost:7878/query`

Always use the full **query** path (`/query`), not the store base URL alone.

If the user does not give an endpoint, ask once, then default the suggestion to
`http://localhost:7878/query` for local work.

## Agent workflow

1. **Confirm endpoint** — required; do not invent live URLs.
2. **Match a template** — run `list`, pick the best `id`, then `run`.
3. **If no template fits** — write SPARQL from the cookbook → `query` or `file`.
4. **Show the SPARQL** — use `--show-query` (or paste the query in the reply).
5. **Report results honestly** — row counts and sample rows only; never invent bindings.
6. **Empty results** — try `probe_triples` / `list_graphs`; check http vs https schema.org; check named graphs vs default graph.

### Prefer templates over inventing SPARQL

| User intent | Template id |
|---|---|
| Is the store alive / has data? | `probe_triples` |
| What types exist? | `list_types` |
| What named graphs? | `list_graphs` |
| Sample datasets | `datasets_sample` |
| Find datasets by name | `dataset_by_name` (`--name`) |
| List measured variables | `variable_measured` |
| Depth variables inventory | `depth_assay` |
| DepBelowSurf ranges | `depth_minmax` |
| Spatial coverage count | `count_spatial` |
| Provider slugs from graph IRIs | `providers_from_graphs` |

## CLI

Run from the **decoder-pi repo root** (`uv` resolves `SPARQLWrapper` from this
repo's `pyproject.toml`). Paths below are relative to that root:

```bash
# List templates (no network)
uv run python skills/sparql/scripts/sparql_query.py list

# Run a named template
uv run python skills/sparql/scripts/sparql_query.py run \
  --endpoint http://localhost:7878/query \
  --query depth_assay \
  --limit 50 \
  --format table \
  --show-query

# Optional filters
#   --name <fragment>           # required for dataset_by_name
#   --graph-contains <substr>   # FILTER on named graph IRI (variable_measured, depth_minmax)

# Ad-hoc SPARQL string
uv run python skills/sparql/scripts/sparql_query.py query \
  --endpoint http://localhost:7878/query \
  --sparql 'PREFIX schema: <https://schema.org/>
SELECT ?s ?name WHERE {
  GRAPH ?g { ?s a schema:Dataset ; schema:name ?name . }
} LIMIT 10' \
  --format json

# Any .rq file
uv run python skills/sparql/scripts/sparql_query.py file \
  --endpoint http://localhost:7878/query \
  --query-file skills/sparql/queries/probe_triples.rq
```

| Subcommand | Network? | Purpose |
|---|---|---|
| `list` | no | Catalog of template ids |
| `run` | yes | Curated `queries/<id>.rq` |
| `query` | yes | Inline SPARQL string |
| `file` | yes | Path to `.rq` file |

**Output:** `--format table|json|csv` (default `table`).

**Deps:** `SPARQLWrapper` via this repo's `pyproject.toml`. First run:

```bash
uv sync
```

## Schema.org cookbook

Metadata in this domain is primarily **schema.org** + **GeoSPARQL**, often in
**named graphs**.

### Prefixes (portable)

```sparql
PREFIX schema: <https://schema.org/>
PREFIX rdf:    <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs:   <http://www.w3.org/2000/01/rdf-schema#>
PREFIX xsd:    <http://www.w3.org/2001/XMLSchema#>
PREFIX geo:    <http://www.opengis.net/ont/geosparql#>
```

Prefer `https://schema.org/`. Some older loads use `http://schema.org/` — if counts look low, UNION both or probe with `list_types`.

### Named graphs

Most Oxigraph loads put triples in **named graphs**. Prefer:

From earthcube/decoder-pi, Apache-2.0.

More from earthcube/decoder-pi