Deploy a Federated Database Instance

Log in to MongoDB Atlas.

Select the Data Federation option on the left-hand navigation.

Create a federated database instance.

1. Click the Create New Federated Database dropdown.

2. Select Feed Downstream Systems.

Click Get Started.

Type a name for your federated database instance in the Federated Database Instance Name field and click Continue.

Defaults to FederatedDatabaseInstance[n]. Once your federated database instance is created, you can't change its name.

Specify your data sources.

1. Select an Atlas cluster to use as a data source from the dropdown. By default, Atlas Data Federation adds all collections in this cluster. To use a subset of the data, click Specific Collections, expand the databases, and then select the collections that you want to add to your federated database instance.

   Tip

   To filter the databases and collections, enter text into the Specific Collections field. The dialog box displays only databases and collections with names that match your search criteria.

2. Click Continue.

Select an AWS IAM role for Atlas.

You can select an existing AWS IAM role that Atlas is authorized for from the role selection dropdown list or choose Authorize an AWS IAM Role to authorize a new role.

If you selected an existing role that Atlas is authorized for, proceed to the next step to list your AWS S3 buckets.

If you are authorizing Atlas for an existing role or are creating a new role, complete the following steps before proceeding to the next step:

1. From the dropdown, select Authorize an AWS IAM Role to authorize a new role or select an existing role.

2. Use the AWS ARN and unique External ID in the Role Authorization section to add Atlas to the trust relationships of an existing or new AWS IAM role.

   In the Atlas UI, click one of the following:

   • The Create new AWS IAM role shows how to use the ARN and the unique External ID to add Atlas to the trust relationships of a new AWS IAM role. Follow the steps in the Atlas UI for creating a new role. To learn more, see Create New Role with the AWS CLI.

     When authorizing a new role, if you quit the workflow:

     • Before validating the role, Atlas will not create the federated database instance. You can go to the Atlas Integrations page to authorize a new role, then start the procedure for deploying a federated database instance again when you have the AWS IAM role ARN.

     • After validating the role, Atlas will not create the federated database instance. However, the role is available in the role selection dropdown and can be used to create a federated database instance. You do not need to authorize the role again.

   • The Use existing AWS IAM role shows how to use the ARN and the unique External ID to add Atlas to the trust relationships of an existing AWS IAM role. Follow the steps in the Atlas UI for adding Atlas to the trust relationship to an existing role. To learn more, see Add Trust Relationships to an Existing Role .

   Important

   If you modify your custom AWS role ARN in the future, ensure that the access policy of the role includes the appropriate access to the S3 resources for the federated database instance.

   To learn more, see Set Up Unified AWS Access and Create a Cloud Provider Access Role.

3. Click Validate AWS IAM role.

Assign an access policy to your AWS IAM role.

1. Enter the name of your S3 bucket.

2. Follow the steps in the Atlas UI to assign an access policy to your AWS IAM role.

3. Click Validate AWS S3 bucket access.

4. Click Continue.

Schedule your data extractions.

Schedule a trigger to continuously copy data from your Atlas cluster into your S3 bucket using $out in the Schedule Queries section.

1. Specify how often you want to extract data from your Atlas cluster using the Repeat Once By dropdowns.

2. Optional. Specify whether Atlas Data Federation must re-run the same query if it missed it for any reason. By default, this is disabled to allow Atlas Data Federation to re-run missed queries. Alternatively, to skip missed queries and not catch up, toggle on Skip Catch Up Events.

3. Optional. Choose the format you want for your data when Atlas Data Federation writes it to your S3 bucket. Atlas Data Federation supports Parquet, CSV , BSON , and MongoDB Extended JSON.

4. Specify the Max File Size to limit how large each file that Atlas Data Federation writes to your S3 bucket can be. For example, if you set Max File Size to 100 MB and a query returns 1 GB of data, Atlas Data Federation writes the query to your S3 bucket in 10 files, each 100 MBs.

5. Enter the AWS prefix for your destination S3 bucket.

6. Enter the name of the indexed date field in Date Field and specify the format of its value using the dropdown. Every collection that you want to copy downstream must have an indexed field that stores a timestamp as its value.

7. Click Continue.

Click Create.

Log in to MongoDB Atlas.

Select the Data Federation option on the left-hand navigation.

Create a federated database instance.

1. Click the Create New Federated Database dropdown.

2. Select Explore with Sample Data.

Click Get Started.

Click Create.

Log in to MongoDB Atlas.

Select the Data Federation option on the left-hand navigation.

Create a federated database instance.

1. Click the Create New Federated Database dropdown.

2. Select Query Data Across Clusters.

Click Get Started.

Type a name for your federated database instance in the Federated Database Instance Name field and click Continue.

Defaults to FederatedDatabaseInstance[n]. Once your federated database instance is created, you can't change its name.

Specify the Atlas clusters to use as data sources.

1. Select an Atlas cluster to use as a data source from the dropdown. Atlas only displays clusters in your current Atlas project in this dropdown.

2. Expand the databases and select the collections that you want to add to your federated database instance.

   Tip

   To filter the databases and collections, enter text into the Specific collections field. The dialog box displays only databases and collections with names that match your search criteria.

3. Optional. Expand the Cluster Read Preference settings to configure the following fields.

   Field Name	Description
   Read Preference Mode	Specifies the replica set member to which you want to route the read requests. You can choose one of the following from the dropdown: primary - to route all read requests to the replica set primary primaryPreferred - to route all read requests the replica set primary and to secondary members only if primary is unavailable secondary - to route all read requests to the secondary members of the replica set secondaryPreferred - to route all read requests to the secondary members of the replica set and the primary on sharded clusters only if secondary members are unavailable nearest - to route all read requests to random eligible replica set member, irrespective of whether that member is a primary or secondary If you add an Atlas cluster as a store, the default value is secondary. If you don't set anything in your federated database instance storage configuration, the default value is nearest. To learn more, see Read preference mode.
   TagSets	Specifies the list of tags or tag specification documents that contain name and value pairs for the replica set member to which you want to route read requests. To learn more, see Read Preference Tag Sets.
   Maxstaleness Seconds	Specifies the maximum replication lag, or "staleness", for reads from secondaries. To learn more, see Read Preference maxStalenessSeconds.

4. Click Add Atlas cluster and collection and repeat these steps for all the Atlas clusters that you want to use as data sources.

5. Once you're done adding clusters, click Continue.

Click Create.