PUT /v1/metrics

curl -X PUT "{base_url}/api/v1/metrics" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer_retention_rate",
    "displayName": "Customer Retention Rate",
    "description": "Percentage of customers retained during the month.",
    "metricExpression": {
      "language": "SQL",
      "code": "retained_customers * 100.0 / NULLIF(total_customers, 0)"
    },
    "metricType": "RATIO",
    "unitOfMeasurement": "PERCENTAGE",
    "granularity": "MONTH",
    "domains": ["Customer"]
  }'

from metadata.sdk import configure
from metadata.sdk.entities import Metrics

configure(
    host="https://your-company.open-metadata.org/api",
    jwt_token="your-jwt-token"
)

# The SDK calculates and submits JSON Patch from the changed entity.
metric = Metrics.retrieve("b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10")
metric.description = "Percentage of active customers retained month over month."
metric.displayName = "Monthly Customer Retention Rate"

updated = Metrics.update(metric)
print(f"Updated to version {updated.version.root}")

// client is an initialized OpenMetadataClient.
var metricId = "b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10";
var metric = client.metrics().get(metricId);

metric.setDescription(
    "Percentage of active customers retained month over month.");
metric.setDisplayName("Monthly Customer Retention Rate");

// update() calculates and submits JSON Patch from the fetched snapshot.
var updated = client.metrics().update(metricId, metric);
System.out.println("Updated to version " + updated.getVersion());

# Update by ID.
curl -X PATCH "{base_url}/api/v1/metrics/b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
    {
      "op": "replace",
      "path": "/description",
      "value": "Percentage of active customers retained month over month."
    },
    {
      "op": "replace",
      "path": "/displayName",
      "value": "Monthly Customer Retention Rate"
    }
  ]'

# Update by fully qualified name.
curl -X PATCH "{base_url}/api/v1/metrics/name/customer_retention_rate" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
    {
      "op": "replace",
      "path": "/metricExpression/code",
      "value": "active_retained_customers * 100.0 / NULLIF(active_customers, 0)"
    }
  ]'

{
  "id": "b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10",
  "name": "customer_retention_rate",
  "displayName": "Monthly Customer Retention Rate",
  "fullyQualifiedName": "customer_retention_rate",
  "description": "Percentage of active customers retained month over month.",
  "metricExpression": {
    "language": "SQL",
    "code": "retained_customers * 100.0 / NULLIF(total_customers, 0)"
  },
  "metricType": "RATIO",
  "unitOfMeasurement": "PERCENTAGE",
  "granularity": "MONTH",
  "version": 0.2,
  "updatedAt": 1787760600000,
  "updatedBy": "admin",
  "href": "https://your-company.open-metadata.org/api/v1/metrics/b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10",
  "deleted": false
}

PUT

metrics

PUT /v1/metrics

curl -X PUT "{base_url}/api/v1/metrics" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer_retention_rate",
    "displayName": "Customer Retention Rate",
    "description": "Percentage of customers retained during the month.",
    "metricExpression": {
      "language": "SQL",
      "code": "retained_customers * 100.0 / NULLIF(total_customers, 0)"
    },
    "metricType": "RATIO",
    "unitOfMeasurement": "PERCENTAGE",
    "granularity": "MONTH",
    "domains": ["Customer"]
  }'

from metadata.sdk import configure
from metadata.sdk.entities import Metrics

configure(
    host="https://your-company.open-metadata.org/api",
    jwt_token="your-jwt-token"
)

# The SDK calculates and submits JSON Patch from the changed entity.
metric = Metrics.retrieve("b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10")
metric.description = "Percentage of active customers retained month over month."
metric.displayName = "Monthly Customer Retention Rate"

updated = Metrics.update(metric)
print(f"Updated to version {updated.version.root}")

// client is an initialized OpenMetadataClient.
var metricId = "b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10";
var metric = client.metrics().get(metricId);

metric.setDescription(
    "Percentage of active customers retained month over month.");
metric.setDisplayName("Monthly Customer Retention Rate");

// update() calculates and submits JSON Patch from the fetched snapshot.
var updated = client.metrics().update(metricId, metric);
System.out.println("Updated to version " + updated.getVersion());

# Update by ID.
curl -X PATCH "{base_url}/api/v1/metrics/b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
    {
      "op": "replace",
      "path": "/description",
      "value": "Percentage of active customers retained month over month."
    },
    {
      "op": "replace",
      "path": "/displayName",
      "value": "Monthly Customer Retention Rate"
    }
  ]'

# Update by fully qualified name.
curl -X PATCH "{base_url}/api/v1/metrics/name/customer_retention_rate" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
    {
      "op": "replace",
      "path": "/metricExpression/code",
      "value": "active_retained_customers * 100.0 / NULLIF(active_customers, 0)"
    }
  ]'

{
  "id": "b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10",
  "name": "customer_retention_rate",
  "displayName": "Monthly Customer Retention Rate",
  "fullyQualifiedName": "customer_retention_rate",
  "description": "Percentage of active customers retained month over month.",
  "metricExpression": {
    "language": "SQL",
    "code": "retained_customers * 100.0 / NULLIF(total_customers, 0)"
  },
  "metricType": "RATIO",
  "unitOfMeasurement": "PERCENTAGE",
  "granularity": "MONTH",
  "version": 0.2,
  "updatedAt": 1787760600000,
  "updatedBy": "admin",
  "href": "https://your-company.open-metadata.org/api/v1/metrics/b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10",
  "deleted": false
}

Update a Metric

