# Cotera Tools

> Access and query datasets from your Cotera datagraph with powerful filtering capabilities.

Source: https://cotera.co/docs/reference/tools/individual-tools/dataset

---

**Authentication Type:** No Authentication\
**Description:** Access and query datasets from your Cotera datagraph with powerful filtering capabilities.

***

## Dataset Query Operations

Execute queries against datasets in your organization's datagraph.

### Query Dataset

Query any dataset by symbol name with optional filtering. Perfect for data exploration, debugging, and analysis of your Cotera data.

**Operation Type:** Query (Read)

**Parameters:**

* **symbol** `string` (required): The name/symbol of the dataset to query
* **filterColumn** `string` (nullable): Column name to filter on (optional)
* **filterValue** `string` (nullable): Value to filter by using LIKE operator (optional)
* **limit** `number` (nullable): Maximum number of rows to return. Defaults to 100

**Returns:**

* **symbol** `string`: The dataset symbol that was queried
* **data** `array of objects`: Array of result rows
* **metadata** `object`: Query metadata information
  * **rowCount** `number`: Number of rows returned
  * **columns** `array of strings`: Available column names in the dataset
  * **filterApplied** `boolean`: Whether a filter was applied
  * **filter** `string` (nullable): The filter condition that was applied, if any

**Example Usage:**

```json
{
  "symbol": "customer_transactions",
  "filterColumn": "transaction_type",
  "filterValue": "purchase",
  "limit": 500
}
```

***

## Dataset Workflow Operations

Trigger and manage automated workflows bound to datasets.

### Run Dataset Workflows

Run the workflows bound to a dataset over its rows — the chat equivalent of the dataset grid's Run menu. Use `all` to replay every matching row (including rows that already succeeded), or `needs-run` to fire only the rows that still need a run.

**Operation Type:** Mutation (Write)

**Access Requirements:** Requires dataset write/edit access. If the caller does not have edit permission on the dataset, the tool returns a terminal error.

**Parameters:**

* **datasetId** `string` (required): UUID of the dataset whose bound workflows to run. Use `coco/dataset-read` (its `automations` list) or `coco/search-cotera` to find it.
* **scope** `string` (nullable, default: `null`): Which rows to run. `null` is treated as `'all'`.
  * `'all'` — Replays every row that meets each trigger's criterion, including rows that already ran. Uses the same server-side replay as the dataset grid's "All rows" option: unbounded, crash-safe, and handles large datasets. Resets the observed trigger/workflow state for targeted pairs; the evaluator then re-runs rows over the next few minutes.
  * `'needs-run'` — Force-fires only rows a workflow still owes a run: rows that have never run, went stale after the row changed, or were cancelled. Enumerates rows to find outstanding ones, so it is capped at 5,000 rows. Datasets larger than the cap must use `'all'`.
* **workflowIds** `array of strings` (nullable, default: `null`): UUIDs of the specific workflows to run, from the dataset's `automations`. `null` runs every workflow bound to the dataset. Any UUID not bound to this dataset is silently ignored.

**Returns:**

* **datasetId** `string`: UUID of the dataset that was targeted.
* **scope** `string`: The resolved scope (`'all'` or `'needs-run'`).
* **groupId** `string`: UUID batch identifier shared by all workflow runs created by this call. Can be used to identify or cancel the runs later.
* **targetedWorkflows** `array of objects`: Workflows actually targeted after narrowing to `workflowIds`.
  * **id** `string`: Workflow UUID.
  * **name** `string`: Workflow display name.
* **triggersRun** `number`: Number of dataset triggers that had at least one targeted workflow.
* **dispatchedWorkflowRuns** `number` (nullable): (`needs-run` only) Number of workflow runs actually dispatched. `null` for `'all'`.
* **replayedPairs** `number` (nullable): (`all` only) Number of (trigger, workflow) pairs whose observed state was reset so the evaluator replays their rows. `null` for `'needs-run'`.
* **rowsConsidered** `number` (nullable): (`needs-run` only) Number of rows scanned to find outstanding runs. `null` for `'all'`.
* **truncated** `boolean`: `true` when `needs-run` hit the 5,000-row cap and some outstanding rows may not have been fired. Always `false` for `'all'`.
* **summary** `string`: Human-readable sentence describing what ran (or why nothing ran), suitable for relaying directly to the user.

**No-op Cases:**

The following situations are not errors. The tool returns zero counts and a `summary` explaining why:

* The dataset has no live automations watching it.
* The dataset has automations but no workflows are bound to them yet.
* The provided `workflowIds` are not bound to this dataset.

**Example Usage:**

Run all workflows on a dataset, replaying every matching row:

```json
{
  "datasetId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scope": "all"
}
```

Run only the rows that still need a run, for a specific workflow:

```json
{
  "datasetId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scope": "needs-run",
  "workflowIds": ["f1e2d3c4-b5a6-7890-1234-abcdef567890"]
}
```

***

## Common Use Cases

**Data Exploration:**

* Query datasets to understand data structure and available columns
* Explore sample data from various datasets in your organization's datagraph
* Use filtering to examine specific subsets of data for pattern analysis

**Data Debugging:**

* Investigate data quality issues by filtering for specific values or conditions
* Verify data transformations by comparing input and output datasets
* Check for missing or anomalous data patterns using targeted queries

**Analytics and Reporting:**

* Extract filtered datasets for use in business intelligence and reporting tools
* Query transaction data with date range or category filters for financial analysis
* Retrieve customer data segments for targeted marketing campaign analysis

**Development and Testing:**

* Access sample datasets during application development and testing
* Validate data pipeline outputs by querying intermediate and final datasets
* Monitor data freshness and completeness across different data sources in your datagraph