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

# Replication modes

> Choose how Filament reads a resource and how the destination changes

Start with the change you need to observe, then choose how the destination
should represent it. Filament validates that combination before data moves.

## Choose a read mode

| Need | Read mode | What the next run reads |
| - | - | - |
| A fresh copy every time | `full` | Every selected row |
| New or changed rows identified by a cursor | `incremental` | Rows beyond durable cursor progress |
| Inserts, updates, and deletes from a database log | `cdc` | The ordered change stream from its durable position |

An incremental `users` route might use `updated_at` as its cursor. That is
lighter than rereading the table, but it cannot see a hard delete. Use CDC when
deletes or source transaction order must propagate.

A source connection is configured as either standard or CDC. Standard routes
choose full or incremental per resource. CDC applies to the whole route and
cannot be mixed with standard resources in the same run.

Read mode is separate from execution mode. A bounded run finishes after its
planned work; a continuous run keeps listening and commits progress repeatedly.
CDC support alone does not imply continuous support. See
[Streaming](/pages/guides/concepts/streaming) for the connector requirements
and recovery behavior of continuous runs.

## Choose destination behavior

* `append` keeps each emitted row version.
* `replace` produces a new snapshot of the resource.
* `upsert` keeps the current row for each primary key.
* `merge` applies ordered CDC inserts, updates, and deletes.

New pipelines default to upsert for full and incremental reads. Resources with
primary keys use upsert; resources without keys use append within the same route.
The sink must support append for those resources. Repeated keyless rows accumulate,
including when a full read runs again. Select replace when you need a fresh snapshot.
CDC routes default to append but may be configured to merge; their key requirements
are unchanged.

Common combinations look like this:

| Goal | Read | Write | Important consequence |
| - | - | - | - |
| Rebuild a reporting table | full | replace | Restarts from the beginning after failure |
| Periodically refresh current users | incremental | upsert | Cursor progress can support resume |
| Keep an immutable change history | CDC | append | Deletes remain events rather than removing rows |
| Maintain a current replica | CDC | merge | Ordered deletes remove destination rows |

## Reference: resolved modes

You can skip this section unless you use the API or build a connector.
Internally, each read/write pair becomes an ingestion type such as
`full_replace`, `incremental_upsert`, `cdc_append`, or `cdc_merge`. That plan
sets the sink mode, key requirement, and checkpoint timing. You usually need
the names only when using the API or building a connector.

Supported combinations are:

| Ingestion type | Primary key | Checkpoint timing |
| - | -: | - |
| `full_replace` | no | none |
| `full_append` | no | none |
| `full_upsert` | yes | after each written batch |
| `incremental_append` | no | after each written batch |
| `incremental_upsert` | yes | after each written batch |
| `cdc_append` | yes | after sink commit |
| `cdc_merge` | yes | after sink commit |

The engine checks the source policy, sink capabilities, primary keys, and cursor
configuration while resolving the plan. A connector advertising a mode does not
bypass those runtime contracts.

## How incremental upserts choose the latest row

For an incremental upsert, the cursor tells the source where the next read
begins. The sink also uses that field to decide which version of a row is newer.
If you do not choose a cursor, Filament can use the connector's recommendation.

Full upserts use insert order instead of a cursor. A checkpoint controls where
reading resumes; the version rule controls which row wins at the destination.

## Columns Filament adds

Filament reserves the `_filament_` prefix and adds the logical run ID and start
time to replicated rows. CDC also adds the operation, source position, and
sequence needed to interpret the change stream. These fields are nullable so an
existing destination can evolve without rewriting older rows. A source column
using a reserved name is rejected rather than overwritten.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.