Create a metric or update it if it already exists, using PUT /v1/metrics with the full request body. Send the complete definition, not just the fields you want to change. To change only some fields, use PATCH with a JSON Patch array and the application/json-patch+json content type, as shown in the PATCH examples below.

Body Parameters

string

required

Globally unique name of the metric.

string

Human-readable display name for the metric.

string

Description of what the metric measures and how it should be used, in Markdown format.

object

Expression used to calculate the metric.

Show properties

string

Expression language: SQL, Java, JavaScript, Python, or External.

string

Code or external expression that calculates the metric.

string

Metric type: COUNT, SUM, AVERAGE, RATIO, PERCENTAGE, MIN, MAX, MEDIAN, MODE, STANDARD_DEVIATION, VARIANCE, SIMPLE, CUMULATIVE, DERIVED, CONVERSION, or OTHER.

string

Unit: COUNT, DOLLARS, PERCENTAGE, TIMESTAMP, SIZE, REQUESTS, EVENTS, TRANSACTIONS, or OTHER.

string

Custom unit name when unitOfMeasurement is OTHER.

string

Time granularity: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, or YEAR.

array

Dimensions that can be used to group or slice the metric.

Show properties

string

required

Dimension name.

string

Dimension type: CATEGORICAL or TIME.

string

Description of the dimension.

string

Expression used to calculate the dimension.

array

Measures used by the metric.

Show properties

string

required

Measure name.

string

Aggregation function, such as SUM, COUNT, or AVERAGE.

string

Description of the measure.

string

Expression used to calculate the measure.

array

Filters applied when calculating the metric.

Show properties

string

required

SQL WHERE clause for the filter.

Fully qualified names of related metrics.

array

Entity references for data assets this metric is calculated from or applies to.

array

User or team references that own the metric.

array

User or team references responsible for reviewing the metric.

array

Classification tags to apply to the metric.

array

Fully qualified names of domains the metric belongs to.

array

Fully qualified names of data products that include the metric.

object

Custom property values defined by your organization’s metadata schema.

string

default:"user"

Entity provider: system, user, or automation.

PUT /v1/metrics

curl -X PUT "{base_url}/api/v1/metrics" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer_retention_rate",
    "displayName": "Customer Retention Rate",
    "description": "Percentage of customers retained during the month.",
    "metricExpression": {
      "language": "SQL",
      "code": "retained_customers * 100.0 / NULLIF(total_customers, 0)"
    },
    "metricType": "RATIO",
    "unitOfMeasurement": "PERCENTAGE",
    "granularity": "MONTH",
    "domains": ["Customer"]
  }'

from metadata.sdk import configure
from metadata.sdk.entities import Metrics

configure(
    host="https://your-company.open-metadata.org/api",
    jwt_token="your-jwt-token"
)

# The SDK calculates and submits JSON Patch from the changed entity.
metric = Metrics.retrieve("b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10")
metric.description = "Percentage of active customers retained month over month."
metric.displayName = "Monthly Customer Retention Rate"

updated = Metrics.update(metric)
print(f"Updated to version {updated.version.root}")

// client is an initialized OpenMetadataClient.
var metricId = "b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10";
var metric = client.metrics().get(metricId);

metric.setDescription(
    "Percentage of active customers retained month over month.");
metric.setDisplayName("Monthly Customer Retention Rate");

// update() calculates and submits JSON Patch from the fetched snapshot.
var updated = client.metrics().update(metricId, metric);
System.out.println("Updated to version " + updated.getVersion());

# Update by ID.
curl -X PATCH "{base_url}/api/v1/metrics/b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
    {
      "op": "replace",
      "path": "/description",
      "value": "Percentage of active customers retained month over month."
    },
    {
      "op": "replace",
      "path": "/displayName",
      "value": "Monthly Customer Retention Rate"
    }
  ]'

# Update by fully qualified name.
curl -X PATCH "{base_url}/api/v1/metrics/name/customer_retention_rate" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
    {
      "op": "replace",
      "path": "/metricExpression/code",
      "value": "active_retained_customers * 100.0 / NULLIF(active_customers, 0)"
    }
  ]'

{
  "id": "b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10",
  "name": "customer_retention_rate",
  "displayName": "Monthly Customer Retention Rate",
  "fullyQualifiedName": "customer_retention_rate",
  "description": "Percentage of active customers retained month over month.",
  "metricExpression": {
    "language": "SQL",
    "code": "retained_customers * 100.0 / NULLIF(total_customers, 0)"
  },
  "metricType": "RATIO",
  "unitOfMeasurement": "PERCENTAGE",
  "granularity": "MONTH",
  "version": 0.2,
  "updatedAt": 1787760600000,
  "updatedBy": "admin",
  "href": "https://your-company.open-metadata.org/api/v1/metrics/b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10",
  "deleted": false
}

Returns

Returns the updated metric with an incremented version.

Fetch relationship fields before modifying them with an SDK. This gives the SDK a complete baseline from which to calculate additions and removals.

Error Handling

Code	Error Type	Description
`400`	`BAD_REQUEST`	Invalid or malformed request body
`401`	`UNAUTHORIZED`	Invalid or missing authentication token
`403`	`FORBIDDEN`	User lacks permission to update this metric
`409`	`CONFLICT`	Concurrent modification or naming conflict

API Reference

Data Assets

AI Assets

AI SDK

SDK

Discovery

Lineage

Data Contracts

Teams And Users

Data Governance

Data Quality

Alerts

Incidents

Main Concepts

Update a Metric

Update a Metric

Body Parameters

Returns

Error Handling

​Update a Metric

​Body Parameters

​Returns

​Error Handling

Update a Metric

Body Parameters

Returns

Error Handling