Skip to content
Alation Agent Studio Documentation

Revise Data Product

The Revise Data Product agent improves data product semantic layers through iterative refinement. It analyzes SQL evaluation results, identifies failures, updates data product specifications, and verifies improvements through re-evaluation.

How it works

Section titled “How it works”

The agent follows this workflow:

  1. Runs SQL evaluation on the data product’s evaluation set and analyzes results
  2. Provides a summary of evaluation results, identifying patterns in failed cases
  3. Fetches the current data product specification to understand its structure
  4. Generates JSON Patch (RFC 6902) operations targeting only the fields that need to change
  5. Applies the patch to the data product’s unlisted draft version in place
  6. Re-runs evaluation to verify improvements and compares with previous results
  7. Iterates the process if needed based on user feedback

Input parameters

Section titled “Input parameters”

Required:

  • message (string): Instructions or questions about the data product evaluation
  • data_product_id (string): The ID of the data product to evaluate and improve

Output format

Section titled “Output format”

The agent produces a series of thinking, tool call, tool return, and text blocks as it works through the user request. The final message, assuming no errors, is a string with evaluation results and improvement summary.

Available tools

Section titled “Available tools”

The agent has access to three tools:

Run SQL evaluation

Section titled “Run SQL evaluation”

Runs SQL evaluation on the data product’s evaluation set. Returns cached results if the data product specification hasn’t changed, otherwise triggers a fresh evaluation run.

Returns:

  • Overall execution accuracy
  • Passed cases (successful question/SQL pairs)
  • Failed cases with detailed reasoning

Get data product raw specification

Section titled “Get data product raw specification”

Retrieves the complete raw data product specification in the exact format expected by the update API. This differs from the schema tool by providing the raw JSON specification without sample values or simplification.

Key fields in specification:

  • product.en.description: Natural language description
  • product.deliverySystems: Database connection information
  • product.recordSets: Table definitions
  • x-metrics: Custom metric definitions
  • x-derivedColumns: Computed column definitions
  • relationships: Join relationship definitions

Update data product spec

Section titled “Update data product spec”

Applies a list of JSON Patch (RFC 6902) operations to the data product’s unlisted draft version. Patches use JSON Pointer paths (/product/recordSets/<table_name>/...) and support add, replace, copy, and remove.

Protected paths (cannot be modified):

  • /product/productId
  • /product/version
  • /product/deliverySystems

If the target version is already listed in the Data Product Marketplace, the call fails — listed versions are immutable, and a new draft must be created before further edits.

Behavior notes

Section titled “Behavior notes”
  • Always fetch before update: The agent must call Get Data Product Raw Specification before generating a patch, so its operations target the actual current structure
  • Patch-based, not replacement: Updates are JSON Patch operations targeting only the fields that change. Other fields are left untouched
  • Drafts only: Patches apply to the unlisted draft version in place; listed versions are immutable
  • Verify improvements: Changes are only kept if they improve evaluation scores
  • Iterative approach: The agent can make multiple rounds of refinements based on evaluation feedback
  • Cached results: If the data product hasn’t changed, evaluation returns cached results for efficiency

Common use cases

Section titled “Common use cases”

Improving descriptions

Section titled “Improving descriptions”

Updates product.en.description or table/column descriptions to better capture domain terminology and improve semantic understanding.

Refining metrics

Section titled “Refining metrics”

Modifies x-metrics definitions to accurately represent business calculations and aggregations.

Defining relationships

Section titled “Defining relationships”

Updates relationships to correctly specify join conditions between tables.

Adding derived columns

Section titled “Adding derived columns”

Creates or modifies x-derivedColumns to expose computed fields for natural language queries.

Section titled “Related”