Changesets: Safe Drafts for Your Data

A changeset is an isolated copy of your workspace where you can make changes freely—without touching your live data. Think of it like a draft mode for your entire catalog. You can edit, create, and delete records, preview the result, and only push the changes live once you are satisfied.

Why Changesets Exist

The most important use case is working with AI. When you ask the AI to rewrite descriptions, translate fields, or run a mass update across thousands of products, the result can sometimes surprise you. Changesets give you a safety net:

• The AI writes its results into a changeset, not directly into your live data.
• You can review every change before deciding what to do with it.
• If you don’t like the results, you simply reject the changeset—nothing in your real data is ever touched.
• If you do like them, you apply the changeset and the changes become permanent.

This applies equally to any bulk or automated operation—mass updates, background jobs, API integrations, or your own experiments.

How Changesets Work

Changesets work like branches in Git. When you switch to a changeset and modify a record, the original record is left untouched and a modified copy is stored in the changeset. While you are working inside the changeset, you see the data exactly as if all your edits were already saved—filters, sorting, aggregations, and list views all reflect your changes. But the live data is unchanged until you explicitly apply the changeset.

Key characteristics:

• Everything works inside a changeset. Filtering, sorting, aggregations, editing, and list views all behave exactly as they do in the main data.
• Modified records are highlighted. Any record that was changed in the current changeset shows a small yellow dot so you can spot it at a glance.
• Deleted records disappear from lists while inside the changeset (as expected), but they are still visible in the changeset detail.
• Storage is efficient. Only modified records are duplicated. The additional storage consumed by a changeset is usually very small.

Creating a Changeset

1. Click the **Main Data (Live)** button in the top toolbar (or the name of the currently active changeset).
2. Select **Changesets (Safe Testing)** from the dropdown.
3. Click the **Add changeset** button.
4. Enter a **Name** that describes the purpose (e.g., "AI-translated descriptions – March").
5. Click **Save**.
6. Select your new changeset from the list to switch into it.

[badge:Changeset active|warning] Once you switch to a changeset, all edits you make go into that changeset only. Live data is unaffected.

Working Inside a Changeset

Once you are inside a changeset, the system behaves exactly as normal. You can:

• Browse, filter, and sort records.
• Open and edit individual records.
• Create new records or delete existing ones.
• Run AI edits and mass updates—they will write their results into the changeset.

Viewing Only Modified Records

When you want to focus on what has changed:

1. Open any entity list (e.g., Products).
2. Use the **"Show modified only"** filter to narrow the list to records that were changed in the current changeset.
3. Each modified record is marked with a small **yellow dot** next to its row.

Inspecting a Changeset

The changeset detail page gives you a full overview of everything that was changed.

1. Open the **Changesets** list.
2. Click on the changeset you want to inspect.

On the detail page you will see:

• Per-entity summary – for each entity type (e.g., Products, Categories) the number of created, updated, and deleted records is shown.
• Drill into an entity – clicking the entity name navigates you directly to that entity list filtered to show only the modified records in this changeset.

Keeping Your Changeset Up to Date

While you are working on a changeset, other users may update the live data. You can pull those changes into your changeset at any time.

1. Open the changeset detail page.
2. Click **Sync from main data**.
3. The system merges the latest live changes into your changeset and flags any **collisions** (the same field was changed in both places).
4. Use the built-in **merge tool** to resolve collisions—you choose which version to keep for each conflicting field.
5. After resolving all conflicts, click **Save** to finalize the merge.

**Tip:** The merge tool tries to preserve all changes automatically. You only need to manually resolve the cases where the same field was edited in both the live data and the changeset.

Applying or Rejecting a Changeset

When you are done reviewing, you have two options:

Apply (make changes live)

1. Open the changeset detail page.
2. Click **Apply**.
3. The system merges the changeset into the live data. If any new collisions have appeared since your last sync, the merge tool is shown again so you can resolve them.
4. After all conflicts are resolved, the changes are written to the live catalog and the changeset is marked as applied.

Reject (discard all changes)

1. Open the changeset detail page.
2. Click **Reject**.
3. Confirm the action. All changes stored in the changeset are permanently discarded. Live data is left exactly as it was.

**Warning:** Rejecting a changeset is irreversible. All edits stored in the changeset will be lost.

Choosing a Target Changeset During Edits

Whenever you trigger an AI edit or a mass update, you can choose which changeset the results should be written to—even if you are not currently inside that changeset.

1. Open the **AI Edit** or **Mass Update** dialog.
2. In the **Save to** dropdown, select the target changeset (or "Main Data" to apply directly).
3. Complete the operation as normal.

This lets you run multiple experiments in parallel, each in its own named changeset.

Using Changesets in the API and Background Jobs

Changesets are a first-class concept throughout the system. Any API call or background job can target a specific changeset by including the changeset identifier in the request. This means automated workflows—imports, scheduled jobs, integrations—can all write safely into a changeset for human review before going live.

How Many Changesets Can I Have?

You can have as many changesets as you need, for as long as you need them. The system is designed to handle up to around 100 active changesets comfortably. Give each one a meaningful name so your team knows what it contains.

Quick Reference