Atlas SQL Schema Builder

Parent: Atlas SQL Interface MongoSQL · Published reference · snapshot 2026-10-15 · viability 3.15 / 5 (skip)

Depth-first rabbithole dossier for Atlas SQL Schema Builder; source-anchored research pack.

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

Definitions

[medium] The MongoDB SQL Schema Builder CLI is the schema-management tool for the SQL Interface on Enterprise Advanced self-managed deployments and Atlas dedicated clusters (M10 and above). (verified as of 2026-10-15) Sources: https://www.mongodb.com/docs/sql-interface/index.md, https://www.mongodb.com/docs/sql-interface/schema-management.md, https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md, https://www.mongodb.com/docs/sql-interface/connect-with-sql-composable.md, https://www.mongodb.com/docs/sql-interface/changelog.md [source]
[medium] The MongoDB SQL Schema Builder CLI is not available for MongoDB Community clusters, Free clusters, Flex clusters, or M2 and M5 shared Atlas clusters. (verified as of 2026-10-15) Sources: https://www.mongodb.com/docs/sql-interface/index.md, https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md [source]
[low] Schemas are not shared between deployment types; a schema created with the MongoDB SQL Schema Builder CLI is not available via Atlas Data Federation, and vice versa. Sources: https://www.mongodb.com/docs/sql-interface/schema-management.md [source]

Structure and components

[low] To verify a created SQL schema, users can look for the __sql_schemas collection in the database, which contains a document for each collection with its schema map and data type assignments. Sources: https://www.mongodb.com/docs/sql-interface/connect-with-sql-composable.md [source]
[low] Later versions of SQL Interface components might drop support for earlier MongoDB server versions. Sources: https://www.mongodb.com/docs/sql-interface/index.md [source]

How it works

[low] The MongoDB SQL Schema Builder CLI requires the find, insert, and update privileges on the __sql_schemas collection, or the readWrite role, because it uses upserts even on the first run. Sources: https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md [source]
[low] The MongoDB SQL Schema Builder CLI directs schema reads to a secondary or analytics node when available, falling back to the primary node otherwise. Sources: https://www.mongodb.com/docs/sql-interface/changelog.md [source]
[low] When using the sampleNamespaces parameter with Atlas Data Federation, the command must be run against the admin database. Sources: https://www.mongodb.com/docs/sql-interface/schema/adf.md [source]
[low] When creating a quick start connection, Atlas Data Federation generates the schema automatically. Sources: https://www.mongodb.com/docs/sql-interface/schema/adf.md [source]
[low] An outdated schema can cause the SQL Interface to map collections to the wrong tables and columns. Sources: https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md [source]
[low] Use a federated database instance when a single SQL query must span more than one data source, such as multiple clusters or S3 buckets. Sources: https://www.mongodb.com/docs/sql-interface/index.md [source]

Problems, failure modes and limitations

[low] If no schema exists for a source collection or the CLI cannot derive the schema from available source schemas, the MongoDB SQL Schema Builder CLI falls back to executing the view and sampling its output documents. Sources: https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md [source]
[low] Atlas Data Federation returns an error if the specified namespaces do not exist in the storage configuration, are empty, or if it could not set the schema for a given namespace. Sources: https://www.mongodb.com/docs/sql-interface/schema/adf.md [source]

Comparisons and alternatives

[medium] Atlas Data Federation samples documents from collections to generate the initial schema, unlike the CLI which analyzes all documents. Sources: https://www.mongodb.com/docs/sql-interface/schema-management.md, https://www.mongodb.com/docs/sql-interface/schema/adf.md [source]

Facts and statements

