> ## Documentation Index
> Fetch the complete documentation index at: https://forest-chore-open-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Mongoose datasource

> Connect to MongoDB using Mongoose ODM with flexible data transformation strategies

The Mongoose datasource connects to MongoDB through Mongoose models, automatically importing your collections into Forest with support for nested objects, arrays, and relationships.

<Warning>
  Mongoose datasource is only available for Node.js. For Ruby, check the [Mongoid datasource](/get-started/connect/data-sources/mongoid).
</Warning>

## Basic usage

```javascript theme={null}
import { createAgent } from '@forestadmin/agent';
import { createMongooseDataSource } from '@forestadmin/datasource-mongoose';
import connection from './mongoose-models';

const agent = createAgent(options);

agent.addDataSource(
  createMongooseDataSource(connection, {
    flattenMode: 'none'
  })
);
```

## Example schema

Here's an example Mongoose schema with nested data:

```javascript theme={null}
import mongoose from 'mongoose';

const personSchema = new mongoose.Schema({
  name: String,
  age: Number,
  address: {
    streetName: String,
    city: String,
    country: String
  },
  bills: [{
    title: String,
    amount: Number,
    issueDate: Date,
    paidBy: [String]
  }]
});

const Person = mongoose.model('persons', personSchema);
```

## Flatten modes

The Mongoose datasource offers four transformation strategies:

### `flattenMode: 'auto'`

Arrays of objects and references are converted to independent collections. Other nested fields are moved to the root level.

```javascript theme={null}
createMongooseDataSource(connection, {
  flattenMode: 'auto'
})
```

### `flattenMode: 'none'`

No transformations are made. Forest collections use the exact same structure as your Mongoose models.

```javascript theme={null}
createMongooseDataSource(connection, {
  flattenMode: 'none'
})
```

### `flattenMode: 'manual'`

You are in full control of which virtual collections are created and which fields are moved to the root level.

```javascript theme={null}
createMongooseDataSource(connection, {
  flattenMode: 'manual',
  asModels: {
    'persons': ['bills']  // Convert bills array to separate collection
  },
  asFields: {
    'persons': ['address']  // Flatten address to root level
  }
})
```

### `flattenMode: 'legacy'`

Maintains backward compatibility with previous datasource versions.

```javascript theme={null}
createMongooseDataSource(connection, {
  flattenMode: 'legacy'
})
```

## Data navigation

When working with nested or related data, use specific separators:

* **Nested fields**: Use `@@@` to access nested properties
* **Related data**: Use `:` to navigate relationships

**Example**: `address:city@@@name` accesses the name field within city within the address relation.

## Virtual collections

In `auto` mode, the datasource may create virtual collections to represent relationships. If you use a collection whitelist, make sure to include these virtual collections in your configuration.

## Source code

This connector is open source. Browse the code or contribute on GitHub: [`@forestadmin/datasource-mongoose`](https://github.com/ForestAdmin/agent-nodejs/tree/main/packages/datasource-mongoose).