# Relationships

{% hint style="success" %}
This is the official documentation of Forest Admin Cloud.
{% endhint %}

In Forest Admin, relationships link Collections, structuring data into a interconnected architecture beyond simple presentations.

By default, relationships are automatically discovered and configured from the connected data sources, eliminating the need for manual definition.

However, you can also create custom relationships between two different collections, from possibly separate data sources. This lets Forest Admin handle these links as if they were built-in.

{% hint style="info" %}
The following sections assume that you have correctly followed all the steps in the [Code Customization Getting Started](/cloud/code-customization/getting-started.md) guide.
{% endhint %}

***

To make the code easier to read, all the code snippets below should be wrapped in the following code. Ensure you update the collection name as needed.

```typescript
import type { Agent } from '@forestadmin/forest-cloud';
import { Schema } from '../typings';

export default function customizeAgent(agent: Agent<Schema>) {
  agent.customizeCollection('towns', collection =>
    // Insert the code snippet here.
  );
}
```

***

### Adding a ManyToOne relationship

To create a `ManyToOne` relationship, consider the scenario where each town belongs to one country. The relationships can be defined as follows:

```typescript
collection.addManyToOneRelation('country', 'countries', { foreignKey: 'country_id' });
```

### Adding a OneToMany relationship

To create a `OneToMany` relationship, think about how a town can have multiple residents. You can set up this relationship as follows:

```typescript
collection.addOneToManyRelation('residents', 'people', { originKey: 'town_id' });
```

### Adding a ManyToMany collection

To create a `ManyToMany` relationship, let's imagine a town's electricity comes from shared power plants, servicing multiple towns.

```typescript
collection.addManyToManyRelation('energyProviders', 'powerPlants', 'utilityContracts', {
  originKey: 'town_id',
  foreignKey: 'power_plant_id',
});
```

### Adding an External Relationship fed by an API

In this example, we demonstrate using an external API to retrieve data about a town with several honorary citizens. Start by defining the JSON schema returned by the API. Then use `listRecords()` to implement how to fetch the data.

```typescript
collection.addExternalRelation('honoraryCitizen', {
  schema: { firstName: 'String', lastName: 'String' },
  listRecords: async ({ id }) => {
    const response = await axios.get(`https://api.mytown.com/cities/${id}/honorary-citizen`);
    return response.body;
  },
});
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.forestadmin.com/cloud/code-customization/relationships.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.