Skip to main content
PUT
https://sandbox.getcollate.io/api
/
v1
/
tables
/
{id}
/
customMetric
PUT /v1/tables/{id}/customMetric
from metadata.sdk import configure
from metadata.sdk.entities import Tables

configure(
    host="https://your-company.getcollate.io/api",
    jwt_token="your-jwt-token"
)

table_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

# Add a table-level custom metric
Tables.add_custom_metric(table_id, {
    "name": "active_customer_ratio",
    "description": "Ratio of active customers to total customers",
    "expression": "SELECT CAST(SUM(CASE WHEN active = true THEN 1 ELSE 0 END) AS FLOAT) / COUNT(*) FROM {table}"
})

# Add a column-level custom metric
Tables.add_custom_metric(table_id, {
    "name": "email_domain_count",
    "description": "Number of distinct email domains",
    "columnName": "email",
    "expression": "SELECT COUNT(DISTINCT SPLIT_PART(email, '@', 2)) FROM {table}"
})

# Delete a custom metric
Tables.delete_custom_metric(table_id, "active_customer_ratio")
{
  "id": "455e3d9d-dbbf-455e-b3be-7191daa825f3",
  "name": "agent_performance_summary",
  "fullyQualifiedName": "sample_data.ecommerce_db.shopify.agent_performance_summary",
  "customMetrics": [
    {
      "name": "high_performer_ratio",
      "description": "Ratio of high-performing agents (score > 90) to total agents",
      "expression": "SELECT CAST(SUM(CASE WHEN performance_score > 90 THEN 1 ELSE 0 END) AS FLOAT) / COUNT(*) FROM {table}"
    }
  ]
}

Custom Metrics

Define custom SQL-based metrics on a table or specific column. Custom metrics are evaluated during profiling runs and tracked over time.

Add Custom Metric

PUT /v1/tables/{id}/customMetric
id
string
required
UUID of the table.
name
string
required
Name of the custom metric. Must be unique within the table.
expression
string
required
SQL expression to evaluate for this metric. Must return a single numeric value.
columnName
string
Name of the column this metric applies to. If omitted, the metric is table-level.
description
string
Description of what this metric measures.

Delete Custom Metric

DELETE /v1/tables/{id}/customMetric/{metricName}
id
string
required
UUID of the table.
metricName
string
required
Name of the custom metric to delete.
PUT /v1/tables/{id}/customMetric
from metadata.sdk import configure
from metadata.sdk.entities import Tables

configure(
    host="https://your-company.getcollate.io/api",
    jwt_token="your-jwt-token"
)

table_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

# Add a table-level custom metric
Tables.add_custom_metric(table_id, {
    "name": "active_customer_ratio",
    "description": "Ratio of active customers to total customers",
    "expression": "SELECT CAST(SUM(CASE WHEN active = true THEN 1 ELSE 0 END) AS FLOAT) / COUNT(*) FROM {table}"
})

# Add a column-level custom metric
Tables.add_custom_metric(table_id, {
    "name": "email_domain_count",
    "description": "Number of distinct email domains",
    "columnName": "email",
    "expression": "SELECT COUNT(DISTINCT SPLIT_PART(email, '@', 2)) FROM {table}"
})

# Delete a custom metric
Tables.delete_custom_metric(table_id, "active_customer_ratio")
{
  "id": "455e3d9d-dbbf-455e-b3be-7191daa825f3",
  "name": "agent_performance_summary",
  "fullyQualifiedName": "sample_data.ecommerce_db.shopify.agent_performance_summary",
  "customMetrics": [
    {
      "name": "high_performer_ratio",
      "description": "Ratio of high-performing agents (score > 90) to total agents",
      "expression": "SELECT CAST(SUM(CASE WHEN performance_score > 90 THEN 1 ELSE 0 END) AS FLOAT) / COUNT(*) FROM {table}"
    }
  ]
}

Returns

Add returns the updated table object with the custom metric included. Delete returns no content (204).

Response

customMetrics
array
Array of custom metrics defined on the table.

Error Handling

CodeError TypeDescription
401UNAUTHORIZEDInvalid or missing authentication token
403FORBIDDENUser lacks permission
404NOT_FOUNDTable or custom metric does not exist
400BAD_REQUESTInvalid metric definition or SQL expression
409CONFLICTCustom metric with same name already exists