# MongoDB

Terra can store health data directly in your [MongoDB](https://www.mongodb.com/) database, with full payloads stored inline (no external URLs to fetch).

## Setup

You'll need a MongoDB instance reachable from Terra's servers. Terra supports both `mongodb://` and `mongodb+srv://` connection schemes.

{% hint style="warning" %}
**Security:** Restrict inbound connections to Terra's IP addresses listed on the [data destinations overview page](https://docs.tryterra.co/health-and-fitness-api/integration-setup/setting-up-data-destinations/..#ip-whitelisting). If using MongoDB Atlas, add these IPs to your [IP Access List](https://www.mongodb.com/docs/atlas/security/ip-access-list/). Use a strong, unique password and require TLS for connections.
{% endhint %}

Create a database user with read/write access to your target database. Enter the following in the Terra Dashboard when adding the MongoDB destination:

* **Host** (e.g. `cluster0.abc123.mongodb.net`)
* **Database name**
* **Username and password**
* **Connection scheme** (`mongodb` or `mongodb+srv`)

## Data Structure

Terra creates collections automatically and adds indices on first write.

#### Collections

| Collection     | Contents                                                 | Document ID             |
| -------------- | -------------------------------------------------------- | ----------------------- |
| `user_events`  | Auth events (auth success, deauth, access revoked, etc.) | `{user_id, event_time}` |
| `athlete`      | Athlete profile data                                     | `user_id`               |
| `activity`     | Activity data                                            | `{user_id, start_time}` |
| `body`         | Body metrics                                             | `{user_id, start_time}` |
| `daily`        | Daily summary data                                       | `{user_id, start_time}` |
| `sleep`        | Sleep data                                               | `{user_id, start_time}` |
| `nutrition`    | Nutrition data                                           | `{user_id, start_time}` |
| `menstruation` | Menstruation data                                        | `{user_id, start_time}` |

#### Indices

Terra creates the following indices automatically:

* **`user_events` and `athlete`:** `user.user_id` (ascending), `user.reference_id` (ascending)
* **Data collections** (activity, body, daily, sleep, nutrition, menstruation): `metadata.start_time` (descending), `metadata.end_time` (descending)

#### Document format

All documents include the full data payload inline — there are no external URLs to download. Each document includes a `user` object with the user's details.

**Data event example:**

```json
{
  "_id": { "user_id": "abc123", "start_time": "2026-03-12T06:00:00Z" },
  "user": { "user_id": "abc123", "reference_id": "your-ref", "provider": "FITBIT" },
  "metadata": { "start_time": "2026-03-12T06:00:00Z", "end_time": "2026-03-12T07:00:00Z" },
  "duration_seconds": 3600,
  "active_duration_seconds": 1800
}
```

Documents are upserted — if a document with the same ID already exists, it is replaced with the latest data.