cotera
Logo

Cotera Tools

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:

{
  "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:

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

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

{
  "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