MongoDB Atlas Charts
Parent: MongoDB Atlas · Published reference · snapshot 2026-09-08 · skill mongodb-atlas-expert/references/mongodb-atlas-charts.md
↓ Facts as markdownall context files
Atlas Charts is MongoDB's built-in BI and data visualization layer, native to the Atlas platform. No separate cluster, ETL pipeline, or data warehouse needed — it queries Atlas collections directly.
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.
1. Atlas Charts Overview
- Atlas Charts is MongoDB's built-in BI and data visualization layer, native to the Atlas platform. No separate cluster, ETL pipeline, or data warehouse needed - it queries Atlas collections directly. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#1-atlas-charts-overview]
- Key characteristics: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#1-atlas-charts-overview]
- No driver required; reads directly from the cluster via Atlas data-access path [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#1-atlas-charts-overview]
- Real-time queries - each chart load triggers a live aggregation query [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#1-atlas-charts-overview]
- No separate cluster: reads from the cluster you designate as a data source [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#1-atlas-charts-overview]
- Sub-100ms live refresh → Grafana + Atlas monitoring panels [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#1-atlas-charts-overview]
- Row-level security at query time → application-layer query API [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#1-atlas-charts-overview]
- Complex cross-cluster joins → Atlas Data Federation + dedicated BI tool [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#1-atlas-charts-overview]
- Streaming / CDC visualization → Charts is not designed for event-stream display [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#1-atlas-charts-overview]
3. Data Sources
- Direct cluster access: Add cluster → select database + collection → Charts auto-samples up to 1,000 documents for field discovery [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#3-data-sources]
- Federated data sources: Atlas Data Federation can expose S3/Azure Blob/GCS/BigQuery. Federated queries are slower - avoid live-dashboard use cases requiring sub-second render times over S3-backed sources. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#3-data-sources]
4. Aggregation Pipeline in Charts
- Query bar: Accepts an MQL filter document applied as a $match stage [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#4-aggregation-pipeline-in-charts]
- Encoding-driven aggregation: Charts automatically constructs a pipeline from your field selections [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#4-aggregation-pipeline-in-charts]
- Custom pipelines: Write full pipeline JSON in Custom mode. Must emit documents where each top-level field maps to an encoding channel. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#4-aggregation-pipeline-in-charts]
5. Dashboard Features
- Filters: Dashboard-level filters apply across all charts sharing the same collection. Additive with chart-level query bar filters. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#5-dashboard-features]
- Chart alerts: Evaluate on each scheduled refresh (minimum 5 minutes on paid tiers). Notifications via email or webhook. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#5-dashboard-features]
- Sharing: Within-project sharing at Viewer or Author level, PDF/PNG export, embed (iframe or SDK), dashboard JSON export. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#5-dashboard-features]
Unauthenticated (public) embedding
- Generates a public embed URL. Suitable for public-facing dashboards with non-sensitive data. Always configure a restrictive base filter in embed settings. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#unauthenticated-public-embedding]
Authenticated SDK embedding (@mongodb-js/charts-embed-dom)
- Uses the Charts JavaScript SDK. Requires a backend-issued signed JWT. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#authenticated-sdk-embedding-mongodb-jscharts-embed-dom]
7. JWT-based Filter Security
- CRITICAL: Never pass filter values directly from untrusted client input. Always sign tenant-scoped filters in a backend-issued JWT: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#7-jwt-based-filter-security]
- The JWT must be signed with the Embedding Signing Key configured in Charts project settings. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#7-jwt-based-filter-security]
8. Charts API (REST)
- Base URL: https://cloud.mongodb.com/api/atlas/v1.0/groups/{groupId}/charts/ Authentication: Atlas programmatic API keys with Digest authentication. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#8-charts-api-rest]
- Common operations: list/get/create/delete dashboards, list/get/update chart definitions. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#8-charts-api-rest]
- Use cases: CI/CD version control of chart definitions, tenant provisioning (clone template dashboard via API), bulk updates. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#8-charts-api-rest]
9. Access Control
- Atlas project Owners automatically receive Charts Admin. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#9-access-control]
10. Anti-Patterns
- Unfiltered large collection queries: Always add a query bar filter. For time-series data, filter to last N days by default. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#10-anti-patterns]
- No caching for embedded charts: Use SDK's maxDataAge property to enable client-side result caching. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#10-anti-patterns]
- Missing filter security on multi-tenant embeds: Always use backend-signed JWT for tenant-scoped filters. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#10-anti-patterns]
- Charts as real-time operational dashboard: Charts is not designed for sub-100ms refresh. Use Grafana instead. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#10-anti-patterns]
- Too many data sources per dashboard: Consolidate related metrics into pre-aggregated summary collections. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#10-anti-patterns]
- Exposing sensitive fields through unauthenticated embeds: Configure restrictive base filter in embed settings. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#10-anti-patterns]
11. Cost Model
- Free tier: Unlimited dashboards for Atlas-authenticated users + monthly embedded render quota (historically 1,000 renders/month) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#11-cost-model]
- Paid embedded renders: Per-render rate above free quota. maxDataAge directly reduces billing. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#11-cost-model]
- No separate Charts cluster cost: Pay only for Atlas cluster + renders above free tier. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#11-cost-model]
- Federated source cost: Atlas Data Federation processing fees (per GB) apply. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#11-cost-model]
12. SDK Quick Reference
- Installation: npm install @mongodb-js/charts-embed-dom [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#12-sdk-quick-reference]
- SDK initialization checklist: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#12-sdk-quick-reference]
- Configure embedding signing key in Atlas Charts project settings [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#12-sdk-quick-reference]
- Build backend endpoint issuing short-lived signed JWTs with mongodbFilter claims [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#12-sdk-quick-reference]
- Use getUserToken in SDK - never generate/hardcode signing key client-side [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#12-sdk-quick-reference]
- Set maxDataAge for data freshness/cost control [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#12-sdk-quick-reference]
- Subscribe to click events for drilldown navigation [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-charts/#12-sdk-quick-reference]
Where this helps
- Building an internal or customer-facing dashboard directly against Atlas data without standing up a separate BI warehouse or ETL pipeline. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Embedding a filtered, tenant-scoped chart into a multi-tenant SaaS product, where filter security has to be enforced server-side rather than trusted from the client. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Publishing a public-facing dashboard on non-sensitive data via unauthenticated embedding. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Automating dashboard provisioning, such as cloning a template dashboard per new tenant, via the Charts REST API instead of manual UI setup. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Project ideas
- Build a multi-tenant embedded dashboard where each tenant's filter is enforced through a backend-issued signed JWT rather than a client-supplied filter value. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Automate tenant onboarding by using the Charts API to clone a template dashboard and provision it programmatically for each new customer. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Build a pre-aggregated summary collection specifically for a Charts dashboard, to avoid unfiltered live aggregation queries against a large raw collection. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Wire up chart alerts on a scheduled refresh with webhook notifications for a metric that needs proactive monitoring. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Common mistakes
- Querying a large collection from a chart with no query-bar filter, instead of defaulting time-series charts to a "last N days" filter. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Trusting client-supplied filter values for a multi-tenant embed instead of signing tenant-scoped filters into a backend-issued JWT. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Treating Atlas Charts as a real-time operational dashboard — it is not built for sub-100ms refresh, and Grafana is the better fit for that use case. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Adding too many separate data sources to one dashboard instead of consolidating related metrics into pre-aggregated summary collections. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- Federated data sources (S3/Azure Blob/GCS/BigQuery via Atlas Data Federation) are noticeably slower than direct cluster sources, so they're a poor fit for dashboards that need sub-second render times. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Chart alerts evaluate on a scheduled refresh with a minimum interval of 5 minutes on paid tiers, so they can't substitute for real-time alerting. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Field discovery for a new data source auto-samples only up to 1,000 documents, which can miss less common fields in a large or highly variable schema. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- The embedded-render free quota (historically 1,000 renders/month) and per-render billing above it mean an unbounded or unfiltered embed can generate unexpected charges. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.