POST /v1/dataQuality/testCases

from metadata.sdk import configure
from metadata.sdk.entities import TestCases
from metadata.generated.schema.api.tests.createTestCase import CreateTestCaseRequest

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

# Create a column-level test case
request = CreateTestCaseRequest(
    name="column_value_max_to_be_between",
    testDefinition="columnValueMaxToBeBetween",
    entityLink="<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>",
    parameterValues=[
        {"name": "minValueForMaxInCol", "value": "1"},
        {"name": "maxValueForMaxInCol", "value": "100"}
    ],
    description="Validates shop_id max value stays between 1 and 100"
)

test_case = TestCases.create(request)
print(f"Created: {test_case.fullyQualifiedName.root}")

import org.openmetadata.sdk.fluent.builders.TestCaseBuilder;

// client is an initialized OpenMetadataClient.
var testCase = TestCaseBuilder.create(client)
    .name("column_value_max_to_be_between")
    .testDefinition("columnValueMaxToBeBetween")
    .entityLink("<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>")
    .parameter("minValueForMaxInCol", "1")
    .parameter("maxValueForMaxInCol", "100")
    .create();

curl -X POST "{base_url}/api/v1/dataQuality/testCases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "column_value_max_to_be_between",
    "testDefinition": "columnValueMaxToBeBetween",
    "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>",
    "parameterValues": [
      {"name": "minValueForMaxInCol", "value": "1"},
      {"name": "maxValueForMaxInCol", "value": "100"}
    ],
    "description": "Validates shop_id max value stays between 1 and 100"
  }'

curl -X POST "{base_url}/api/v1/dataQuality/testCases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders_no_negative_amounts",
    "testDefinition": "tableCustomSQLQuery",
    "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.orders>",
    "parameterValues": [
      {"name": "sqlExpression", "value": "SELECT * FROM orders WHERE amount < 0"},
      {"name": "strategy", "value": "ROWS"},
      {"name": "operator", "value": "=="},
      {"name": "threshold", "value": "0"}
    ],
    "computePassedFailedRowCount": true
  }'

curl -X POST "{base_url}/api/v1/dataQuality/testCases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "email_max_length",
    "testDefinition": "columnValuesMaxLength",
    "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::email>",
    "parameterValues": [
      {"name": "maxLength", "value": "50"},
      {"name": "threshold", "value": "5"},
      {"name": "thresholdUnit", "value": "PERCENTAGE"}
    ],
    "computePassedFailedRowCount": true
  }'

{
  "id": "c1bce355-fa2f-48c6-ab4d-fad722a56ed7",
  "name": "column_value_max_to_be_between",
  "fullyQualifiedName": "sample_data.ecommerce_db.shopify.dim_address.shop_id.column_value_max_to_be_between",
  "description": "Validates shop_id max value stays between 1 and 100",
  "version": 0.1,
  "updatedAt": 1769982759035,
  "updatedBy": "admin",
  "testDefinition": {
    "id": "def-id",
    "type": "testDefinition",
    "name": "columnValueMaxToBeBetween",
    "fullyQualifiedName": "columnValueMaxToBeBetween",
    "deleted": false
  },
  "testSuite": {
    "id": "suite-id",
    "type": "testSuite",
    "name": "sample_data.ecommerce_db.shopify.dim_address.testSuite",
    "deleted": false
  },
  "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>",
  "parameterValues": [
    {"name": "minValueForMaxInCol", "value": "1"},
    {"name": "maxValueForMaxInCol", "value": "100"}
  ],
  "deleted": false,
  "owners": []
}

POST

dataQuality

testCases

POST /v1/dataQuality/testCases

from metadata.sdk import configure
from metadata.sdk.entities import TestCases
from metadata.generated.schema.api.tests.createTestCase import CreateTestCaseRequest

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

# Create a column-level test case
request = CreateTestCaseRequest(
    name="column_value_max_to_be_between",
    testDefinition="columnValueMaxToBeBetween",
    entityLink="<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>",
    parameterValues=[
        {"name": "minValueForMaxInCol", "value": "1"},
        {"name": "maxValueForMaxInCol", "value": "100"}
    ],
    description="Validates shop_id max value stays between 1 and 100"
)

test_case = TestCases.create(request)
print(f"Created: {test_case.fullyQualifiedName.root}")

import org.openmetadata.sdk.fluent.builders.TestCaseBuilder;

// client is an initialized OpenMetadataClient.
var testCase = TestCaseBuilder.create(client)
    .name("column_value_max_to_be_between")
    .testDefinition("columnValueMaxToBeBetween")
    .entityLink("<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>")
    .parameter("minValueForMaxInCol", "1")
    .parameter("maxValueForMaxInCol", "100")
    .create();

