Promote FAQ

What is the difference between promoting quality checks and computed fields?

Quality checks operate on validation rules (rule type, fields, properties, and filter), while computed fields are transformation definitions. Quality checks use overlap-based matching to detect duplicates (same rule type, fields, properties, and filter), whereas computed fields use name-based matching. Additionally, quality checks support a Draft mode option, while computed fields are always promoted as active.

My destination fields have different casing than the source (e.g., Email vs email). Will promote still work?

Yes. Field-name resolution is case-insensitive for both quality checks and computed fields. A check or computed field that references Email will bind to a destination field named email (or EMAIL). The destination's original casing is preserved — only the lookup is normalized.

Does a promote operation copy or move any of my actual data?

No. Promote is a metadata-only operation — it carries definitions (rules, transformations, container specs) from source to destination, but no data rows are read from the source or written to the destination by the promote step itself. The follow-up profile (slim or full) that runs after promotion does scan the destination to populate metadata for the new entities, but the source data is untouched.

Can I promote quality checks across different datastores?

Yes. Quality checks can be promoted from a container on one datastore to a container on any other datastore. The only requirement is that the destination container has fields with matching names for the check's field references. If a required field is missing, the check is promoted as Draft with a warning.

What happens if I promote a check and the destination field doesn't exist?

The check is promoted as Draft with a warning message indicating that no compatible fields were found. You can manually update the check's field mapping on the destination or add the missing field and re-promote.

What happens if I promote the same entity twice?

The platform finds the destination produced by the previous promotion and either updates it (if the source definition has changed) or skips it (if the definitions are identical, so nothing needs to change). See Entity Matching for how the lookup works.

What exactly counts as a "match" when there's no record of a previous promotion?

For computed fields, tables, and files, the platform matches by entity name on the destination. For quality checks, the platform uses overlap matching: two checks are considered the same if they have the same rule type, the same field set (compared case-insensitively), the same rule-specific properties (a fixed allow-list per rule type), and the same filter expression (case- and whitespace-sensitive; NULL is treated as the empty string). Description, tags, and unrelated metadata do not affect the match. See Entity Matching for the precise rules.

Why did my re-promote create a duplicate check instead of updating the existing one?

The most common cause is a filter mismatch. When the platform falls back to overlap matching (no record of a previous promotion exists), it compares filter expressions character-for-character — extra whitespace, a different quote style, or a re-ordered predicate all defeat the match. If the destination check was created via a previous promote, the recorded source-to-destination link makes the filter irrelevant; if it was created or edited manually, normalize the filter on either side to align them.

Can I promote to the same container or datastore?

No. The destination must be different from the source. The platform prevents you from selecting the source container or datastore as the destination.

What does "skipped" mean in the promote results?

A skipped result means the platform found a matching entity at the destination — either a destination produced by a previous promotion, or one detected via fallback matching — and determined that the definitions are identical, so no update is needed.

What does "failed" mean in the promote results?

A failed result means the platform encountered an error while promoting that specific entity. The error message in the result provides details about why the promotion failed. Common causes include missing source fields, name collisions with non-computed fields, or validation errors for active checks.

Can I undo a promote operation?

No. There is no built-in undo for promote operations. If you need to revert promoted entities, you must manually delete or modify them at the destination. To minimize risk, use Draft mode for quality checks so you can review before activating.

What happens to tags during promotion?

Tag handling depends on the promote type:

• Quality Checks — Tags from the source check are carried over to the destination check, plus any additional tags specified on the request.
• Computed Fields — Only the additional tags specified on the request are applied to the destination computed field. Source field tags are not carried over.
• Computed Tables / Computed Files — The new destination container receives the destination datastore's global tags (excluding any with type=external) plus any additional tags on the request. Source container tags are not carried over.

Tags applied via additional_tags never modify the source entities.

What if my additional_tags list references a tag that doesn't exist on the destination?

Unknown tag names are silently skipped — they are not auto-created. Only tags that already exist on the destination side are applied. If you need a new tag to land on promoted entities, create it on the destination first (via the Tags settings or API), then re-run the promotion.

If I manually edited a previously promoted check at the destination, will my edits be lost on the next re-promote?

Most rule definition fields are overwritten by the source on re-promote — rule properties, coverage, filter, and description are all replaced. Tags applied manually on the destination are preserved (any additional tags from the new promote are merged in). If you need a check to evolve independently from its source, treat it as a separate check rather than relying on re-promote, since the platform's intent is to keep the destination aligned with the source.

What is the Draft mode and when should I use it?

Draft mode is available only for quality check promotions. When enabled (default), promoted checks are created in Draft status at the destination. Draft checks do not run during scan operations until they are manually activated. Use Draft mode when promoting to production environments to allow a review step before checks go live.

What happens when I promote checks as Active?

When as_draft is set to false, the platform attempts to validate each new check against the destination container before activation. Validation runs in batches of 10. If validation rejects a check, the just-created destination row is deleted and the source check is recorded as failed in the operation results — no orphan check is left behind on the destination.

