Path parameters

• groupId string Required

  Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

  NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

  Minimum length is 24, maximum length is 24. Format should match the following pattern: ^([a-f0-9]{24})$.

• tenantName string Required

  Human-readable label that identifies the federated database instance to update.

Query parameters

• envelope boolean

  Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

  Default value is false.

• pretty boolean

  Flag that indicates whether the response body should be in the prettyprint format.

  Default value is false.

• skipRoleValidation boolean Required

  Flag that indicates whether this request should check if the requesting IAM role can read from the S3 bucket. AWS checks if the role can list the objects in the bucket before writing to it. Some IAM roles only need write permissions. This flag allows you to skip that check.

Responses

• 200 application/vnd.atlas.2023-01-01+json

  OK

  Hide response attributes Show response attributes object

  • cloudProviderConfig object

    Cloud provider where this Federated Database Instance is hosted.

    Hide cloudProviderConfig attributes Show cloudProviderConfig attributes object

    • aws object

      Configuration for running Data Federation in AWS.

      Hide aws attributes Show aws attributes object

      • externalId string

        Unique identifier associated with the Identity and Access Management (IAM) role that the data lake assumes when accessing the data stores.

      • iamAssumedRoleARN string

        Amazon Resource Name (ARN) of the Identity and Access Management (IAM) role that the data lake assumes when accessing data stores.

        Minimum length is 20, maximum length is 2048.

      • iamUserARN string

        Amazon Resource Name (ARN) of the user that the data lake assumes when accessing data stores.

      • roleId string Required

        Unique identifier of the role that the data lake can use to access the data stores.Required if specifying cloudProviderConfig.

    • azure object

      Configuration for running Data Federation in Azure.

      Hide azure attributes Show azure attributes object

      • atlasAppId string

        The App ID generated by Atlas for the Service Principal's access policy.

      • roleId string Required

        Unique identifier of the role that Data Federation can use to access the data stores.Required if specifying cloudProviderConfig.

      • servicePrincipalId string

        The ID of the Service Principal for which there is an access policyfor Atlas to access Azure resources.

      • tenantId string

        The Azure Active Directory / Entra ID tenant ID associated with the Service Principal.

  • dataProcessRegion object

    Information about the cloud provider region to which the Federated Database Instance routes client connections.

    Hide dataProcessRegion attributes Show dataProcessRegion attributes object

    • cloudProvider string Required

      Name of the cloud service that hosts the Federated Database Instance's infrastructure.

      Values are AWS or AZURE.

    • region string Required

      Name of the region to which the data lake routes client connections.

      One of:

      ApiAtlasDataLakeAWSRegionView string AtlasDataFederationAzureRegion string

      Atlas Data Federation AWS Regions.

      Values are SYDNEY_AUS, MUMBAI_IND, FRANKFURT_DEU, DUBLIN_IRL, LONDON_GBR, VIRGINIA_USA, OREGON_USA, SAOPAULO_BRA, MONTREAL_CAN, TOKYO_JPN, or SINGAPORE_SGP.

      Atlas Data Federation Azure Regions.

      Values are VIRGINIA_USA or AMSTERDAM_NLD.

  • groupId string

    Unique 24-hexadecimal character string that identifies the project.

    Minimum length is 24, maximum length is 24. Format should match the following pattern: ^([a-f0-9]{24})$.

  • hostnames array[string]

    List that contains the hostnames assigned to the Federated Database Instance.

  • name string

    Human-readable label that identifies the Federated Database Instance.

  • privateEndpointHostnames array[object]

    List that contains the sets of private endpoints and hostnames.

    Set of Private endpoint and hostnames.

    Hide privateEndpointHostnames attributes Show privateEndpointHostnames attributes object

    • hostname string

      Human-readable label that identifies the hostname.

    • privateEndpoint string

      Human-readable label that identifies private endpoint.

  • state string

    Label that indicates the status of the Federated Database Instance.

    Values are UNVERIFIED, ACTIVE, or DELETED.

  • storage object

    Configuration information for each data store and its mapping to MongoDB Cloud databases.

    Hide storage attributes Show storage attributes object

    • databases array[object]

      Array that contains the queryable databases and collections for this data lake.

      Database associated with this data lake. Databases contain collections and views.

      Hide databases attributes Show databases attributes object

      • collections array[object]

        Array of collections and data sources that map to a stores data store.

        A collection and data sources that map to a stores data store.

        Hide collections attributes Show collections attributes object

        • dataSources array[object]

          Array that contains the data stores that map to a collection for this data lake.

          Data store that maps to a collection for this data lake.

          Hide dataSources attributes Show dataSources attributes object

          • allowInsecure boolean

            Flag that validates the scheme in the specified URLs. If true, allows insecure HTTP scheme, doesn't verify the server's certificate chain and hostname, and accepts any certificate with any hostname presented by the server. If false, allows secure HTTPS scheme only.

            Default value is false.

          • collection string

            Human-readable label that identifies the collection in the database. For creating a wildcard (*) collection, you must omit this parameter.

          • collectionRegex string

            Regex pattern to use for creating the wildcard (*) collection. To learn more about the regex syntax, see Go programming language.

          • database string

            Human-readable label that identifies the database, which contains the collection in the cluster. You must omit this parameter to generate wildcard (*) collections for dynamically generated databases.

          • databaseRegex string

            Regex pattern to use for creating the wildcard (*) database. To learn more about the regex syntax, see Go programming language.

          • datasetName string

            Human-readable label that identifies the dataset that Atlas generates for an ingestion pipeline run or Online Archive.

          • datasetPrefix string

            Human-readable label that matches against the dataset names for ingestion pipeline runs or Online Archives.

          • defaultFormat string

            File format that MongoDB Cloud uses if it encounters a file without a file extension while searching storeName.

            Values are .avro, .avro.bz2, .avro.gz, .bson, .bson.bz2, .bson.gz, .bsonx, .csv, .csv.bz2, .csv.gz, .json, .json.bz2, .json.gz, .orc, .parquet, .tsv, .tsv.bz2, or .tsv.gz.

          • path string

            File path that controls how MongoDB Cloud searches for and parses files in the storeName before mapping them to a collection.Specify / to capture all files and folders from the prefix path.

          • provenanceFieldName string

            Name for the field that includes the provenance of the documents in the results. MongoDB Cloud returns different fields in the results for each supported provider.

          • storeName string

            Human-readable label that identifies the data store that MongoDB Cloud maps to the collection.

          • trimLevel integer(int32)

            Unsigned integer that specifies how many fields of the dataset name to trim from the left of the dataset name before mapping the remaining fields to a wildcard collection name.

          • urls array[string]

            URLs of the publicly accessible data files. You can't specify URLs that require authentication. Atlas Data Lake creates a partition for each URL. If empty or omitted, Data Lake uses the URLs from the store specified in the dataSources.storeName parameter.

        • name string

          Human-readable label that identifies the collection to which MongoDB Cloud maps the data in the data stores.

      • maxWildcardCollections integer(int32)

        Maximum number of wildcard collections in the database. This only applies to S3 data sources.

        Minimum value is 1, maximum value is 1000. Default value is 100.

      • name string

        Human-readable label that identifies the database to which the data lake maps data.

      • views array[object]

        Array of aggregation pipelines that apply to the collection. This only applies to S3 data sources.

        An aggregation pipeline that applies to the collection.

        Hide views attributes Show views attributes object

        • name string

          Human-readable label that identifies the view, which corresponds to an aggregation pipeline on a collection.

        • pipeline string

          Aggregation pipeline stages to apply to the source collection.

          Aggregation Pipelines
        • source string

          Human-readable label that identifies the source collection for the view.

    • stores array[object]

      Array that contains the data stores for the data lake.

      One of:

      s3 object dls:aws object dls:azure object atlas object http object azure object

      Group of settings that define where the data is stored.

      Hide attributes Show attributes

      • name string

        Human-readable label that identifies the data store. The databases.[n].collections.[n].dataSources.[n].storeName field references this values as part of the mapping configuration. To use MongoDB Cloud as a data store, the data lake requires a serverless instance or an M10 or higher cluster.

      • provider string Required Discriminator

        Value is s3.

      • additionalStorageClasses array[string]

        Collection of AWS S3 storage classes. Atlas Data Lake includes the files in these storage classes in the query results.

        Values are STANDARD, INTELLIGENT_TIERING, or STANDARD_IA.

      • bucket string

        Human-readable label that identifies the AWS S3 bucket. This label must exactly match the name of an S3 bucket that the data lake can access with the configured AWS Identity and Access Management (IAM) credentials.

      • delimiter string

        The delimiter that separates databases.[n].collections.[n].dataSources.[n].path segments in the data store. MongoDB Cloud uses the delimiter to efficiently traverse S3 buckets with a hierarchical directory structure. You can specify any character supported by the S3 object keys as the delimiter. For example, you can specify an underscore () or a plus sign (+) or multiple characters, such as double underscores (_) as the delimiter. If omitted, defaults to /.

      • includeTags boolean

        Flag that indicates whether to use S3 tags on the files in the given path as additional partition attributes. If set to true, data lake adds the S3 tags as additional partition attributes and adds new top-level BSON elements associating each tag to each document.

        Default value is false.

      • prefix string

        Prefix that MongoDB Cloud applies when searching for files in the S3 bucket. The data store prepends the value of prefix to the databases.[n].collections.[n].dataSources.[n].path to create the full path for files to ingest. If omitted, MongoDB Cloud searches all files from the root of the S3 bucket.

      • public boolean

        Flag that indicates whether the bucket is public. If set to true, MongoDB Cloud doesn't use the configured AWS Identity and Access Management (IAM) role to access the S3 bucket. If set to false, the configured AWS IAM role must include permissions to access the S3 bucket.

        Default value is false.

      • region string

        Physical location where MongoDB Cloud deploys your AWS-hosted MongoDB cluster nodes. The region you choose can affect network latency for clients accessing your databases. When MongoDB Cloud deploys a dedicated cluster, it checks if a VPC or VPC connection exists for that provider and region. If not, MongoDB Cloud creates them as part of the deployment. MongoDB Cloud assigns the VPC a CIDR block. To limit a new VPC peering connection to one CIDR block and region, create the connection first. Deploy the cluster after the connection starts.

        Values are US_GOV_WEST_1, US_GOV_EAST_1, US_EAST_1, US_EAST_2, US_WEST_1, US_WEST_2, CA_CENTRAL_1, EU_NORTH_1, EU_WEST_1, EU_WEST_2, EU_WEST_3, EU_CENTRAL_1, EU_CENTRAL_2, AP_EAST_1, AP_NORTHEAST_1, AP_NORTHEAST_2, AP_NORTHEAST_3, AP_SOUTHEAST_1, AP_SOUTHEAST_2, AP_SOUTHEAST_3, AP_SOUTHEAST_4, AP_SOUTH_1, AP_SOUTH_2, SA_EAST_1, CN_NORTH_1, CN_NORTHWEST_1, ME_SOUTH_1, ME_CENTRAL_1, AF_SOUTH_1, EU_SOUTH_1, EU_SOUTH_2, IL_CENTRAL_1, CA_WEST_1, or GLOBAL.

      Group of settings that define where the data is stored.

      Hide attributes Show attributes

      • name string

        Human-readable label that identifies the data store. The databases.[n].collections.[n].dataSources.[n].storeName field references this values as part of the mapping configuration. To use MongoDB Cloud as a data store, the data lake requires a serverless instance or an M10 or higher cluster.

      • provider string Required Discriminator

        Value is dls:aws.

      • region string

        Physical location where MongoDB Cloud deploys your AWS-hosted MongoDB cluster nodes. The region you choose can affect network latency for clients accessing your databases. When MongoDB Cloud deploys a dedicated cluster, it checks if a VPC or VPC connection exists for that provider and region. If not, MongoDB Cloud creates them as part of the deployment. MongoDB Cloud assigns the VPC a CIDR block. To limit a new VPC peering connection to one CIDR block and region, create the connection first. Deploy the cluster after the connection starts.

        Values are US_GOV_WEST_1, US_GOV_EAST_1, US_EAST_1, US_EAST_2, US_WEST_1, US_WEST_2, CA_CENTRAL_1, EU_NORTH_1, EU_WEST_1, EU_WEST_2, EU_WEST_3, EU_CENTRAL_1, EU_CENTRAL_2, AP_EAST_1, AP_NORTHEAST_1, AP_NORTHEAST_2, AP_NORTHEAST_3, AP_SOUTHEAST_1, AP_SOUTHEAST_2, AP_SOUTHEAST_3, AP_SOUTHEAST_4, AP_SOUTH_1, AP_SOUTH_2, SA_EAST_1, CN_NORTH_1, CN_NORTHWEST_1, ME_SOUTH_1, ME_CENTRAL_1, AF_SOUTH_1, EU_SOUTH_1, EU_SOUTH_2, IL_CENTRAL_1, CA_WEST_1, or GLOBAL.

      Group of settings that define where the data is stored.

      Hide attributes Show attributes

      • name string

        Human-readable label that identifies the data store. The databases.[n].collections.[n].dataSources.[n].storeName field references this values as part of the mapping configuration. To use MongoDB Cloud as a data store, the data lake requires a serverless instance or an M10 or higher cluster.

      • provider string Required Discriminator

        Value is dls:azure.

      • region string

        Microsoft Azure Regions.

        Values are US_CENTRAL, US_EAST, US_EAST_2, US_NORTH_CENTRAL, US_WEST, US_SOUTH_CENTRAL, EUROPE_NORTH, EUROPE_WEST, US_WEST_CENTRAL, US_WEST_2, US_WEST_3, CANADA_EAST, CANADA_CENTRAL, BRAZIL_SOUTH, BRAZIL_SOUTHEAST, AUSTRALIA_CENTRAL, AUSTRALIA_CENTRAL_2, AUSTRALIA_EAST, AUSTRALIA_SOUTH_EAST, GERMANY_CENTRAL, GERMANY_NORTH_EAST, GERMANY_WEST_CENTRAL, GERMANY_NORTH, SWEDEN_CENTRAL, SWEDEN_SOUTH, SWITZERLAND_NORTH, SWITZERLAND_WEST, UK_SOUTH, UK_WEST, NORWAY_EAST, NORWAY_WEST, INDIA_CENTRAL, INDIA_SOUTH, INDIA_WEST, CHINA_EAST, CHINA_NORTH, ASIA_EAST, JAPAN_EAST, JAPAN_WEST, ASIA_SOUTH_EAST, KOREA_CENTRAL, KOREA_SOUTH, FRANCE_CENTRAL, FRANCE_SOUTH, SOUTH_AFRICA_NORTH, SOUTH_AFRICA_WEST, UAE_CENTRAL, UAE_NORTH, or QATAR_CENTRAL.

      Group of settings that define where the data is stored.

      Hide attributes Show attributes

      • name string

        Human-readable label that identifies the data store. The databases.[n].collections.[n].dataSources.[n].storeName field references this values as part of the mapping configuration. To use MongoDB Cloud as a data store, the data lake requires a serverless instance or an M10 or higher cluster.

      • provider string Required Discriminator

        Value is atlas.

      • clusterName string

        Human-readable label of the MongoDB Cloud cluster on which the store is based.

      • projectId string

        Unique 24-hexadecimal digit string that identifies the project.

        Minimum length is 24, maximum length is 24. Format should match the following pattern: ^([a-f0-9]{24})$.

      • readConcern object

        MongoDB Cloud cluster read concern, which determines the consistency and isolation properties of the data read from an Atlas cluster.

        Hide readConcern attribute Show readConcern attribute object

        • level string

          Read Concern level that specifies the consistency and availability of the data read.

          Values are LOCAL, MAJORITY, LINEARIZABLE, SNAPSHOT, or AVAILABLE.

          Read Concern Level
      • readPreference object

        MongoDB Cloud cluster read preference, which describes how to route read requests to the cluster.

        Hide readPreference attributes Show readPreference attributes object

        • maxStalenessSeconds integer(int32)

          Maximum replication lag, or staleness, for reads from secondaries.

        • mode string

          Read preference mode that specifies to which replica set member to route the read requests.

          Values are primary, primaryPreferred, secondary, secondaryPreferred, or nearest.

          Read Preference Modes
        • tagSets array[array]

          List that contains tag sets or tag specification documents. If specified, Atlas Data Lake routes read requests to replica set member or members that are associated with the specified tags.

          Read Preference Tag Set Lists
          Hide tagSets attributes Show tagSets attributes object

          • name string

            Human-readable label of the tag.

          • value string

            Value of the tag.

      Group of settings that define where the data is stored.

      Hide attributes Show attributes

      • name string

        Human-readable label that identifies the data store. The databases.[n].collections.[n].dataSources.[n].storeName field references this values as part of the mapping configuration. To use MongoDB Cloud as a data store, the data lake requires a serverless instance or an M10 or higher cluster.

      • provider string Required Discriminator

        Value is http.

      • allowInsecure boolean

        Flag that validates the scheme in the specified URLs. If true, allows insecure HTTP scheme, doesn't verify the server's certificate chain and hostname, and accepts any certificate with any hostname presented by the server. If false, allows secure HTTPS scheme only.

        Default value is false.

      • defaultFormat string

        Default format that Data Lake assumes if it encounters a file without an extension while searching the storeName. If omitted, Data Lake attempts to detect the file type by processing a few bytes of the file. The specified format only applies to the URLs specified in the databases.[n].collections.[n].dataSources object.

      • urls array[string]

        Comma-separated list of publicly accessible HTTP URLs where data is stored. You can't specify URLs that require authentication.

      Group of settings that define where the data is stored.

      Hide attributes Show attributes

      • name string

        Human-readable label that identifies the data store. The databases.[n].collections.[n].dataSources.[n].storeName field references this values as part of the mapping configuration. To use MongoDB Cloud as a data store, the data lake requires a serverless instance or an M10 or higher cluster.

      • provider string Required Discriminator

        Value is azure.

      • containerName string

        Human-readable label that identifies the name of the container.

      • delimiter string

        Delimiter.

      • prefix string

        Prefix.

      • public boolean

        Flag that indicates whether the blob store is public. If set to true, MongoDB Cloud doesn't use the configured Azure service principal to access the blob store. If set to false, the configured Azure service principal must include permissions to access the blob store.

        Default value is false.

      • region string

        Microsoft Azure Regions.

        Values are US_CENTRAL, US_EAST, US_EAST_2, US_NORTH_CENTRAL, US_WEST, US_SOUTH_CENTRAL, EUROPE_NORTH, EUROPE_WEST, US_WEST_CENTRAL, US_WEST_2, US_WEST_3, CANADA_EAST, CANADA_CENTRAL, BRAZIL_SOUTH, BRAZIL_SOUTHEAST, AUSTRALIA_CENTRAL, AUSTRALIA_CENTRAL_2, AUSTRALIA_EAST, AUSTRALIA_SOUTH_EAST, GERMANY_CENTRAL, GERMANY_NORTH_EAST, GERMANY_WEST_CENTRAL, GERMANY_NORTH, SWEDEN_CENTRAL, SWEDEN_SOUTH, SWITZERLAND_NORTH, SWITZERLAND_WEST, UK_SOUTH, UK_WEST, NORWAY_EAST, NORWAY_WEST, INDIA_CENTRAL, INDIA_SOUTH, INDIA_WEST, CHINA_EAST, CHINA_NORTH, ASIA_EAST, JAPAN_EAST, JAPAN_WEST, ASIA_SOUTH_EAST, KOREA_CENTRAL, KOREA_SOUTH, FRANCE_CENTRAL, FRANCE_SOUTH, SOUTH_AFRICA_NORTH, SOUTH_AFRICA_WEST, UAE_CENTRAL, UAE_NORTH, or QATAR_CENTRAL.

      • replacementDelimiter string

        Replacement Delimiter.

      • serviceURL string

        Service URL.

• 400 application/json

  Bad Request.

  Hide response attributes Show response attributes object

  • detail string

    Describes the specific conditions or reasons that cause each type of error.

  • error integer(int32)

    HTTP status code returned with this error.

    External documentation
  • errorCode string

    Application error code returned with this error.

  • parameters array[object]

    Parameters used to give more information about the error.
  • reason string

    Application error message returned with this error.

• 404 application/json

  Not Found.

  Hide response attributes Show response attributes object

  • detail string

    Describes the specific conditions or reasons that cause each type of error.

  • error integer(int32)

    HTTP status code returned with this error.

    External documentation
  • errorCode string

    Application error code returned with this error.

  • parameters array[object]

    Parameters used to give more information about the error.
  • reason string

    Application error message returned with this error.

• 500 application/json

  Internal Server Error.

  Hide response attributes Show response attributes object

  • detail string

    Describes the specific conditions or reasons that cause each type of error.

  • error integer(int32)

    HTTP status code returned with this error.

    External documentation
  • errorCode string

    Application error code returned with this error.

  • parameters array[object]

    Parameters used to give more information about the error.
  • reason string

    Application error message returned with this error.