curl -X POST "{base_url}/api/v1/dataQuality/testCases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "column_value_max_to_be_between",
    "testDefinition": "columnValueMaxToBeBetween",
    "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>",
    "parameterValues": [
      {"name": "minValueForMaxInCol", "value": "1"},
      {"name": "maxValueForMaxInCol", "value": "100"}
    ],
    "description": "Validates shop_id max value stays between 1 and 100"
  }'

curl -X POST "{base_url}/api/v1/dataQuality/testCases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders_no_negative_amounts",
    "testDefinition": "tableCustomSQLQuery",
    "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.orders>",
    "parameterValues": [
      {"name": "sqlExpression", "value": "SELECT * FROM orders WHERE amount < 0"},
      {"name": "strategy", "value": "ROWS"},
      {"name": "operator", "value": "=="},
      {"name": "threshold", "value": "0"}
    ],
    "computePassedFailedRowCount": true
  }'

curl -X POST "{base_url}/api/v1/dataQuality/testCases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "email_max_length",
    "testDefinition": "columnValuesMaxLength",
    "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::email>",
    "parameterValues": [
      {"name": "maxLength", "value": "50"},
      {"name": "threshold", "value": "5"},
      {"name": "thresholdUnit", "value": "PERCENTAGE"}
    ],
    "computePassedFailedRowCount": true
  }'

{
  "id": "c1bce355-fa2f-48c6-ab4d-fad722a56ed7",
  "name": "column_value_max_to_be_between",
  "fullyQualifiedName": "sample_data.ecommerce_db.shopify.dim_address.shop_id.column_value_max_to_be_between",
  "description": "Validates shop_id max value stays between 1 and 100",
  "version": 0.1,
  "updatedAt": 1769982759035,
  "updatedBy": "admin",
  "testDefinition": {
    "id": "def-id",
    "type": "testDefinition",
    "name": "columnValueMaxToBeBetween",
    "fullyQualifiedName": "columnValueMaxToBeBetween",
    "deleted": false
  },
  "testSuite": {
    "id": "suite-id",
    "type": "testSuite",
    "name": "sample_data.ecommerce_db.shopify.dim_address.testSuite",
    "deleted": false
  },
  "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>",
  "parameterValues": [
    {"name": "minValueForMaxInCol", "value": "1"},
    {"name": "maxValueForMaxInCol", "value": "100"}
  ],
  "deleted": false,
  "owners": []
}

Create a Test Case

Create a new test case by linking a test definition to a specific table or column with concrete parameter values. The server associates the test case with the basic suite of the table in entityLink, creating that suite if needed. Omit testSuite from the create request. Automatically created suites are named <tableFQN>.testSuite. An existing basic suite keeps its name.

Body Parameters

string

required

Name of the test case. Must be unique within the target entity scope.

string

required

Fully qualified name (FQN) of the test definition to use. For example, columnValueMaxToBeBetween. For a custom SQL test (the Custom SQL Query test type in the UI), use tableCustomSQLQuery. For a test case on a custom test definition you created, use that definition’s name, such as columnValuesMaxLength. For more information, see Custom SQL Test Cases.

string

required

Entity link to the target table or column. Format: <#E::table::tableFQN> for table-level or <#E::table::tableFQN::columns::colName> for column-level.

array

Array of parameter name/value pairs as defined by the test definition.

Show properties

string

required

Parameter name. Must match a parameter in the test definition.

string

required

Parameter value. Always provide it as a string.

string

Description of the test case in Markdown format.

string

Human-readable display name for the test case.

array

Array of reviewer references (users or teams). Each item accepts the same fields as owners.

boolean

Compute the passed and failed row count for the test case. Defaults to false.

boolean

Use dynamic assertion to evaluate the test case, if the test definition supports it. Defaults to false.

array

Names of the columns to group test results by. When set, the test runs overall and grouped by these columns. Defaults to [].

integer

Number of top dimension values to show before the rest are grouped as Others. Accepts 1 to 50. Defaults to 5.

string

Name of the data quality dimension for this test case. Defaults to the dimension of the test definition. Accepts a built-in dimension or any custom dimension registered in Settings > Preferences > Data Quality.

array

Array of owner references (users or teams) to assign.

Show properties

string

UUID of the owner entity.

string

Owner entity type, such as user or team.

string

Name of the owner entity.

POST /v1/dataQuality/testCases

from metadata.sdk import configure
from metadata.sdk.entities import TestCases
from metadata.generated.schema.api.tests.createTestCase import CreateTestCaseRequest

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

# Create a column-level test case
request = CreateTestCaseRequest(
    name="column_value_max_to_be_between",
    testDefinition="columnValueMaxToBeBetween",
    entityLink="<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>",
    parameterValues=[
        {"name": "minValueForMaxInCol", "value": "1"},
        {"name": "maxValueForMaxInCol", "value": "100"}
    ],
    description="Validates shop_id max value stays between 1 and 100"
)

