docs: Add MongoDB docs for data-source and offline-store integration

Signed-off-by: jvincent-mongodb <jeffrey.vincent@mongodb.com>
ntkathole · May 1, 2026 · Apr 29, 2026 · Apr 29, 2026 · Apr 30, 2026 · Apr 30, 2026
commit b322422d1e5d0c38381ce4772ebd15e7713aa4c2
@@ -113,6 +113,7 @@
   * [Athena (contrib)](reference/data-sources/athena.md)
   * [Clickhouse (contrib)](reference/data-sources/clickhouse.md)
   * [Ray (contrib)](reference/data-sources/ray.md)
+  * [MongoDB (contrib)](reference/data-sources/mongodb.md)
 * [Offline stores](reference/offline-stores/README.md)
   * [Overview](reference/offline-stores/overview.md)
   * [Dask](reference/offline-stores/dask.md)
@@ -129,6 +130,7 @@
   * [Ray (contrib)](reference/offline-stores/ray.md)
   * [Oracle (contrib)](reference/offline-stores/oracle.md)
   * [Athena (contrib)](reference/offline-stores/athena.md)
+  * [MongoDB (contrib)](reference/offline-stores/mongodb.md)
   * [Remote Offline](reference/offline-stores/remote-offline-store.md)
   * [Hybrid](reference/offline-stores/hybrid.md)
 * [Online stores](reference/online-stores/README.md)

@@ -69,3 +69,7 @@ Please see [Data Source](../../getting-started/concepts/data-ingestion.md) for a
 {% content-ref url="ray.md" %}
 [ray.md](ray.md)
 {% endcontent-ref %}