[medium] On an Atlas dedicated cluster, the MongoDB SQL Schema Builder CLI requires the read privilege on the __mdb_internal_sqlinterface database and exits if the read fails. Sources: https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md, https://www.mongodb.com/docs/sql-interface/connect-with-sql-composable.md, https://www.mongodb.com/docs/sql-interface/install-driver.md [source]
[medium] An Atlas dedicated cluster or a self-managed Enterprise Advanced deployment must run MongoDB 6.0 or later to use the SQL Interface. (verified as of 2026-10-15) Sources: https://www.mongodb.com/docs/sql-interface/index.md, https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md, https://www.mongodb.com/docs/sql-interface/connect.md [source]
[low] The MongoDB SQL Schema Builder CLI writes one schema document per namespace to a __sql_schemas collection in each database it processes. Sources: https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md [source]
[low] By default, the MongoDB SQL Schema Builder CLI implicitly excludes any database or collection whose name begins with two underscores (__), including the __sql_schemas collection. Sources: https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md [source]
[low] If a namespace has a level of polymorphism too great for meaningful use, the MongoDB SQL Schema Builder CLI deems the schema unstable, sets unstable to true, caps captured fields, and sets additionalProperties to true. Sources: https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md [source]
[low] The MongoDB SQL Schema Builder CLI has a maximum number of concurrent schema-processing jobs, which must be an integer greater than 0, defaulting to two times the number of physical cores. Sources: https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md [source]
[medium] The MongoDB SQL Schema Builder CLI binary is named mongodb-schema-manager. Sources: https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md, https://www.mongodb.com/docs/sql-interface/connect-with-sql-composable.md [source]
[low] MongoDB SQL Schema Builder 1.1.0 introduces on-premises schema management. (verified as of 2026-10-15) Sources: https://www.mongodb.com/docs/sql-interface/changelog.md [source]
[medium] The MongoDB SQL Schema Builder CLI does not sample documents; it analyzes every document in each collection to generate a schema that precisely reflects the exact data. Sources: https://www.mongodb.com/docs/sql-interface/schema-management.md, https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md [source]
[low] The MongoDB SQL Schema Builder CLI does not detect data-shape changes automatically, so schema regeneration is always user-initiated. Sources: https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md [source]
[low] The MongoDB SQL Schema Builder CLI derives the schema of a view from the view pipeline and the schemas of the source collections it references. Sources: https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md [source]
[low] The default merge action in the MongoDB SQL Schema Builder CLI does not update an unstable schema; users must run the CLI with --action overwrite to update it. Sources: https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md [source]
Fact 133 states that an M0 cluster will work fine for Atlas SQL, while Facts 1, 21, 27, 67, and 121 state that dedicated clusters must be M10 and above. Sources: https://www.mongodb.com/docs/sql-interface/index.md, https://www.mongodb.com/docs/sql-interface/schema-management.md, https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md, https://www.mongodb.com/docs/sql-interface/connect.md, https://www.mongodb.com/docs/atlas/cluster-additional-settings.md, https://www.mongodb.com/community/forums/t/how-can-i-refresh-the-schema-thats-presented-to-sql-clients/264675 [source]
[low] The sqlGenerateSchema, sqlGetSchema, and sqlSetSchema commands and their Atlas UI equivalents apply only to the Atlas Data Federation deployment type. Sources: https://www.mongodb.com/docs/sql-interface/schema/adf.md [source]
[low] The format version of the schema in Atlas Data Federation is always 1. Sources: https://www.mongodb.com/docs/sql-interface/schema/adf.md [source]
[low] The SQL Interface schemas are JSON schemas that describe data as it exists in MongoDB, including polymorphism, sparseness, and nested structured data. Sources: https://www.mongodb.com/docs/sql-interface/schema-management.md [source]
[medium] JSON schemas are required to translate SQL queries between BI tools and the MongoDB database, and the SQL Interface uses them to translate queries into optimized MongoDB operations. Sources: https://www.mongodb.com/docs/sql-interface/index.md, https://www.mongodb.com/docs/sql-interface/schema-management.md [source]
[low] The Atlas Data Federation schema generation parameter for the number of documents to sample defaults to 1000 if omitted. Sources: https://www.mongodb.com/docs/sql-interface/schema/adf.md [source]
[low] The Atlas Data Federation parameter to store the generated schema defaults to false if omitted; if true, it overwrites any existing schema for the collection or view. Sources: https://www.mongodb.com/docs/sql-interface/schema/adf.md [source]
[low] The Atlas Data Federation command does not validate the provided schema against the data in the collection. Sources: https://www.mongodb.com/docs/sql-interface/schema/adf.md [source]
[low] Scheduled schema updates in Atlas Data Federation sample each namespace and merge the new schema with the existing one. Sources: https://www.mongodb.com/docs/sql-interface/schema/adf.md [source]
Fact 145 states the capability is limited to MongoDB's Atlas cloud, while Facts 7, 21, 25, and 60 state the CLI is used for self-managed Enterprise Advanced deployments. Sources: https://www.mongodb.com/docs/sql-interface/index.md, https://www.mongodb.com/docs/sql-interface/schema-management.md, https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md, https://www.mongodb.com/docs/sql-interface/connect-with-sql-composable.md, https://www.dbta.com/Columns/MongoDB-Matters/MongoDB-60-Introduces-New-NoSQL-SQL-Engine-155052.aspx [source]
[low] The SQL Interface requires a MongoDB Enterprise cluster; Community clusters are not supported. Sources: https://www.mongodb.com/docs/sql-interface/index.md [source]
[low] The SQL Interface provides live, read-only access over standard ODBC and JDBC connections, eliminating the need to learn MQL or move data out of MongoDB for analytics. Sources: https://www.mongodb.com/docs/sql-interface/index.md [source]
[low] The SQL Interface uses the MongoSQL dialect, which is SQL-92 compatible and supports complex transformations like flattening nested objects and unwinding arrays directly within SQL queries. Sources: https://www.mongodb.com/docs/sql-interface/index.md [source]
[low] The SQL Interface does not support inserting, updating, or deleting documents on any deployment, and it does not support other SQL dialects. Sources: https://www.mongodb.com/docs/sql-interface/index.md [source]
[medium] An Atlas federated database instance must be mapped to one or more data stores, and each Atlas cluster it reads from must run MongoDB 5.0 or later. (verified as of 2026-10-15) Sources: https://www.mongodb.com/docs/sql-interface/index.md, https://www.mongodb.com/docs/sql-interface/connect.md [source]
[low] Schema computations adapt to data and represent collections natively; schemas are not cached and can be refreshed at any time without impacting connectivity. Sources: https://www.mongodb.com/docs/sql-interface/index.md [source]
[low] All three SQL Interface deployment options use the same JDBC and ODBC drivers. Sources: https://www.mongodb.com/docs/sql-interface/connect.md [source]
[low] Microsoft updates Power BI monthly, and Atlas supports only the latest version of Power BI Desktop. (verified as of 2026-10-15) Sources: https://www.mongodb.com/docs/sql-interface/connect.md [source]

Related concepts

Schema — is a part of Atlas SQL Schema Builder
SQL — is a part of Atlas SQL Schema Builder
Atlas — is a part of Atlas SQL Schema Builder
Builder — is a part of Atlas SQL Schema Builder

Children

No children recorded.

← the whole tree · 3D view· how to read this page