test_case = TestCases.create(request)
print(f"Created: {test_case.fullyQualifiedName.root}")

import org.openmetadata.sdk.fluent.builders.TestCaseBuilder;

// client is an initialized OpenMetadataClient.
var testCase = TestCaseBuilder.create(client)
    .name("column_value_max_to_be_between")
    .testDefinition("columnValueMaxToBeBetween")
    .entityLink("<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>")
    .parameter("minValueForMaxInCol", "1")
    .parameter("maxValueForMaxInCol", "100")
    .create();

curl -X POST "{base_url}/api/v1/dataQuality/testCases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "column_value_max_to_be_between",
    "testDefinition": "columnValueMaxToBeBetween",
    "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>",
    "parameterValues": [
      {"name": "minValueForMaxInCol", "value": "1"},
      {"name": "maxValueForMaxInCol", "value": "100"}
    ],
    "description": "Validates shop_id max value stays between 1 and 100"
  }'

curl -X POST "{base_url}/api/v1/dataQuality/testCases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders_no_negative_amounts",
    "testDefinition": "tableCustomSQLQuery",
    "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.orders>",
    "parameterValues": [
      {"name": "sqlExpression", "value": "SELECT * FROM orders WHERE amount < 0"},
      {"name": "strategy", "value": "ROWS"},
      {"name": "operator", "value": "=="},
      {"name": "threshold", "value": "0"}
    ],
    "computePassedFailedRowCount": true
  }'

curl -X POST "{base_url}/api/v1/dataQuality/testCases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "email_max_length",
    "testDefinition": "columnValuesMaxLength",
    "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::email>",
    "parameterValues": [
      {"name": "maxLength", "value": "50"},
      {"name": "threshold", "value": "5"},
      {"name": "thresholdUnit", "value": "PERCENTAGE"}
    ],
    "computePassedFailedRowCount": true
  }'

{
  "id": "c1bce355-fa2f-48c6-ab4d-fad722a56ed7",
  "name": "column_value_max_to_be_between",
  "fullyQualifiedName": "sample_data.ecommerce_db.shopify.dim_address.shop_id.column_value_max_to_be_between",
  "description": "Validates shop_id max value stays between 1 and 100",
  "version": 0.1,
  "updatedAt": 1769982759035,
  "updatedBy": "admin",
  "testDefinition": {
    "id": "def-id",
    "type": "testDefinition",
    "name": "columnValueMaxToBeBetween",
    "fullyQualifiedName": "columnValueMaxToBeBetween",
    "deleted": false
  },
  "testSuite": {
    "id": "suite-id",
    "type": "testSuite",
    "name": "sample_data.ecommerce_db.shopify.dim_address.testSuite",
    "deleted": false
  },
  "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>",
  "parameterValues": [
    {"name": "minValueForMaxInCol", "value": "1"},
    {"name": "maxValueForMaxInCol", "value": "100"}
  ],
  "deleted": false,
  "owners": []
}

Returns

Returns the created test case object with all specified properties and system-generated fields.

Response

string

Unique identifier for the test case (UUID format).

string

Test case name.

string

Fully qualified name in format table.column.testCaseName or table.testCaseName.

string

Description of the test case.

object

Reference to the test definition.

Show properties

string

UUID of the test definition.

string

Always testDefinition.

string

Name of the test definition.

string

FQN of the test definition.

object

Reference to the test suite.

Show properties

string

UUID of the test suite.

string

Always testSuite.

string

Name of the test suite.

string

Entity link to the target table or column.

array

Parameter values for this test case.

Show properties

string

Parameter name.

string

Parameter value.

array

List of owners assigned to the test case.

number

Version number for the entity (starts at 0.1).

Create or Update (PUT)

Use PUT /v1/dataQuality/testCases instead of POST to perform an upsert. If a test case with the same fullyQualifiedName already exists, the server updates it. Otherwise, the server creates a new test case. PUT accepts the same body parameters as POST, including the optional description field. Both curl examples include description.

curl -X PUT "{base_url}/api/v1/dataQuality/testCases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "column_value_max_to_be_between",
    "testDefinition": "columnValueMaxToBeBetween",
    "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::shop_id>",
    "parameterValues": [
      {"name": "minValueForMaxInCol", "value": "1"},
      {"name": "maxValueForMaxInCol", "value": "100"}
    ],
    "description": "Validates shop_id max value stays between 1 and 100"
  }'

PUT updates an existing entity instead of returning a 409 conflict error.

Custom SQL Test Cases

OpenMetadata has two ways to run SQL in a test case:

