Import API

Request parameters

Responses

Field reference

Field names, types and rules for the four entity types of the CRUD flow. "Default" is what a create stores when the field is left out; on an update, a left-out scalar field is reset to that default, so always send the full entity (for example the result of GET /api/v1/import/reference/{uuid}). Lists follow the update rule above: left out keeps, empty clears. Unknown fields are ignored.

All entities:

DYNAMIC_RULE

TEST_SUITE

TEST_CASE

BUSINESS_RULE

An update keeps the rule's folder, dynamic rule link and auto-generate setting.

Schedule fields (TEST_SUITE and TEST_CASE)

Get entity by reference

Returns { entityType, entity } in the import format; the entity type is resolved from the reference. The response can be posted back to /api/v1/import unchanged. Needs the IMPORT scope.

Response example for a business rule:

Works for dynamic rules, test suites, test cases and business rules. Returns 404 when the reference is unknown, its entity no longer exists or it belongs to another type (connections, webhooks, variables and parameters are not read back), and 400 when the path is not a UUID.

Request parameters

Responses

Term mentions in descriptions

Description texts can embed glossary term mentions. Exports serialize each mention as a portable token in the form @[Label](key:|Glossary path|Term name|) (the glossary segment is empty for root terms). On import each token is matched against the glossary: a resolved mention becomes a live term link again, and an unresolved one keeps its label and re-links automatically once a matching term exists (for example later in the same import batch). Plain-text descriptions written by hand import as-is - the tokens only matter when round-tripping exported data.

TEST_CASE

Import test cases. connectionRef and testsuiteRef must reference existing entities (or be included earlier in the same deployment flow). relations.schema and relations.object bind the test case to a catalog object so lineage and alerting work correctly.

saveResults keeps each execution's result rows, and resultsInReportRows sets how many breached records the test case's failure alerts list. Both are stored as sent: a resultsInReportRows above 0 makes the execution save results even when saveResults is false, but it does not turn the stored flag on. resultsInReportRows is clamped to 0..1000 silently, so a value above 1000 is imported as 1000 rather than rejected.

Request example:

Key fields:

• type - Query, Query + total or Compare; any other value fails the entry. Compare additionally requires compareConnectionRef and compareSql.

• dynamicRuleRef - optional UUID of the parent dynamic rule when this case was generated from one.

• labels - on an update, leave the key out to keep the current labels, send [] to clear them.

• severity - CRITICAL, WARNING, INFO.

• scheduleType - see Scheduling. Omit or use NOT_SCHEDULED to inherit the test suite schedule.

TEST_SUITE

Import test suites. Referenced test cases are linked through testsuiteRef in the test case payload - a test suite import does not embed its test cases.

Request example:

Key fields:

• directory - forward-slash separated folder path. Missing folders are created on import.

• emailThreshold - percentage of failing test cases (0 to 100) above which an email notification is sent.

• alertMode - ALWAYS or ON_FAILURE.

• visibility - PUBLIC, PRIVATE or READ_ONLY. PUBLIC is viewable and editable by everyone, PRIVATE is viewable and editable only by the owner and users matching allowedRoles, READ_ONLY is viewable by everyone but only editable by the owner and users matching allowedRoles.

• allowedRoles - comma-separated role names. Used when visibility is PRIVATE (controls view and edit) or READ_ONLY (controls edit only). Ignored when visibility is PUBLIC.

• scheduleType - NOT_SCHEDULED, SELECTED_DAYS, MONTHLY, CUSTOM, CRON. Additional fields scheduleDay, scheduleTime, scheduleDate, scheduleCustom are used depending on the chosen type - see Scheduling. Fields the type does not use can be left out; they get the scheduling form's defaults (every day, 09:00, day 1, interval 300). A CRON schedule needs only scheduleCustom with the cron expression, for example "0 6 * * 1-5"; without one the entity fails with "A CRON schedule needs a cron expression in scheduleCustom". On an update, leaving scheduleType out keeps the suite's current schedule; NOT_SCHEDULED removes it.

• tags, webhookRefs, emails, allowedRoles - on an update, leave the key out to keep the current value, send an empty value to clear it. A webhookRefs UUID that does not resolve is skipped with a warning.

CONNECTION

Import database connections. Credentials are not included in the payload and must be set through the Connections UI or the secrets backend after import.

Request example:

Key fields:

• type - connector identifier as shown in the Connections UI (e.g. postgresql, mssql, snowflake, bigquery). See Connections.

• jdbcUrlOverride - use this to supply a full JDBC URL instead of the discrete databaseUrl/databasePort/databaseName triple.

DYNAMIC_RULE

Import dynamic rules - SQL templates that generate test cases based on metadata.

Request example:

Key fields:

• sql - may use the {schema}, {object} and {column} placeholders that are substituted per generated test case.

• drivers - list of connector types this dynamic rule applies to. Leave empty for all. On an update, leave the key out to keep the current drivers; [] clears them.

VARIABLE

Import global variables usable in SQL via ${variableName} syntax.

Request example:

WEBHOOK

Import webhook definitions used for alerting.

Request example:

Key fields:

• json - request body template. Placeholders such as {{testSuiteName}}, {{failedCount}} are substituted by the alerting engine when the webhook fires.

