Replication Keys for Mongo Integrations

Replication Keys are columns that Stitch uses to identify new and updated data for replication. As Stitch’s Mongo integration uses only Incremental Replication, when you set a Mongo collection to sync, you’ll also need to define a Replication Key.

Incorrectly setting a Replication Key can cause data discrepancies, latency, and high row counts. As Mongo Replication Keys have their own set of quirks, it’s important to understand how they work and what makes a good key.

Replication Keys vs. 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 phaseof 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 data warehouse. Primary Keys identify unique rows within a table and ensure that only the most recently updated version of that record appears in your data warehouse.

  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

Stitch uses a field you define - called a Replication Key - to identify new and updated data for replication. For Mongo connections, Stitch requires that the Replication Key field:

1. be indexed, AND
2. exist in the root of the document.

If you want to sync Mongo data and are going to add query parameters - which is what Incremental Replication does - undue stress could be put on your Mongo database. By indexing the fields you want to sync, that stress can be relieved.

Recommendations & Gotchas

While a field need only be indexed and exist in the root of the document to be a Mongo Replication Key, we have some recommendations (and things you should keep in mind) when selecting a field to be a Replication Key.

Replication Key Recommendations

1. Replication Key fields should contain only one data type. While Mongo allows you to have multiple data types in a single field, we strongly recommend keeping Replication Key fields to just one. This is because of the way Mongo compares and sorts data types and how this can impact replication.

2. Date and timestamp fields are great Replication Key candidates. We’re big fans of using updatedAt or modifiedAt. This is the best way to ensure that both new records and updates to existing records are captured.

   In some cases - for example, if a table is Append-Only - createdAt may also be suitable.

3. If date or timestamp fields can’t be used, Replication Keys should update incrementally. Fields with Integer and ObjectId data types can be used as Replication Keys if they update incrementally, which allows Stitch to identify a MAX value and detect new records for replication.

   This is suitable for Append-Only tables only, meaning that the table is only updated with new data. If existing records are ever modified, a field like updatedAt or modifiedAt should be used instead.

Replication Key Gotchas

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

1. Changing a collection’s Replication Key requires a full re-sync of the collection. To change the Replication Key for a Mongo collection, Stitch must perform a full re-sync of the collection.

2. Stitch will not capture hard deletes.

3. NULL is a defined BSON data type in Mongo. Unlike SQL, NULLs can actually compare to other data types and replicate without issue.

4. Mongo fields may contain more than one data type. These data types also have a hierarchy. Fields in Mongo (even _id) can contain more than one data type. In addition, Mongo “ranks” data types, meaning that some are considered greater than others. This can lead to problems detecting new data.

   While Stitch doesn’t require single data types for Replication Keys, we strongly recommend it. We’ve seen a lot of data discrepancies arise from this.

   Here’s an example that demonstrates why this could be a problem in Stitch:

   1. You sync a table, using a field called _id as the Replication Key. This field contains both ObjectId and String data types.
   2. A historical sync of the table completes.
   3. Because Mongo considers ObjectId data types to be greater than Strings, Stitch will record the MAX value as the last replicated record containing an ObjectId data type in the Replication Key field.
   4. New records are added to the table.
   5. During the next sync, Stitch uses the last recorded MAX value - in this case, an ObjectId - to identify new/updated data. Remember: only records with Replication Key values greater than or equal to this value will be selected for replication.
   6. Because ObjectIds > Strings, all records with Strings are considered to be less than the last recorded MAX value. This means Stitch won’t be able to detect these records and replicate them to your data warehouse.

   Because Stitch may be unable to correctly identify new and updated data due to how data types are sorted, it’s best to keep Replication Key fields to a single data type. See below in the Checking for Multiple Data Types section for guidance on verifying a field’s data types.

5. Some data types may not auto-increment. Before using the field, you should verify the field’s data type and that it auto-increments. Otherwise, Stitch may have issues detecting new data.

Checking for Multiple Data Types

To determine if a field has more than one data type and is thus suitable to be used as a Replication Key, we recommend running the following queries. We’re using Mongo version 3.0+, so keep in mind that these queries may be different for your version.

Run this query to count how many of a single data type there are in the table’s Replication Key field, replacing:

• nameOfCollection with the collection name,
• replicationKeyField with the field name, and
• knownDataTypeId with the Mongo BSON data type ID. You can find the data type IDs here in Mongo’s docs.

   db.nameOfCollection.count({replicationKeyField: {$type: knownDataTypeId}});

Next, run this query to get a count of all records in the table:

db.nameOfCollection.count();

Compare the results. If the counts are equal, then the Replication Key field contains only one data type.

Additionally, the following query will return the MAX value for the table’s Replication Key field. This can be helpful when comparing your source database to what’s in your data warehouse:

db.nameOfCollection.find().sort({replicationKeyField:-1}).limit(1);

Defining Replication Keys

After you set a collection to sync, you’ll be prompted to select a Replication Key.

After you select a field from the drop-down, click the Update Settings button.

Changing Existing Replication Keys

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

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

Resetting Replication Keys

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

Mongo Replication Keys can be reset at the integration level only.

To reset Replication Keys, do the following:

1. Click into the integration from the Stitch Dashboard page.

2. Click Settings.

3. Scroll down to the Reset Replication Keys section.
4. Click the Reset Keys button.
5. When prompted, click OK to confirm.
6. A Success! message will display at the top of the page.

At this point, a full re-sync of the integration will be queued. Note that 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.

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