Skip to main content

​
Introduction

MongoDB is a document database that stores data as flexible, schema-less documents inside collections. The Adriel MongoDB connector binds one Adriel data source to one MongoDB collection, discovers that collection’s fields by sampling documents, and lets those fields be used as metrics and breakdowns in widgets. When a widget loads, the connector compiles the widget configuration into a MongoDB aggregation pipeline, runs it against the collection, and returns the result. Adriel never opens a native MongoDB connection. Every operation is dispatched over HTTP to an external database proxy service that holds the MongoDB driver and executes the pipeline, keeping MongoDB connectivity isolated from the dashboard service. As a database connector, the available fields are not a fixed catalog — they are derived from the documents in the bound collection. Because MongoDB does not enforce a schema, fields and types can vary from document to document, so the connector resolves field types by sampling and maps them to Adriel field types. Numeric fields become metrics, while text and other fields can serve as either a metric or a breakdown. To connect this data source, see How to connect MongoDB to Adriel.

​
Data refresh strategy

MongoDB data is fetched on demand. There is no incremental sync — every dashboard, widget, or report load issues a live aggregation pipeline against the bound collection, so results always reflect whatever the collection contains at request time. Field-metadata cache. The collection’s resolved field list is memoized per data source for 300 seconds (5 minutes). New fields added on the MongoDB side become visible after this cache refreshes.

​
Architecture levels

MongoDB deployment → Database → Collection. Discovery walks these levels through the database proxy:
  1. Deployment — the connected MongoDB deployment (replica set, sharded cluster, or Atlas database).
  2. Databases — every database the connected credentials can access.
  3. Collections — every collection within the chosen database.
One Adriel data source binds to one MongoDB collection. To expose a second collection, create a second data source.
Adriel connects through a database proxy, not directlyThe dashboard service does not reach MongoDB directly — an external database proxy holds the driver and issues every operation. IP allowlists on MongoDB Atlas, and firewall rules on self-hosted deployments, must permit the proxy’s egress addresses. See the paired how-to for the addresses to allow.

​
Date range limits

There is no platform-imposed date range limit. Query bounds are set by the widget’s date-range control combined with the field mapped as the date field on the bound collection. A default 1,000-document result cap applies to every pipeline, so refine widget filters — or pre-aggregate on the MongoDB side — for tighter result shaping.

​
Query model

Widget queries are compiled into a MongoDB aggregation pipeline, not SQL. Each request produces a pipeline whose stages are assembled in this fixed order:
  1. Column pre-filter injection — any data-source-level column filter is appended to the query’s where conditions before anything else.
  2. Field type resolution — field types are resolved from the collection (from cache when available) so later stages know how to treat each field.
  3. $match from widget filters — widget where conditions become a $match document.
  4. Date range filter — the widget date range is merged into the same $match (or added as a second $match if none exists), as either a direct $gte/$lt bound or an $expr condition, depending on the date field’s type.
  5. $group — the breakdown selection forms the group key (_id) and each field’s aggregation forms the accumulators.
  6. $sort — added only when the widget specifies a sort.
  7. $limit — always appended, using the widget’s limit or the default of 1,000 documents.
Breakdown behavior. When the breakdown is set to all, the group key collapses to a single full-collection aggregate (_id: null) and one summary row is returned. With named breakdown fields, each selected field becomes a key in the group key and each distinct combination becomes a row. Breakdown fields of a date type are formatted as yyyy-MM-dd in the group key.

​
Filters

Widget filters translate into aggregation-pipeline $match conditions using a whitelisted operator set. A data-source-level column pre-filter narrows every query on the data source before widget filters apply.

​
Supported filter operators

Only three operators are enabled for widget filters on MongoDB data sources:
  • EQUAL
  • IN
  • LIKE
Any other operator is rejected at query time. For richer logic, restructure the data on the MongoDB side or pre-aggregate into a purpose-built collection. How each operator translates:

​
Data-source pre-filters

Each data source can carry one optional column pre-filter, configured at creation time from three settings that must be provided together — setting any one without the others fails validation:
  • Filter column — the column to filter on. The lookup lists text-typed columns only; numeric and date columns cannot be used as a column pre-filter.
  • Filter type — one of the supported operators (EQUAL, IN, LIKE).
  • Filter value — the value to match. For IN, the value is split on commas into multiple values.
The pre-filter is appended to the where conditions of every query issued against that data source.

​
Date-range filtering

Date-range filtering is applied automatically to the field mapped as the collection’s date field. The upper bound is expanded by one day so the range is inclusive.

​
Field type mapping

MongoDB has no fixed metric or breakdown catalog. The available fields are the fields of the bound collection, resolved from sampled documents at query time.
How to read the columnsThe Data type column uses the platform’s ten-value vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean. The Field role column indicates whether the field can serve as a metric, a breakdown, or both.
Fields with mixed or unknown types become textBecause documents in the same collection can differ, a field’s type is not always consistent. A field whose sampled type cannot be resolved to a number or a date is exposed as a text field, so it stays available as a breakdown rather than being dropped.
Each MongoDB (BSON) type maps to an Adriel field type as follows.

​
Aggregation defaults

When no explicit aggregation is set on a field, the connector chooses one based on the resolved field type: An explicit per-field aggregation overrides the default. The available aggregations map to MongoDB accumulators as follows:

​
Limitations

Based on the current connector:
  • 1,000-document cap per widget query by default. A result set larger than the query can return surfaces as REQUESTED_RESULT_TOO_LARGE; refine filters or pre-aggregate to stay under the cap.
  • One collection per data source. Cross-collection joins are not supported — pre-join or pre-aggregate the data on the MongoDB side.
  • Aggregation pipeline only, no SQL. Widgets can only aggregate over the bound collection; there is no free-form query input. Logic with no MongoDB-pipeline equivalent is not available.
  • Filter operator whitelist. Only EQUAL, IN, and LIKE are available in widget filters.
  • Text-only column pre-filter. The data-source column pre-filter can target text-typed columns only, and its three settings must all be set together or left entirely unset.
  • Schema-less variance. Fields that appear in only some documents are treated as absent elsewhere; heavy shape variance across documents slows field discovery. Keeping document shape consistent gives the best dashboard performance.
  • 300-second field-metadata cache. New fields added on the MongoDB side become visible only after the field cache refreshes (up to 5 minutes).
  • 5-second field-discovery timeout. Field-type resolution is bounded by a 5-second timeout against the proxy; a collection that is slow to sample may fail schema discovery.
  • Proxy egress must be allowlisted. Because operations run through the database proxy, MongoDB Atlas IP allowlists and self-hosted firewalls must permit the proxy’s addresses, or the connection fails.

​
API references

​
See also