When the platform validates an active check at promote time, is it actually running the check against data?

No — active-check validation is schema and syntax only. The platform loads the destination container's structure with a zero-row read, parses the check against that schema, and verifies that referenced columns exist and the rule shape is valid. It does not execute the check on real rows. Data-quality evaluation happens later, during the next scan or check run. So a check that "promotes as Active" successfully is not the same as a check that "passes" — only that it is structurally compatible with the destination.

Why can't I promote a Discarded or Archived quality check?

The platform automatically excludes checks in Discarded or Archived status from promote operations, even when they are listed explicitly by ID. Only Active and Draft checks are eligible. To promote a previously archived check, restore it on the source container first and then re-run the promotion.

Can I promote a subset of checks or fields using tags?

Yes. All promote types (except computed files) support tag-based selection. You specify a list of tags, and only entities matching those tags are included in the promotion. Tag-based selection is mutually exclusive with specific ID selection — you must use one or the other.

Why don't computed files support tag-based selection?

Computed file promotion requires an explicit mapping step where each source computed file is associated with a specific file pattern on the destination datastore. This one-to-one mapping makes tag-based bulk selection impractical, so computed files only support individual selection.

Why did selecting one computed field also promote others?

When a computed field references other computed fields — either through explicit source_fields or through field references inside a custom expression — the platform expands the selection to include every transitive dependency. Promoting a single nested computed field can therefore pull in its parent computed fields automatically. The dependencies are processed parents-first so each field has its inputs in place when it is created.

What happens if my computed fields have a circular dependency?

The request is rejected up front with a 422 error listing the cycle members. Circular dependencies fail at validation, before the operation is enqueued — no work is done and no destination state is changed. Resolve the cycle on the source container, then retry the promotion.

What is the mapping step in computed file promotion?

The mapping step is unique to computed file promotion. Each source computed file must be associated with a profiled file pattern container on the destination DFS datastore. The platform offers an auto-match feature that uses fuzzy name matching to suggest mappings, with confidence scores displayed for each suggestion.

Why does the destination file pattern need to be profiled before I can promote computed files to it?

The promote operation needs the destination file pattern's schema to validate the computed file's transformation and to plan the post-promote profile. The platform discovers that schema by reading the profile of the destination file pattern. If the destination has never been profiled (was_profiled == false), the request is rejected up front with a 422 error and no work is enqueued.

To resolve this, open the destination DFS datastore, navigate to the file pattern container, and run a profile operation. Once it completes, re-run the promote.

How does the auto-match for computed files actually decide?

The platform runs a fuzzy name match between each source computed file and the available destination file patterns and shows a confidence percentage next to each suggestion (color-coded so high-confidence matches stand out). Auto-match never commits a mapping on its own — every row remains editable, and the Promote button stays disabled until every source file has an explicit destination assigned. Override any suggestion by picking a different destination from the dropdown.

Does promotion trigger any follow-up operations?

Yes, depending on the promote type:

• Quality Checks: No follow-up operation.
• Computed Fields: A slim profile runs on the destination container to generate metadata for the new computed fields.
• Computed Tables: A full profile runs on each created or updated computed table.
• Computed Files: A full profile runs on each created or updated computed file.

What happens if the post-promote profile fails?

For computed fields, the slim profile is invoked during each field's iteration. A failure marks that field as failed; if the underlying issue is consistent (e.g., the destination's partition column doesn't exist), every field will hit the same error and end up failed. For computed tables and computed files, a profile failure is reported in the operation results but the container definition is preserved.

What records does the slim profile read after a computed field is promoted?

The slim profile reads a small, bounded, partition-sequential sample from the destination — it is not a random shuffle and it skips AI-based constraint inference, correlation analysis, and high-cardinality histograms. The goal is to give each new computed field the minimal metadata it needs (type, basic stats) so it can be displayed and validated. If you need full statistics for the new fields, trigger a regular profile manually after promotion.

What if my source container's partition column doesn't exist (or has a different type) on the destination?

For computed tables and computed files, the follow-up profile first tries to load with the partition column. If loading fails because the column is missing or its type can't be coerced on the destination, the profile automatically retries without the partition filter and surfaces a message in the operation result so you know to reconfigure the partition column on the destination container. The promote itself does not fail in this case — only the partition optimization is dropped.

How are type mismatches handled when re-promoting computed fields onto a destination whose schema has drifted?

The post-promote profile re-applies each computed field's transformation against the destination's current schema. Rows that fail a safe cast become NULL rather than aborting the entire profile. If a type mismatch is fundamental (e.g., string column to a struct transformation that requires structured input), the profile reports the failed-cast count, the field is marked as failed for that operation, and the previously stored type metadata is left intact rather than silently overwritten.

Can I promote to a destination that already has entities from a different source?