PARAMETER

Import per-test-case parameter overrides. values[].testCaseRef must match an existing test case UUID.

Request example:

Parameter values are fully replaced on import: any existing values for the parameter that are not listed in the values array are removed.

BUSINESS_RULE

Import business rules. The testCaseRefs field links the rule to test cases by UUID - those test cases must already exist or be imported in the same deployment.

Request example:

Key fields:

• owners - user names or display names. An unknown name is skipped with a warning.

• owners, allowedRoles, testCaseRefs - on an update, leave the key out to keep the current value, send [] to clear it. A testCaseRefs UUID that does not resolve is skipped with a warning.

An update changes the name, description and the lists above. The rule's folder, its dynamic rule link and the auto-generate setting are kept, since the import format does not carry them.

Business rules are also importable from CSV via /api/v1/import/csv?type=BUSINESS_RULE, however CSV import does not link test cases - use the JSON endpoint if you need to set testCaseRefs.

OBJECT

CSV import only via /api/v1/import/csv?type=OBJECT. Imports catalog objects (tables and views) into the catalog. Expected CSV headers match the OBJECT export template downloadable from the catalog import UI.

COLUMN

CSV import only via /api/v1/import/csv?type=COLUMN. Imports column descriptions and metadata attached to existing catalog objects. Expected CSV headers match the COLUMN export template.

COLUMN_RELATION

CSV import only via /api/v1/import/csv?type=COLUMN_RELATION. Imports column-level lineage relations between catalog columns. For SQL-driven lineage that the platform should parse for you instead, use the Import lineage endpoint.

COLUMN_TERM_RELATION

CSV import only via /api/v1/import/csv?type=COLUMN_TERM_RELATION. Imports the mapping between catalog columns and business glossary terms. The term column uses the term reference format, so glossary-scoped terms are written as My glossary|Term name.

TERM

CSV import only via /api/v1/import/csv?type=TERM. Imports business glossary terms.

Columns: name (required), color, description, type, glossary, plus one cf_ column per custom field defined for terms (multiple values within one cell are separated by ;). glossary is the full path of an existing glossary with nested levels joined by / (e.g. Finance/Accounting); when it is empty or does not match an existing glossary, the term is placed at the glossary root. An unknown type value creates that term type. Descriptions may carry term mention tokens; values of term-type custom fields use the term reference format.

TERM_RELATION

CSV import only via /api/v1/import/csv?type=TERM_RELATION. Imports relations between business glossary terms.

Columns: sourceName, relation, targetName. Both term columns use the term reference format - there is no separate glossary column, the glossary path is part of the term reference (My glossary|Term name).

The relation value is matched case-insensitively against the built-in relations (Synonym, Related to, Contains) and the custom relation types defined under Settings. A directed custom relation is accepted by either of its side names - importing the inverse side swaps source and target, so the stored relation always uses the type's original direction. An unknown relation value creates a new custom relation type with that name. Rows that duplicate an existing relation are reported as failed, and Contains relations are validated against containment cycles.

Request parameters

Responses

What the counters mean

total is the number of relations resolved from the submitted queries, and every one of them lands in exactly one of the next four counters:

• created - the relation did not exist and a new row was inserted.

• updated - the relation already existed, and this call attached new query evidence to its reference chain.

• unchanged - the relation already existed and its whole reference chain was already there. Nothing was written; the import was an idempotent no-op.

• failed - reserved. Lineage import has no partial failure: a query that resolves to no known columns is skipped before counting and never reaches total, while a genuine error aborts the whole call. The counter is in the sum for consistency with the other import endpoints.

So for a lineage import:

deleted sits outside that sum, because the relations it counts were removed from a previous batch and were never part of the submitted payload.

unchanged is present only on the lineage import response. The other import endpoints do not detect a no-op, so they omit the field rather than report a zero they cannot stand behind, and so does the delete endpoint below, which submits no relations to leave unchanged.

A worked example. Import a query for the first time:

Import the identical query again, under a new batchId or with none:

Nothing was written, and unchanged: 1 is what says so. Before this counter existed the same call answered with every counter at zero, which was indistinguishable from an import that resolved nothing. Now import that same query together with a new one:

Batches

When you omit batchId, a UUID is generated, persisted as the batch handle, and returned in the response. Pass that same id to a later call to replace the batch, or to the delete endpoint below to remove it. Re-importing under an existing batchId replaces the batch: relations that reappear in the payload are reported as updated, and relations no longer present are removed and counted in deleted.

Note the interaction with unchanged. Replacing under the same batchId clears that batch's own reference rows first, so a relation that reappears is written afresh and counts as updated rather than unchanged. A nightly job that always passes the same batchId will therefore normally keep reporting updated, even when nothing about the lineage has actually changed.

That sweep is scoped to the batch's own rows. If identical evidence also exists under a different batchId, or with no batch at all (an import from the user interface, for instance), it survives the sweep and still matches, so the same call reports unchanged instead. In short: unchanged means nothing needed writing, and whether a same-batch re-import reaches that state depends on whether any other batch already holds the same evidence.

Request parameters

Responses

Request parameters

Responses