--- title: "Test rule" method: POST path: "/data-quality/v1/rules/{ruleUrn}/test" tags: ["Data Quality Rules"] --- # Test rule `POST /data-quality/v1/rules/{ruleUrn}/test` ## Request - Base URL: `https://your-environment.ataccama.one/api` - URL: `https://your-environment.ataccama.one/api/data-quality/v1/rules/{ruleUrn}/test` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Evaluate the rule against sample rows sent in the request, and get one result per row. Use it to check the rule logic before you publish the rule or run it in a DQ monitor. Nothing is stored, and no DQ monitor or DQ evaluation is involved. The rule is evaluated in its draft version when it has one, and in its published version otherwise, so you can test a change before you publish it. Each row carries the values of the rule inputs keyed by input `name`, as strings that are converted to the input's `dataType`. A value that cannot be converted, such as `abc` for an `INTEGER` input, is rejected with `400`. Values of the rule parameters are sent in `parameterValues`. **Cross-table rules** For a `CROSS_TABLE` rule, send the parent table's rows in `records`, the joined table's rows in `joinedRecords`, and the names of the join-key attributes in `join`. Each row carries its join-key value next to its input values. Results are returned for the parent rows only. **Aggregation rules** For an `AGGREGATION` rule, the submitted `records` are grouped by the rule's `groupByInputs` and the conditions are evaluated per group, as in a DQ evaluation. Each row gets the result of its group, so a row's result depends on the other rows sent in the same request. **Failures** - A malformed request, such as an unknown input name, a value that does not match its input's `dataType`, or a missing `join` for a `CROSS_TABLE` rule, is rejected with `400`. - A rule that cannot be evaluated as a whole in its current state, such as one with a condition expression that does not compile, is rejected with `409`. - A row the evaluation engine returns no result for is reported as `ERROR` in its own `outcome`, without failing the other rows. ## Path parameters - `ruleUrn` string, uri, required: A URN identifying the data quality rule resource in the Data Quality API. Format: urn:ata:{tenant}:data-quality:rule:{uuid} Example: urn:ata:acme-corp:data-quality:rule:123e4567-e89b-12d3-a456-426614174000. ## Request body - RuleTestInput: Sample data and parameter values for a single test run of a rule. For a single-table rule, send the rows in `records` and omit `join` and `joinedRecords`. For a `CROSS_TABLE` rule, `records` holds the rows of the parent table, `joinedRecords` the rows of the joined table, and `join` names the join-key attribute on each side; all three are required, and omitting any of them is rejected with `400`. `join` and `joinedRecords` sent for a single-table rule are rejected with `400` as well. - `records` RuleTestRecord[], required: Rows to evaluate; for a `CROSS_TABLE` rule, the rows of the parent table. Each row holds the values of the inputs in the rule's input groups with `joined: false`. One result is returned per row, in the same order. For an `AGGREGATION` rule, the rows are grouped by the rule's `groupByInputs` and each row gets the result of its group, so send all the rows of a group you want to check in the same request. - `values` object, required: Values of the row, keyed by the `name` of the rule input each belongs to. Every value is a string converted to the input's `dataType` for evaluation. An input that is not listed, or whose value is `null` or an empty string, is evaluated as an empty value. A value that cannot be converted to its input's `dataType`, such as `abc` for an `INTEGER` input, is rejected with `400`. For a `CROSS_TABLE` rule, the row also carries its join-key value, under the attribute name given in `join`. Any other key that does not name an input on the row's side of the rule is rejected with `400`. - `joinedRecords` RuleTestRecord[]: Rows of the joined table of a `CROSS_TABLE` rule. Each row holds the values of the inputs in the rule's input group with `joined: true`. Joined rows get no result of their own: they contribute to the results of the parent rows they join to. - `values` object, required: Values of the row, keyed by the `name` of the rule input each belongs to. Every value is a string converted to the input's `dataType` for evaluation. An input that is not listed, or whose value is `null` or an empty string, is evaluated as an empty value. A value that cannot be converted to its input's `dataType`, such as `abc` for an `INTEGER` input, is rejected with `400`. For a `CROSS_TABLE` rule, the row also carries its join-key value, under the attribute name given in `join`. Any other key that does not name an input on the row's side of the rule is rejected with `400`. - `join` RuleTestJoin: The join key of a `CROSS_TABLE` rule test run. A parent row joins to every joined row whose join-key value equals its own; the values are compared as strings. - `parentAttributeName` string, required: Name under which each row of `records` carries its join-key value. A name that matches one of the rule's parent-table inputs is rejected with `400`. - `joinedAttributeName` string, required: Name under which each row of `joinedRecords` carries its join-key value. A name that matches one of the rule's joined-table inputs is rejected with `400`. - `parameterValues` object: Values of the rule's parameters for this run, keyed by the parameter `name`. Each value is a string converted to the parameter's `dataType`. A parameter that is not listed has no value. A key that does not name a parameter of the rule is rejected with `400`. ## Response `200` One result per submitted row of `records`, in the same order. - RuleTestResult: The outcome of a rule test run. - `results` RuleTestRecordResult[], required: One entry per row of the request's `records`, in the same order: `results[i]` is the outcome of `records[i]`. - `outcome` string, required: @ExtensibleEnum How the row was evaluated: - `CONDITION_MATCHED`: a condition of the rule matched the row. `conditionUrn` and `dimensionResultUrn` identify it and the dimension result it assigns. - `FALLBACK`: no condition matched, so the rule's fallback applied. `dimensionResultUrn` is the fallback's dimension result. - `ERROR`: the evaluation engine returned no result for the row. No further detail is available, and the other rows are not affected. Values that do not fit their input's `dataType` are rejected with `400` before evaluation, so this is not expected for valid input. - `conditionUrn` string, uri: A URN identifying the data quality rule condition resource in the Data Quality API. Format: urn:ata:{tenant}:data-quality:rule-condition:{uuid} Example: urn:ata:acme-corp:data-quality:rule-condition:123e4567-e89b-12d3-a456-426614174000. - `dimensionResultUrn` string, uri: A URN identifying the DQ dimension result resource in the Data Quality API. Format: urn:ata:{tenant}:data-quality:dq-dimension-result:{uuid} Example: urn:ata:acme-corp:data-quality:dq-dimension-result:123e4567-e89b-12d3-a456-426614174000. ## Other responses - `400`: Bad request. The request parameters or body are invalid. - `403`: Forbidden. You do not have permission to access the requested resource. - `404`: Not found. The requested resource does not exist. - `409`: The request conflicts with the current state. --- [API](https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api.md) - [All operations](https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api/revisions/46f16e0487f8?raw)