Yes. The platform matches entities independently per source. Each promotion record is specific to a source-destination pair, so promoting from Source A and Source B to the same destination creates separate records and does not interfere with each other.

How do I know if a promotion succeeded?

Check the operation results from the Activity page or via the API (GET /api/operations/{id}). The status object shows counts for created, updated, skipped, and failed entities. The overall operation result is success if at least one entity was promoted successfully, or failure if all entities failed.

What happens if the worker is interrupted while a promotion is running?

The promote operation is resumable. If the background worker is interrupted and the operation is retried, the platform skips entities that have already been processed. Previous failed results for the same source-destination pair are replaced rather than duplicated, so a worker restart never produces partial duplicates or double-promotions.

Can I abort a running promote operation?

Yes. From the Activity page, you can abort a running promotion. The worker stops cleanly between entities — already-processed entities keep their result, and the operation is marked as aborted. Once aborted, expanding the row reveals a Resume button that re-enqueues the operation and skips entities already processed, so you can finish what was left without re-promoting the same entities. A Rerun button is also available if you prefer to start fresh and process every entity again. See View Promotion Results — After abort for the full set of follow-up actions.

What happens if I close the promote modal partway through configuring it?

Closing the modal discards your current selections. Reopening it starts you back at step 1 with empty fields — there is no auto-save or draft state. If you've configured a complex multi-tag or multi-destination selection, complete it in one session.

Is there a confirmation prompt before the promote starts?

No — the platform validates inputs inline and only enables the Promote button once required fields are set. Once you click Promote, the operation is enqueued immediately. If you want a review step before changes take effect, promote quality checks with Draft mode so that nothing runs at the destination until each check is manually activated.

How many entities can I include in a single promote operation?

There is no explicit user-facing cap, but the operation grows linearly with the number of selected entities — for active (non-draft) quality check promotions, each check is validated against the destination before activation, so very large operations take proportionally longer. For promotions involving thousands of entities, prefer breaking the work into smaller batches (e.g., by tag) so partial failures are easier to triage from the Activity page.

What permissions do I need to promote?

You need Editor team permission on both the source and the destination — the same gate applies to every promote type (Quality Checks, Computed Fields, Computed Tables, Computed Files). You also need at least the Member workspace role. See Permissions for the full breakdown.

Why does a user with Editor role on the source still get a permission error?

Promote is checked on both sides — source and destination. The user must have Editor team-permission on the source container or datastore and on the destination. If either side is missing, the API returns 403 Forbidden and the operation is not enqueued. See Permissions for the full breakdown.

Can I schedule promote operations?

Promote operations are triggered manually through the UI or API. They are not currently available as scheduled operations.

What happens if I rename a previously promoted source entity?

The platform tracks each promotion's source-to-destination link by entity ID, not by name. If you rename a previously promoted computed field, computed table, or computed file at the source and re-promote, the platform finds the previously linked destination from its promote result records and updates it — no duplicate is created. The destination's name is updated to match the new source name. Quality checks have no user-editable name, so this only applies to the computed asset types. See Entity Matching for the full lookup strategy.

Can I re-promote a computed table that was deleted at the destination?

Yes, if it was soft-deleted. For computed tables and computed files, the matching logic includes soft-deleted destinations — the platform reactivates the existing container (status returns to active) and updates its definition. For quality checks and computed fields, only live destination rows are considered; if the destination has been hard-deleted, a new entity is created on the next promotion.

The asymmetry is intentional: computed tables and files are datastore-level resources that often need to be revived in place (they back downstream consumers and metadata), while quality checks and computed fields are container-scoped artifacts that are routinely created and deleted during authoring — reactivating a deleted check or computed field would silently bring back something the author had explicitly retired. Promote result rows are kept for audit purposes, but if the previously linked destination is gone, the next promotion creates a new entity.

Can I promote computed tables to a DFS datastore or computed files to a JDBC datastore?

No. Computed tables can only be promoted to JDBC datastores, and computed files can only be promoted to DFS datastores. The destination type filter is enforced in both the UI and the API.

Can I promote computed joins?

No. Computed joins are not currently promotable. Unlike computed tables and computed files — which are tied to a single datastore — a computed join is inherently cross-datastore at creation time: it can reference containers from any source datastore and stores the result in the left datastore. Because joins already span multiple datastores by design, the platform does not provide a separate promote workflow for them. To reuse a join elsewhere, recreate it through the Add Computed Join flow on the target datastore.

Why aren't anomalies, tags, or other entities promotable?

Promote is scoped to definitional assets — the rules and transformations you author once and want to reuse across containers or datastores. Anomalies are observed outcomes of running checks (not definitions), and tags are metadata that gets carried over automatically with promoted entities rather than being promoted on their own. Today, only quality checks, computed fields, computed tables, and computed files are promotable.

Can I promote via the API?

Yes. All promote operations are available through the POST /api/operations/run endpoint. See the Promote API page for detailed request schemas, parameters, and examples.