> This page location: /docs.md > /docs/development.md > /docs/atlas/data-federation.md > /docs/atlas/data-federation/tutorial/getting-started.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Deploy a Federated Database Instance

*Estimated completion time: 15 minutes*

This part of the tutorial guides you through deploying a federated database instance using the following quickstart wizards in the Atlas UI:

- The [Feed Downstream Systems](https://www.mongodb.com/docs/atlas/data-federation/tutorial/deploy.md#std-label-feed-downstream-systems) wizard helps you set up a federated database instance that exports data from your Atlas cluster, transforms the data into [Parquet](https://parquet.apache.org/docs/), [CSV](https://www.mongodb.com/docs/atlas/data-federation/supported-unsupported/data-formats/csv-tsv-data-files.md#std-label-adf-csv-tsv-data), BSON (Binary Javascript Object Notation), or [MongoDB Extended JSON](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#std-label-mongodb-extended-json-v2), and copies the data to your AWS (Amazon Web Services) S3 (Simple Storage Service) buckets at specified intervals using [Atlas Triggers.](https://www.mongodb.com/docs/atlas/atlas-ui/triggers.md#std-label-atlas-triggers)

- The [Explore with Sample Data](https://www.mongodb.com/docs/atlas/data-federation/tutorial/deploy.md#std-label-explore-sample-data) wizard helps you set up a federated database instance loaded with sample data to demonstrate  how to connect to the federated database instance and run queries.

- The [Query Data Across Clusters](https://www.mongodb.com/docs/atlas/data-federation/tutorial/deploy.md#std-label-query-across-clusters) wizard helps you set up a federated database instance that accesses data from multiple Atlas clusters so you can run federated queries across collections from all of them.

To learn more about the storage configuration options, see [Configure Data Stores for a Federated Database Instance.](https://www.mongodb.com/docs/atlas/data-federation/config/config-data-stores.md#std-label-config-adf)

## Required Access

To deploy a federated database instance, you must have [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) access to the project.

**Important:**

Users with [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) access must add themselves as a `Project Owner` to the project before deploying their federated database instance.

## Prerequisites

To complete this part of the tutorial, make sure you meet the following prerequisites:

- Create a [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) account, if you don't have one already.

- For the Feed Downstream Systems wizard, you need:

  - The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html), [configured to access your AWS account](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html#cli-quick-configuration). Alternatively, you must have access to the AWS (Amazon Web Services) Management Console with permission to create [IAM roles.](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html)

  - An S3 (Simple Storage Service) bucket to store extracted data.

  - At least one Atlas cluster with a database.

- For the Query Data Across Clusters wizard, you need:

  - At least one Atlas cluster deployed in the same project you'll use for your federated database instance.

  - At least one database collection. You can [load sample data](https://www.mongodb.com/docs/atlas/import/load-sample-data.md#std-label-sample-data) if you don't have collections already.

## Use the Feed Downstream Systems Wizard

The Feed Downstream Systems wizard helps you set up a federated database instance that writes data from your Atlas cluster to your AWS (Amazon Web Services) S3 (Simple Storage Service) bucket continuously on a schedule.

1. Log in to MongoDB Atlas.

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

3. Create a federated database instance.

   Click the Create New Federated Database dropdown.

   Select Feed Downstream Systems.

4. Click Get Started.

5. 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.

6. Specify your data sources.

   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.

   Click Continue.

7. Select an AWS (Amazon Web Services) IAM role for Atlas.

   You can select an existing AWS (Amazon Web Services) 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 (Amazon Web Services) S3 (Simple Storage Service) 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:

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

   Use the AWS (Amazon Web Services) ARN (Amazon Resource Name) and unique External ID in the Role Authorization section to add Atlas to the trust relationships of an existing or new AWS (Amazon Web Services) IAM role.

   In the Atlas UI, click one of the following:

   - The Create new AWS IAM role shows how to use the ARN (Amazon Resource Name) and the unique External ID to add Atlas to the trust relationships of a new AWS (Amazon Web Services) IAM (Identity and Access Management) role. Follow the steps in the Atlas UI for creating a new role. To learn more, see [Create New Role with the AWS CLI.](https://www.mongodb.com/docs/atlas/security/set-up-unified-aws-access/#procedure)

     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](https://www.mongodb.com/docs/atlas/security/set-up-unified-aws-access/) a new role, then start the procedure for [deploying a federated database instance](https://www.mongodb.com/docs/atlas/data-federation/tutorial/deploy.md#std-label-gst-deploy-adf) again when you have the AWS (Amazon Web Services) IAM role ARN (Amazon Resource Name).

     - 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 (Amazon Resource Name) and the unique External ID to add Atlas to the trust relationships of an existing AWS (Amazon Web Services) IAM (Identity and Access Management) 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](https://www.mongodb.com/docs/atlas/security/set-up-unified-aws-access/#procedure) .

   **Important:**

   If you modify your custom AWS (Amazon Web Services) role ARN (Amazon Resource Name) in the future, ensure that the access policy of the role includes the appropriate access to the S3 (Simple Storage Service) resources for the federated database instance.

   To learn more, see [Set Up Unified AWS Access](https://www.mongodb.com/docs/atlas/security/set-up-unified-aws-access/) and [Create a Cloud Provider Access Role.](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#operation/createCloudProviderAccessRole)

   Click Validate AWS IAM role.

8. Assign an access policy to your AWS (Amazon Web Services) IAM role.

   Enter the name of your S3 (Simple Storage Service) bucket.

   Follow the steps in the Atlas UI to assign an access policy to your AWS (Amazon Web Services) IAM role.

   Click Validate AWS S3 bucket access.

   Click Continue.

9. Schedule your data extractions.

   Schedule a [trigger](https://www.mongodb.com/docs/atlas/atlas-ui/triggers/scheduled-triggers.md#std-label-atlas-scheduled-trigger) to continuously copy data from your Atlas cluster into your S3 (Simple Storage Service) bucket using [$out](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out/#-out--aggregation-) in the Schedule Queries section.

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

   *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.

   *Optional*. Choose the format you want for your data when Atlas Data Federation writes it to your S3 (Simple Storage Service) bucket. Atlas Data Federation supports [Parquet](https://parquet.apache.org/docs/), [CSV](https://www.mongodb.com/docs/atlas/data-federation/supported-unsupported/data-formats/csv-tsv-data-files.md#std-label-adf-csv-tsv-data) , BSON (Binary Javascript Object Notation) , and [MongoDB Extended JSON.](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json/)

   Specify the Max File Size to limit how large each file that Atlas Data Federation writes to your S3 (Simple Storage Service) 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 (Simple Storage Service) bucket in 10 files, each 100 MBs.

   Enter the [AWS prefix](http://docs.aws.amazon.comAmazonS3/latest/userguide/using-prefixes.html) for your destination S3 (Simple Storage Service) bucket.

   Enter the name of the [indexed](https://www.mongodb.com/docs/manual/indexes/) 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](https://www.mongodb.com/docs/manual/indexes/) field that stores a timestamp as its value.

   Click Continue.

10. Click Create.

## Use the Explore with Sample Data Wizard

The Explore with Sample Data wizard helps you set up a federated database instance loaded with sample data.

1. Log in to MongoDB Atlas.

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

3. Create a federated database instance.

   Click the Create New Federated Database dropdown.

   Select Explore with Sample Data.

4. Click Get Started.

5. Click Create.

This federated database instance includes the following sample datasets that you can use to practice [running queries:](https://www.mongodb.com/docs/atlas/data-federation/tutorial/run-queries-sample-data.md#std-label-gst-run-queries)

- `/airbnb/listingsAndReviews/{bedrooms int}/{review_scores.review_scores_rating int}/`

  This path references the `airbnb` dataset, which contains the vacation home listing details and customer reviews. To learn more about this dataset, see [Sample AirBnB Listings Dataset.](https://www.mongodb.com/docs/atlas/sample-data/sample-airbnb/)

  For this path, the federated database instance uses partitions optimized for queries on the `bedrooms` field and `review_scores.review_score_ratings` fields.

- `/analytics/accounts/{limit int}/`

  This path references the `analytics` dataset, which contains data for a typical financial services application. To learn more about this dataset, see [Sample Analytics Dataset.](https://www.mongodb.com/docs/atlas/sample-data/sample-analytics/#sample_analytics.accounts)

  For this path, the federated database instance uses partitions optimized for queries on the `limit` field.

- `/analytics/customers/{birthdate isodate}/`

  This data references the `analytics` dataset, which contains collections for a typical financial services application. To learn more about this dataset, see [Sample Analytics Dataset.](https://www.mongodb.com/docs/atlas/sample-data/sample-analytics/#sample_analytics.customers)

  For this path, the federated database instance uses partitions optimized for queries on the `birthdate` field.

- `/analytics/transactions/{account_id int}/`

  This path references the `analytics` dataset, which contains data for a typical finanacial services application. To learn more about this dataset, see [Sample Analytics Dataset.](https://www.mongodb.com/docs/atlas/sample-data/sample-analytics/#sample_analytics.transactions)

  For this path, the federated database instance uses partitions optimized for queries on the `account_id` field.

- `/mflix/movies/{type string}/{year int}/`

  This path references the `mflix` dataset, which contains data on movies and movie theaters. To learn more about this dataset, see [Sample Mflix Dataset.](https://www.mongodb.com/docs/atlas/sample-data/sample-mflix/#sample_mflix.movies)

  For this path, the federated database instance uses partitions optimized for queries on the `type` and `year` fields.

- `/mflix/sessions.json`

  This path references the `mflix` dataset, which contains data on movies and movie theaters. To learn more about this dataset, see [Sample Mflix Dataset.](https://www.mongodb.com/docs/atlas/sample-data/sample-mflix/#sample_mflix.sessions)

  This path does not contain any partition attributes and so, for queries against data in the collection, Data Federation searches all the files in the collection.

- `/mflix/theaters/{theaterId string}/{location.address.zipcode string}/`

  This path references the `mflix` dataset, which contains data on movies and movie theaters. To learn more about this dataset, see [Sample Mflix Dataset.](https://www.mongodb.com/docs/atlas/sample-data/sample-mflix/#sample_mflix.theaters)

  For this path, the federated database instance uses partitions optimized for queries on the `theaterId` and `location.address.zipcode` fields.

- `/mflix/users.json`

  This path references the `mflix` collection, which contains data on movies and movie theaters. To learn more about this dataset, see [Sample Mflix Dataset.](https://www.mongodb.com/docs/atlas/sample-data/sample-mflix/#sample_mflix.users)

  This path does not contain any partition attributes and so, for queries against data in the collection, the federated database instance searches all the files in the collection.

- `/nyc-yellow-cab-trips/{trip_start_isodate isodate}/{passenger_count int}/{fare_type string}/`

  This path references the `nyc-yellow-cab-trips` dataset, which contains data on the trips, including trip date, fare, and number of passengers.

  For this path, the federated database instance uses partitions optimized for queries on the `trip_start_isodate`, `passenger_count`, and `fare_type` fields.

## Use the Query Data Across Clusters Wizard

The Query Data Across Clusters wizard helps you set up a federated database instance that accesses data from multiple Atlas clusters.

1. Log in to MongoDB Atlas.

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

3. Create a federated database instance.

   Click the Create New Federated Database dropdown.

   Select Query Data Across Clusters.

4. Click Get Started.

5. 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.

6. Specify the Atlas clusters to use as data sources.

   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.

   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.

   *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](https://www.mongodb.com/docs/manual/reference/glossary/#term-primary); `primaryPreferred` - to route all read requests the replica set [primary](https://www.mongodb.com/docs/manual/reference/glossary/#term-primary) and to [secondary](https://www.mongodb.com/docs/manual/reference/glossary/#term-secondary) members only if `primary` is unavailable; `secondary` - to route all read requests to the [secondary](https://www.mongodb.com/docs/manual/reference/glossary/#term-secondary) members of the replica set; `secondaryPreferred` - to route all read requests to the [secondary](https://www.mongodb.com/docs/manual/reference/glossary/#term-secondary) members of the replica set and the [primary](https://www.mongodb.com/docs/manual/reference/glossary/#term-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](https://www.mongodb.com/docs/manual/reference/glossary/#term-primary) or [secondary](https://www.mongodb.com/docs/manual/reference/glossary/#term-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.](https://www.mongodb.com/docs/manual/core/read-preference/#read-preference-modes) IMPORTANT: Data Federation and Primary Node Impact When Data Federation queries are configured with a read preference that targets secondary nodes, they are not expected to generate load on the primary of the backing Atlas cluster. Queries initiated on a secondary maintain cursor affinity to that node for their lifetime. In some logs, `getMore` operations may appear with a read preference of `primaryPreferred`. This is expected behavior and does not indicate that the cursor has switched to the primary. The `primaryPreferred` mode is valid on both primary and secondary nodes and allows drivers to handle rare role changes (such as a secondary becoming primary) without reissuing the query. Cursor execution continues on the original node unless that node itself changes role. Data Federation isolates its workloads from the primary without requiring any additional configuration. Using the `primaryPreferred` mode ensures compatibility with both primary and secondary nodes, allowing drivers to handle rare role changes—such as a secondary becoming primary—without reissuing the query. Cursor execution continues on the original node unless that node itself changes role. |
   | 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.](https://www.mongodb.com/docs/manual/core/read-preference-tags/) |
   | Maxstaleness Seconds | Specifies the maximum replication lag, or "staleness", for reads from secondaries. To learn more, see [Read Preference maxStalenessSeconds.](https://www.mongodb.com/docs/manual/core/read-preference-staleness/) |

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

   Once you're done adding clusters, click Continue.

7. Click Create.

## Next Steps

Now that your federated database instance is deployed, proceed to [Configure Connection for Your Federated Database Instance.](https://www.mongodb.com/docs/atlas/data-federation/tutorial/configure-connection.md#std-label-config-connection)