+
+{% content-ref url="mongodb.md" %}
+[mongodb.md](mongodb.md)
+{% endcontent-ref %}
@@ -0,0 +1,32 @@
+# MongoDB source (contrib)
+
+## Description
+
+MongoDB data sources are [MongoDB](https://www.mongodb.com/) collections that can be used as a source for feature data. The `MongoDBSource` points at a MongoDB collection and provides the metadata Feast needs to read historical features from the offline store's `feature_history` collection.
+
+## Examples
+
+Defining a MongoDB source:
+
+```python
+from feast.infra.offline_stores.contrib.mongodb_offline_store.mongodb_source import (
+    MongoDBSource,
+)
+
+driver_stats_source = MongoDBSource(
+    name="driver_stats",
+    timestamp_field="event_timestamp",
+    created_timestamp_column="created_at",
+)
+```
+
+The `name` field becomes the `feature_view` discriminator stored in every document in the `feature_history` collection.
+
+Configuration options such as `connection_string`, `database`, and `collection` are inherited from the offline store configuration in `feature_store.yaml`.
+
+The full set of configuration options is available [here](https://rtd.feast.dev/en/master/#feast.infra.offline_stores.contrib.mongodb_offline_store.mongodb_source.MongoDBSource).
+
+## Supported Types
+
+MongoDB data sources support all eight primitive types (`bytes`, `string`, `int32`, `int64`, `float32`, `float64`, `bool`, `timestamp`) and their corresponding array types. Complex types such as `Map` and `Struct` are preserved through the MongoDB document model.
+For a comparison against other batch data sources, please see [here](overview.md#functionality-matrix).
@@ -62,6 +62,10 @@ Please see [Offline Store](../../getting-started/components/offline-store.md) fo
 [clickhouse.md](clickhouse.md)
 {% endcontent-ref %}
 
+{% content-ref url="mongodb.md" %}
+[mongodb.md](mongodb.md)
+{% endcontent-ref %}
+
 {% content-ref url="remote-offline-store.md" %}
 [remote-offline-store.md](remote-offline-store.md)
 {% endcontent-ref %}

@@ -0,0 +1,102 @@
+# MongoDB offline store (contrib)
+
+## Description
+
+The MongoDB offline store provides support for reading [MongoDBSource](../data-sources/mongodb.md).
+* Entity dataframes can be provided as a Pandas dataframe. The offline store converts entity identifiers into serialized entity keys for efficient lookup against the `feature_history` collection.
+* Uses a single shared `feature_history` collection with a compound index for all FeatureViews, distinguished by a `feature_view` discriminator field.
+
+## Getting started
+
+In order to use this offline store, you'll need to run `pip install 'feast[mongodb]'`.
+
+## Example
+
+{% code title="feature_store.yaml" %}
+```yaml
+project: my_project
+registry: data/registry.db
+provider: local
+offline_store:
+  type: feast.infra.offline_stores.contrib.mongodb_offline_store.mongodb.MongoDBOfflineStore
+  connection_string: "mongodb+srv://user:pass@cluster.mongodb.net"
+  database: feast
+  collection: feature_history
+online_store:
+  type: mongodb
+  connection_string: "mongodb+srv://user:pass@cluster.mongodb.net"
+  database_name: feast_online_store
+```
+{% endcode %}
+
+The full set of configuration options is available in [MongoDBOfflineStoreConfig](https://rtd.feast.dev/en/master/#feast.infra.offline_stores.contrib.mongodb_offline_store.mongodb.MongoDBOfflineStoreConfig).
+
+## Data Model
+
+The offline store uses a single shared collection (by default `feature_history`) that stores append-only historical feature rows for all feature views. Each document represents one observation of one entity for one FeatureView at a specific event timestamp:
+
+```json
+{
+  "entity_id": "Binary(...)",
+  "feature_view": "driver_stats",
+  "event_timestamp": "ISODate(2024-01-15T12:00:00Z)",
+  "created_at": "ISODate(2024-01-15T12:01:00Z)",
+  "features": {
+    "conv_rate": 0.72,
+    "acc_rate": 0.91,
+    "avg_daily_trips": 14
+  }
+}
+```
+
+Key properties:
+
+* **Append-only**: Historical data is treated as immutable; corrections are written as new rows with newer `created_at` timestamps rather than in-place updates.
+* **Time-series friendly**: `event_timestamp` represents when the feature value was observed; `created_at` is used as a tie-breaker when multiple observations share the same event timestamp.
+* **Feature grouping by FeatureView**: `feature_view` identifies which FeatureView the row belongs to, so a single collection can host multiple FVs.
+
+A single compound index supports all major query patterns:
+
+```
+(entity_id ASC, feature_view ASC, event_timestamp DESC, created_at DESC)
+```
+
+This index enables efficient range scans over entities and feature views, while ensuring that the most recent observation per `(entity_id, feature_view)` is seen first during aggregation. The index is created lazily on first use and cached per connection string.
+
+## Key Optimizations
+
+* **K-collapse**: Multiple FeatureViews that share the same join keys are queried in a single aggregation using `feature_view: {$in: [...]}`, reducing round trips.
+* **Scoring vs. training paths**: When `entity_df` has unique entity IDs (scoring), server-side `$group $first` is used for efficient retrieval. When entity IDs repeat (training), `pd.merge_asof` provides correct point-in-time joins.
+* **Two-level chunking**: Outer `CHUNK_SIZE` (50,000 rows) limits the entity DataFrame slice; inner `MONGO_BATCH_SIZE` (10,000 entity IDs) limits `$in` array size per aggregation call.
+
+## Functionality Matrix
+
+The set of functionality supported by offline stores is described in detail [here](overview.md#functionality).
+Below is a matrix indicating which functionality is supported by the MongoDB offline store.
+
+|                                                                    | MongoDB |
+| :----------------------------------------------------------------- | :------ |
+| `get_historical_features` (point-in-time correct join)             | yes     |
+| `pull_latest_from_table_or_query` (retrieve latest feature values) | yes     |
+| `pull_all_from_table_or_query` (retrieve a saved dataset)          | yes     |
+| `offline_write_batch` (persist dataframes to offline store)        | yes     |
+| `write_logged_features` (persist logged features to offline store) | no      |
+
+Below is a matrix indicating which functionality is supported by `MongoDBRetrievalJob`.
+
+|                                                       | MongoDB |
+| ----------------------------------------------------- | ------- |
+| export to dataframe                                   | yes     |
+| export to arrow table                                 | yes     |
+| export to arrow batches                               | no      |
+| export to SQL                                         | no      |
+| export to data lake (S3, GCS, etc.)                   | no      |
+| export to data warehouse                              | no      |
+| export as Spark dataframe                             | no      |
+| local execution of Python-based on-demand transforms  | yes     |
+| remote execution of Python-based on-demand transforms | no      |
+| persist results in the offline store                  | yes     |
+| preview the query plan before execution               | no      |
+| read partitioned data                                 | no      |
+
+To compare this set of functionality against other offline stores, please see the full [functionality matrix](overview.md#functionality-matrix).