---
name: uru-datasets
description: Create, inspect, query, change, and restore Uru Dataset V2 resources. Use for Dataset rows, schema identities, typed filters, history, jobs, or Gem Dataset SDK code.
---

# Uru Datasets

Use Dataset V2 only. Do not call an old Dataset tool or old Dataset SDK.

Dataset V2 uses stable Dataset, property, row, revision, and job identities.
The server owns access checks, revision fences, idempotency, and publication.

## Agent tool workflow

1. Find the Dataset with `library_query`.
2. Call `dataset_v2_get`.
3. Copy the returned Dataset id, property ids, Dataset revision, schema
   revision, and capabilities.
4. Query with `dataset_v2_query`.
5. Page with the returned opaque cursor.
6. For a write, use the latest revisions and a new idempotency key.
7. Submit with `dataset_v2_rows_mutate`.
8. Inspect the returned job with `dataset_v2_job_get`.
9. Report the terminal result or the durable job handle.

Use `dataset_v2_history_list` for revision history. Use
`dataset_v2_restore_native` to restore a supported native revision as a new
forward revision.

Use `dataset_v2_jobs_list` to inspect work. Use `dataset_v2_job_cancel` only
when the job state permits cancellation.

If the user requests Dataset creation or a schema change, use the visible
Dataset V2 operation only when its schema advertises that capability. If no V2
operation exists, report the missing capability with `report_friction`. Do not
fall back to an old Dataset tool.

## Query rules

- Use returned property ids. Do not query by display names.
- Use server-side filter, sort, pagination, search, and aggregates when the
  current capability set supports them.
- Do not compute Dataset totals, charts, or top values from one row page.
- Treat cursors as opaque. Do not edit or reuse a cursor with changed query
  inputs.
- Use the returned revision as the state witness.
- Read capabilities before you promise a feature.

The first bounded V2 query surface accepts current-generation reads. Ask the
tool schema for the exact request shape before a call. Do not send a field that
the schema does not advertise.

## Row mutation rules

Every row mutation must include:

- `datasetProtocolVersion: 2`;
- the exact Dataset id;
- a unique idempotency key;
- the expected Dataset revision;
- the expected schema revision;
- one bounded command.

Commands are `rowsUpsert`, `rowsDelete`, or `rowsRestore`.

For an insert, use `rowId: null` and `expectedRowVersion: null`. For an update,
delete, or restore, use the returned row id and row version.

Do not retry a failed write with changed content and the same idempotency key.
For a revision conflict, read the Dataset and affected rows again. Then make a
new request.

## Dataset V2 SDK

The current TypeScript client is `@uru/app`.

```ts
import { createDatasetV2Context } from "@uru/app";

type UruRuntimeConnection = {
  apiBaseUrl: string;
  authHeaders: () => HeadersInit | Promise<HeadersInit>;
};

export function connectDatasets(runtime: UruRuntimeConnection) {
  return createDatasetV2Context({
    baseUrl: runtime.apiBaseUrl,
    headers: runtime.authHeaders,
  });
}
```

The V2 client exposes:

- `get(datasetId)`;
- `query(request)`;
- `listHistory(datasetId, page)`;
- `restoreNative(datasetId, request)`;
- `submitRowsMutation(request)`;
- `listJobs(datasetId, page)`;
- `getJob(datasetId, jobId)`;
- `cancelJob(datasetId, jobId)`.

Use `UruDatasetV2Error.body.code`, `.retryable`, `.errorId`, current revision
fields, and job id for recovery and user-visible diagnostics.

Do not ask the user for an Uru key. Do not put an Uru token in Gem source.
The `runtime` argument represents the server runtime values that Uru
infrastructure supplies. For an external trusted server, adapt the same client
to its server-only Uru connection.

For a hosted Gem:

1. Declare the Dataset id in the root `uru.json`.
2. Keep `dataset_mutation_allowed` false unless the Gem must write.
3. Build the Gem.
4. Resolve the Dataset binding through Uru.
5. Use only the SDK surface that the deployed runtime exposes.

The old `uru.datasets.queryRows`, `upsertRows`, `deleteRows`, and `sqlWrite`
surface is not Dataset V2. Do not add it to new Gem code.

## Stop rules

- Do not fall back to old Dataset tables or tools.
- Do not invent ids, revisions, row versions, or cursors.
- Do not expose credentials in Dataset content or Gem source.
- Do not issue unbounded reads or writes.
- Do not hide queued, running, failed, canceled, or retryable states.
- Stop after an unknown error. Return its error id and the durable job id.

Read [the exact V2 contracts](references/contracts.md) when you need request
fields or recovery behavior.