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 Creation Operations

Create datasets seeded from your organization's connected warehouse.

Create Warehouse Dataset

Create a Cotera dataset seeded from a SELECT query run against the organization's connected warehouse. The dataset kind (Snowflake or Postgres) is determined automatically from the warehouse connection. Use this to build a dataset from existing warehouse tables; use coco/warehouse-schema to discover the available tables and columns first.

Operation Type: Query (Read)

Parameters:

  • name string (required): Name for the new dataset — e.g. "Enterprise accounts". Defaults to 'Untitled dataset' if an empty string is passed.
  • sourceQuery string (required): A single read-only SELECT in the connected warehouse's own SQL dialect, run verbatim against it. When the user wants the full table, use SELECT * FROM <schema>.<table> rather than enumerating columns.
  • rowKeyColumns array of strings (required): The columns of the query result that identify a row, in order (1–16 columns). Must be a stable business key — every column listed must be returned by the SELECT, or the seed fails.
  • cadence string (nullable, default: null): Optional cron expression for how often the dataset is re-scanned for warehouse changes. null leaves no scheduled re-scan.
  • cadenceTimezone string (nullable, default: null): IANA timezone the cadence cron is interpreted in. null defaults to UTC. Ignored when cadence is null.
  • folderId string (nullable, default: null): UUID of the folder to place the dataset in. null uses the conversation's folder when it has one.

Returns:

  • datasetId string: UUID of the created dataset.
  • name string: The dataset name as stored.
  • importId string: UUID of the warehouse seed import job.
  • importStatus string: Final status of the seed — one of 'importing', 'ready', or 'failed'. The tool waits for the seed to settle before returning, so this reflects the outcome.
  • importError string (nullable): The seed's failure reason when importStatus is 'failed', otherwise null.

Warehouse Kind Selection:

The dataset kind is resolved automatically from the organization's warehouse connection vendor:

  • Snowflake connection → Snowflake dataset
  • Postgres connection → Postgres dataset
  • BigQuery, Redshift, DuckDB → not supported; the tool returns a terminal error

Error Cases:

  • If the organization has no connected warehouse, the tool returns a terminal error asking the user to connect one (Settings → Warehouse).
  • If the connected warehouse vendor is not supported (BigQuery, Redshift, DuckDB), the tool returns a terminal error naming the vendor and supported options.
  • If rowKeyColumns is empty or exceeds 16 columns, the tool returns a terminal error.
  • If a declared row key column is not present in the query result, the seed fails and importStatus is 'failed'.

Behavior Notes:

  • The tool adds a Dataset artifact to the conversation once the dataset is created.
  • Because the seed runs asynchronously, do not read the dataset immediately after creation — the rows may not yet have arrived. The returned importStatus is the settled state.
  • generatesReceipts is false.

Example Usage:

Create a dataset from a Snowflake table, keyed by account ID:

{
  "name": "Enterprise accounts",
  "sourceQuery": "SELECT * FROM analytics.public.accounts WHERE tier = 'enterprise'",
  "rowKeyColumns": ["account_id"],
  "cadence": "0 6 * * *",
  "cadenceTimezone": "America/New_York"
}

Create a dataset from a Postgres table in a specific folder:

{
  "name": "Open support tickets",
  "sourceQuery": "SELECT id, subject, status, created_at FROM helpdesk.tickets WHERE status != 'closed'",
  "rowKeyColumns": ["id"],
  "folderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

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"]
}

Dataset Library Operations

Promote chat-scoped uploaded datasets into your organization's permanent dataset library.

Save Uploaded Dataset to Library

Promotes an existing chat-scoped uploaded dataset into the permanent library. The dataset already exists from the upload — this operation saves it to the library without copying rows or creating a new dataset. Use the coco/dataset-create tool only for net-new datasets; calling it on an already-uploaded dataset would duplicate the data.

Operation Type: Query (Read)

Authentication Type: No Authentication

Parameters:

  • datasetId string (required): UUID of the chat-scoped uploaded dataset to save into the library. Use coco/dataset-read or coco/search-cotera to find the UUID of the uploaded dataset.
  • name string (nullable, default: null): Optional new display name for the dataset. null keeps the current name (the original uploaded filename).

Returns:

  • datasetId string: The dataset ID of the promoted dataset.
  • name string: The dataset name — the provided name if supplied, otherwise the original uploaded filename.
  • promoted boolean: Always true on success.

Example Usage:

Promote an uploaded dataset, keeping its original filename as the name:

{
  "datasetId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Promote an uploaded dataset and give it a new display name:

{
  "datasetId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Q3 Customer Survey Responses"
}

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