> ## Documentation Index
> Fetch the complete documentation index at: https://artie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Backfills

> Artie runs CDC and backfills in parallel without data conflicts or database load. Database changes are enqueued in Kafka as the backfill is running and applied after backfill completes.

## How it works

This is how Artie handles <Tooltip tip="Backfills ensure that all your historical data is copied to your destination.">backfills</Tooltip> for each table:

<Steps>
  <Step title="Backfill">
    * Scans full table in batches, writes directly to destination
    * Can use read replica to minimize primary DB load
  </Step>

  <Step title="CDC">
    * Reads database logs immediately
    * Queues all changes (inserts, updates, deletes) in Kafka
  </Step>

  <Step title="Backfill completes">
    * Artie applies the queued CDC changes in order
  </Step>
</Steps>

## How to kick off a backfill

By default, when you onboard a new table, Artie will kick off a backfill to copy all the historical data to your destination.

This is how you trigger an adhoc backfill:

1. Click on any running pipeline and go to the pipeline overview page
2. Click on the <b>Backfill tables</b> button

<Accordion title="Walkthrough">
  <Frame>
    <img src="https://mintcdn.com/artie/FHAqwz-wbjTyUYk5/assets/backfills/adhoc_backfill.png?fit=max&auto=format&n=FHAqwz-wbjTyUYk5&q=85&s=20ba6239cc935b9cdd811517c58e4288" alt="Triggering an adhoc backfill" width="1732" height="943" data-path="assets/backfills/adhoc_backfill.png" />
  </Frame>
</Accordion>

Subsequently, <b>canceling a backfill</b> can be done from the Pipeline overview page.

## Destination table behavior

When triggering an ad-hoc backfill, you choose what happens to the destination table before the backfill begins:

<Card title="Do nothing" icon="minus">
  Artie upserts rows on top of the existing destination data. Use this when the table is already partially populated and you want to fill in missing or outdated rows without re-copying data that is already correct.
</Card>

<Card title="Truncate" icon="eraser">
  Removes all rows from the destination table before the backfill begins, while preserving the table schema, indexes, and grants. This is the simplest option for a clean, complete reload of your data.
</Card>

<Card title="Drop table" icon="trash">
  Drops and recreates the destination table from scratch, including its schema. Use this when the table structure has drifted significantly and you need a completely fresh start.

  <Warning>
    This will break any downstream objects that depend on this table, such as views and materialized views. If you only need to reload the data, use **Truncate** instead.
  </Warning>
</Card>

## Advanced settings

You can configure the additional backfill options from the advanced settings on the source tab in the pipeline editor.

<Frame>
  <img src="https://mintcdn.com/artie/FHAqwz-wbjTyUYk5/assets/backfills/advanced_settings.png?fit=max&auto=format&n=FHAqwz-wbjTyUYk5&q=85&s=df1860305a58473efee10373eb3ee7d7" alt="Backfill advanced settings" width="865" height="542" data-path="assets/backfills/advanced_settings.png" />
</Frame>

## How are backfills ordered?

In <Tooltip tip="FIFO (first-in, first-out)">FIFO order</Tooltip>, tables are backfilled in the order they were added, up to the concurrency limit.

## What happens to CDC changes during a backfill?

Our process continues to capture all changes to Kafka in the background. Once backfill completes:

1. We switch to CDC stream
2. We apply queued changes in order
3. The table transitions to fully streaming state

This guarantees consistency and prevents stale data overwrites.
