# Promote FAQ

Source: https://userguide.qualytics.io/operations/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, and 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 none of the check's fields exist on the destination, the check is promoted as Draft with a warning when **Promote As Draft** is on (the default). With it off, that check fails and is not promoted.

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

With **Promote As Draft** on (the default), a check with none of its fields on the destination is promoted as **Draft** with a warning message indicating that no compatible fields were found. With it off, that check fails and is not promoted. 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](https://userguide.qualytics.io/operations/promote/deep-dive/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](https://userguide.qualytics.io/operations/promote/deep-dive/entity-matching/#phase-2-fallback-match) 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, so 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 one 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 a failed post-promotion profile, a source field that a parent computed field in the same promotion failed to create, or validation errors for active checks. Missing source fields and name collisions that are already visible when you click **Promote** do not produce a failed result: they reject the whole computed field request before the operation starts.

#### 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.** The destination check mirrors the source check's tags, plus the destination container's tags and any additional tags on the request (tags with `type=external` are excluded). The set is replaced on every promotion, so tags added by hand on the destination check, and additional tags from an earlier promotion, are removed unless they are on the source check or on the new request. External tags already on the destination check are kept.
- **Computed Fields.** The destination computed field mirrors the source computed field's tags, plus the destination container's inherited tags and any additional tags on the request (tags with `type=external` are excluded). The set is replaced on every promotion, so additional tags from an earlier promotion are dropped unless you specify them again.
- **Computed Tables and Computed Files.** The destination container mirrors the source container's tags, plus the destination datastore's global tags and any additional tags on the request (tags with `type=external` are excluded). The set is replaced on every promotion, so additional tags from an earlier promotion are dropped unless you specify them again.

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** and 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 are replaced too: the destination check ends up with the source check's tags, the destination container's tags, and the additional tags on the new promote, so tags applied manually on the destination are removed. 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, so 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". It only means the check 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, so 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, so 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 first, quick profile runs as part of the promotion. If it fails, that entity's promotion is undone: a new table or file is not created on the destination, and an existing one keeps its previous definition. Once that profile succeeds, the new definition is saved, so a failure in the full profile that may follow does not restore the previous definition. A failure in that first profile is reported in the Promote results. The full profile runs afterwards as a separate Profile operation, so check that Profile run for a later failure: the Promote results still show the entity as created or updated.

#### 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, and 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. Values are not converted to NULL when they cannot be cast: a single malformed value, such as `r2` in a string column that the transformation casts to a number, fails the profile. The field is then marked as failed for that operation, and its previous definition on the destination is left intact. To let malformed values become NULL instead, write the transformation with `try_cast`.

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

Yes, as long as the entity names differ. Each promotion record is specific to a source-destination pair, but a computed field, table, or file that was never promoted from a given source is matched on the destination by name. If Source A and Source B both promote a computed field with the same name, the second promote updates the field the first one created and replaces its definition, and each later promote from either source swaps it back. To keep them apart, give the entities distinct names before the first promotion. Once two sources share a destination entity, renaming one of them at the source does not separate them: the next promote follows the existing link and renames the shared destination entity instead.

#### 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 operation is marked as `aborted` right away and stops cleanly between entities: work already in progress finishes, no further entities are processed, and anything already processed keeps its result. Work in progress is usually one entity, or up to 10 quality checks being validated together when they are promoted as active. 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](https://userguide.qualytics.io/operations/promote/managing-promotions/view-promotion-results/#monitoring-in-progress-operations) 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, because 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.

#### Where do I end up after I submit a promotion?

On the operation's own page. The modal first confirms that the operation was triggered, and closing that confirmation takes you straight there, so you can watch the run without looking for it. This works the same way for all four promote types and from every entry point. The operation also stays available on the **Activity** page if you want to come back to it later.

#### Can I promote a single asset without going through the Settings menu?

Yes. Quality checks, computed fields, computed tables, and computed files each offer a **Promote** shortcut in the menu on their card or list item, and on their own detail page. The shortcut opens the same modal with that asset already selected, so you go directly to the destination step. See [Where You Can Start a Promote](https://userguide.qualytics.io/operations/promote/deep-dive/getting-started/#where-you-can-start-a-promote).

#### Why is Promote greyed out in the selection bar?

Because a single promotion handles one asset type at a time, and your current selection does not fit that. Hover the greyed-out action and it tells you why, for example "Only computed tables can be promoted" when the selection mixes container types, or "Checks from different tables can't be promoted together" when the selected checks come from more than one table. Narrow the selection to a single type (and, for checks, a single table) and the action becomes available. If **Promote** is missing from the bar altogether, either nothing you selected is promotable, or you do not have the **Editor** team permission.

#### 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 new checks do not run at the destination until each one is manually activated. A check that already exists on the destination is updated in place and keeps its status.

#### 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, and Computed Files). You also need at least the **Member** workspace role. See [Permissions](https://userguide.qualytics.io/operations/promote/deep-dive/permissions/) for the full breakdown.

#### Why does a user with the Editor team permission 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](https://userguide.qualytics.io/operations/promote/deep-dive/permissions/) for the full breakdown.

#### Can I schedule promote operations?

Promote operations are triggered manually through the UI or API. They are not 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, so 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](https://userguide.qualytics.io/operations/promote/deep-dive/entity-matching/) for the full lookup strategy.

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

Yes, but the promotion creates a new computed table instead of restoring the deleted one. Deleting a computed table or computed file removes it permanently, so the new container gets a new ID. The same applies to quality checks and computed fields: if the previously promoted destination was deleted, the next promotion creates a new entity.

Promote result rows are kept for audit purposes, but once the previously linked destination is gone, the next promotion falls back to name matching and creates a new entity if nothing matches.

#### 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](https://userguide.qualytics.io/operations/promote/api/) page for detailed request schemas, parameters, and examples.

**Still have questions?**
Contact the Qualytics support team at
[support@qualytics.ai](mailto:support@qualytics.ai).

*Last updated: October 19, 2026.*