Custom SQL test: the Custom SQL Query test type in the UI. The test case uses the built-in tableCustomSQLQuery test definition and carries the SQL itself in parameterValues. You don’t create a test definition.
Custom test definition: a reusable SQL template you create once, with {{ paramName }} placeholders. Test cases then reference it by name. For more information, see Test Cases for a Custom Test Definition.

A test case passes values to a SQL-based test definition through parameterValues. The server rejects any parameter that the test definition doesn’t declare in parameterDefinition, and requires every parameter marked required.

Custom SQL Test

The built-in tableCustomSQLQuery test definition runs a SQL query against a table. It accepts these parameters:

Parameter	Required	Description
`sqlExpression`	Yes	SQL query to run against the table.
`strategy`	No	`ROWS` runs the query as written. `COUNT` runs it as a `COUNT` query. Defaults to `ROWS`.
`operator`	No	Comparison between the query result and `threshold`: `==`, `>`, `>=`, `<`, `<=`, or `!=`.
`threshold`	No	Value to compare the result against. Defaults to `0`.
`partitionExpression`	No	Partition expression used to compute the passed and failed row count when `computePassedFailedRowCount` is enabled.
`thresholdUnit`	No	How to read `threshold`: `ABSOLUTE` for a raw count of failures, or `PERCENTAGE` for a share of the evaluated rows. Defaults to `ABSOLUTE`.

curl -X POST "{base_url}/api/v1/dataQuality/testCases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders_no_negative_amounts",
    "testDefinition": "tableCustomSQLQuery",
    "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.orders>",
    "parameterValues": [
      {"name": "sqlExpression", "value": "SELECT * FROM orders WHERE amount < 0"},
      {"name": "strategy", "value": "ROWS"},
      {"name": "operator", "value": "=="},
      {"name": "threshold", "value": "0"}
    ],
    "computePassedFailedRowCount": true
  }'

Test Cases for a Custom Test Definition

A test case for a custom SQL test definition sets testDefinition to the definition’s name and passes one parameterValues entry per {{ paramName }} placeholder. The following request uses a custom columnValuesMaxLength definition, which declares maxLength, threshold, and thresholdUnit:

curl -X POST "{base_url}/api/v1/dataQuality/testCases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "email_max_length",
    "testDefinition": "columnValuesMaxLength",
    "entityLink": "<#E::table::sample_data.ecommerce_db.shopify.dim_address::columns::email>",
    "parameterValues": [
      {"name": "maxLength", "value": "50"},
      {"name": "threshold", "value": "5"},
      {"name": "thresholdUnit", "value": "PERCENTAGE"}
    ],
    "computePassedFailedRowCount": true
  }'

Pass condition: The test case passes when the number of rows the SQL returns is within the tolerance. With no threshold, any returned row fails the test case.
Threshold: threshold and thresholdUnit apply only if the test definition declares thresholdUnit. With ABSOLUTE, threshold is a row count. With PERCENTAGE, it is a share of the evaluated rows and can’t exceed 100. A negative or non-numeric threshold returns a 400 error.
Row counts: Set computePassedFailedRowCount to true to report passed and failed row counts.

For more information, see Create a Test Definition.

Parameter Validation

OpenMetadata checks a new test case against its test definition before it stores it:

Parameter values: Each value must be one of the optionValues of the matching parameter in the test definition. The comparison ignores case, and a blank value counts as not set.
Column data type: When the test definition lists supportedDataTypes, the data type of the column in entityLink must be one of them.

A request that fails either check returns 400. POST /v1/dataQuality/testCases and POST /v1/dataQuality/testCases/createMany both apply the checks. createMany checks every test case before it stores any, so one rejected test case means none are stored. An update checks only what it changes. A changed parameter value must be one of the options, and a test case moved to another column or test definition is checked in full. A test case stored before these checks, or one whose column changed data type later, stays editable.

Error Handling

Code	Error Type	Description
`400`	`BAD_REQUEST`	Invalid request body, missing required fields, a parameter value that is not one of the definition’s options, or a column data type the definition does not support
`401`	`UNAUTHORIZED`	Invalid or missing authentication token
`403`	`FORBIDDEN`	User lacks permission to create test cases
`409`	`ENTITY_ALREADY_EXISTS`	Test case with same name already exists for this entity (POST only)

API Reference

Data Assets

Collaboration

AI SDK

SDK

Discovery

Lineage

Data Contracts

Teams And Users

Data Governance

Data Quality

Alerts

Incidents

Main Concepts

Create a Test Case

Create a Test Case

Body Parameters

Returns

Response

Create or Update (PUT)

Custom SQL Test Cases

Custom SQL Test

Test Cases for a Custom Test Definition

Parameter Validation

Error Handling