> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Query model, field type mapping, refresh cadence, and limits for the MongoDB data source in Adriel.

## 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-sources/g-n/mongodb/how-to-connect).

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

<Note>
  **Adriel connects through a database proxy, not directly**

  The 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.
</Note>

## 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:

| Operator | Date field                                                                       | Non-date field                                                                    |
| -------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `EQUAL`  | —                                                                                | Direct equality match on the value.                                               |
| `IN`     | Each value expands to a day-inclusive range (`$gte value`, `$lt value + 1 day`). | Values are cast to numbers unless the field is text; produces an `$in` condition. |
| `LIKE`   | —                                                                                | Each value becomes a `$regex` condition; multiple values are AND-combined.        |

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

<Note>
  **How to read the columns**

  The **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.
</Note>

<Note>
  **Fields with mixed or unknown types become text**

  Because 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.
</Note>

Each MongoDB (BSON) type maps to an Adriel field type as follows.

| MongoDB (BSON) type                     | Adriel field type | Data type | Field role                                                                       |
| --------------------------------------- | ----------------- | --------- | -------------------------------------------------------------------------------- |
| `Int32`, `Long`, `Double`, `Decimal128` | `number`          | Number    | Metric                                                                           |
| `String`                                | `string`          | Text      | Metric or breakdown                                                              |
| `ObjectId`                              | `string`          | Text      | Metric or breakdown; serialized as a 24-character hex string                     |
| `Date`, `Timestamp`                     | `date`            | Date      | Metric or breakdown; used for date-range filtering when mapped as the date field |
| `Object` (sub-document)                 | Flattened         | —         | Child fields exposed via `parent.child` path notation                            |
| `Array`                                 | Pipeline-handled  | —         | Surfaced through aggregation operators rather than expanded into rows            |
| Mixed, absent, or any other BSON type   | `string`          | Text      | Metric or breakdown                                                              |

### Aggregation defaults

When no explicit aggregation is set on a field, the connector chooses one based on the resolved field type:

| Field type               | Default aggregation                                                                                                                                                                                  |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Number                   | `$sum` — sums the values in the group.                                                                                                                                                               |
| Text and all other types | `$addToSet` — collects the distinct values in the group. When exactly one distinct value exists, that value is returned (truncated to 50 characters); when more than one exists, the cell shows `-`. |

An explicit per-field aggregation overrides the default. The available aggregations map to MongoDB accumulators as follows:

| Aggregation | MongoDB accumulator |
| ----------- | ------------------- |
| Sum         | `$sum`              |
| Mean        | `$avg`              |
| Median      | `$median`           |
| Min         | `$min`              |
| Max         | `$max`              |

## 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

* [MongoDB aggregation pipeline reference](https://www.mongodb.com/docs/manual/core/aggregation-pipeline/)
* [Aggregation pipeline stages](https://www.mongodb.com/docs/manual/reference/operator/aggregation-pipeline/)
* [BSON types](https://www.mongodb.com/docs/manual/reference/bson-types/)
* [Connection string URI format](https://www.mongodb.com/docs/manual/reference/connection-string/)

## See also

* [How to connect MongoDB](/data-sources/g-n/mongodb/how-to-connect) (paired how-to)
* [MySQL data reference](/data-sources/g-n/mysql/data-reference) — SQL database alternative
* [PostgreSQL data reference](/data-sources/o-z/postgres/data-reference) — SQL database alternative
* [Amazon Redshift data reference](/data-sources/o-z/redshift/data-reference) — cloud data warehouse alternative
* [Google BigQuery data reference](/data-sources/g-n/google-bigquery/data-reference) — cloud data warehouse alternative