Already have an account? Sign in

Replication Keys for Database Integrations

Replication Keys are columns that Stitch uses to identify new and updated data for replication. When you set a table to useIncremental Replication, you’ll also need to define a Replication Key for that table.

As improperly setting Replication Keys can cause data discrepancies, latency, and high row counts, it’s important to understand how they work, what makes a good key, and the gotchas associated with them.

Replication Keys and Primary Keys

When it comes to replicating your data, there are a lot of ‘keys’ involved. It can be difficult to keep them all straight, but aside from Replication Keys, there’s one more you should keep in mind: Primary Keys.

In Stitch, Replication Keys and Primary Keys serve two different purposes:

• Replication Keys are used during the Extraction phase of the replication process - or when Stitch is querying your data source - to identify new and updated data for replication.

  In the Stitch app, Replication Keys have a next to the column name.

• Primary Keys are used during the last step of the replication process, which is when Stitch loads replicated data into your destination. Primary Keys identify unique rows within a table and ensure that only the most recently updated version of that record appears in your destination.

  In the Stitch app, Primary Keys have a next to the column name.

While a column can sometimes be used as both a Replication Key and a Primary Key, these are not necessarily always the same column.

Replication Key requirements

To useKey-based Incremental Replication, a table must contain one of the following column types to be used as the Replication Key:

When Stitch replicates your data, it will store the last recorded maximum value in the Replication Key column and compare it against the data source -not what’s in your destination - to identify new/updated data.

Any row with a Replication Key value greater than or equal to the stored value is where Stitch will begin the next replication job.

Recommendations and gotchas

While a column only need be aninteger,datetime, ortimestamp to be a Replication Key, we have some recommendations (and things you should keep in mind) when selecting a column to be a Replication Key.

Replication Key recommendations

• For tables where existing records are updated: We’re big fans of usingupdated_at ormodified_at columns as Replication Keys. This is the best way to ensure that both new records and updates to existing records are captured.

• ForAppend-Only tables: We recommend using a unique, auto-incrementing integer as the Replication Key for these types of tables. However, acreated_at date ortimestamp column may also be suitable.

Replication Key gotchas

Before selecting a Replication Key for a table, there are a few things you should keep in mind:

• Rows withNULL values in the Replication Key column will only be replicated during the first extraction of an integration. This means subsequent extractions will not capture rows where the Replication Key isNULL. Stitch uses the Replication Key column to detect new and updated data - without it, data can’t be correctly detected and replicated.

  If the Replication Key field is entirelyNULL, the entire source table will be extracted during each job until a non-NULL value is received and stored as a bookmark.

• Auto-incrementing integers are only suitable Replication Keys for Append-Only tables. If you want to use an auto-incrementing integer column as the Replication Key for your table, ensure that the table is Append-Only.

  If an auto-incrementing integer is used and existing records are updated, Stitch won’t detect the new data if the values in the Replication Key column don’t also change. This can lead to data discrepancies.

• Replication Keys for MongoDB work a little differently than they do for other integrations. Check out theSelecting MongoDB Replication Keys guide for more info.
• Stitch will not capture hard deletes in tables that use Key-based Incremental Replication.

Data discrepancies and row count impact

Replication Keys are one of the single most important aspects of data replication. Because they’re so important, we felt these two points merited their own section:

• Incorrectly selecting a Replication Key can cause data discrepancies. For example: you set the Replication Key for an Append-Only table to anid column, which is an auto-incrementing integer. Existing rows in this table are updated, but theid column never changes after the record is created. Stitch will not detect the updated values because theid column hasn’t changed.

• Incorrectly selecting a Replication Key can impact your row count. For example: you set the Replication Key column for a table to aBIGINT column that’s used in a boolean fashion, meaning it contains 0s and 1s. Every time the values in this column change, the row will be re-replicated to your data warehouse and count against your monthly limit.

  If you encounter a data discrepancy, we recommend you start by verifying that the Replication Method and Key for the table are properly set. For further assistance, check out theData Discrepancy Troubleshooting Guide.

Defining Replication Keys

After you set a table to replicate and selectKey-based Incremental Replication as the Replication Method, you’ll need to select a column to be used as the Replication Key for the table.

After you select a column from the drop-down, click theUpdate Settings button.

Changing existing Replication Keys

Changing an existing Replication Key for a table is simple - just open up the Table Settings page for the table and select the new Replication Key column from the drop-down menu.

Note: When you change a table’s Replication Key, Stitch will queue a full re-replication of the table’s data. We do this to ensure that there aren’t any gaps because of the Replication Key switch.

Resetting Replication Keys

Replication Keys can be reset for database and (most) SaaS integrations.

There may be times when you need to fully replicate a table (or tables) that usually update incrementally. If, for example, you add a new column and want to backfill data for already-replicated rows, forcing a full re-replication of the table will populate the column for existing rows and replicate new records. You can do this by resetting Replication Keys.

Resetting database integration Replication Keys

Replication Keys in database integrations can be reset at theintegration or thetable level.

• At theintegration level, the reset will clear the replication key value for ALL tables AND queue a full re-replicationfor all tables in the integration.
• At thetable level, the reset will clear the replication key value AND queue a full re-replicationfor that table only.

To reset Replication Keys, do the following:

1. Click into the integration from the Stitch Dashboard page.
2. Next:
   • To reset the entire integration: Click theSettings link andskip to step 3.
   • To reset a table: Locate the table you want and click into it. Click theTable Settings link, located near the top right corner, andproceed to step 3.
3. Scroll down to theReset Replication Keys section.
4. Click theReset Keys button.
5. When prompted, clickOK to confirm.
6. ASuccess! message will display at the top of the page.

At this point, a full re-replication of the integration or table will be queued.Note: If there is a large volume of data to be replicated, it may take some time before you see the changes in your data warehouse.

Resetting SaaS integration Replication Keys

Resetting the Replication Keys for a SaaS integration is done by changing theHistorical Sync date in the Integration Settings page. When this date is changed, all saved values will be overwritten AND a full re-replication of the integration will be queued.

Note: This feature may not be available for some integrations. Because this approach uses date-based replication, some integrations may be incompatible. For example: Pardot doesn’t support date-based replication, meaning this feature will not be available for Pardot connections.

Changing the Historical Sync date has its own set of considerations and gotchas. Please refer to theSyncing Historical SaaS Data guide for more info.

Did this article help? If you have questions or feedback, feel free tosubmit a pull request with your suggestions,open an issue on GitHub, orreach out to us.