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

# Overview

When relationships are defined during the customization step, Forest Collections act as if the 2 Collections were natively linked at the data source level.

You may have noticed that relationships within a data source are configured out of the box, so you won't need to define those.

However, you may want to create additional intra and cross data source relationships to:

* help users navigate within your back-office
* create charts that use data from multiple data sources
* let users filter, use scopes, or segment with conditions that cross data source boundaries

## Minimal example

<CodeGroup>
  ```javascript Node.js / Cloud theme={null}
  agent.customizeCollection('towns', collection =>
    collection
      // Towns belong to 1 country
      .addManyToOneRelation('country', 'countries', { foreignKey: 'country_id' })

      // Towns have 1 mayor
      .addOneToOneRelation('mayor', 'mayors', { originKey: 'town_id' })

      // Towns have multiple inhabitants
      .addOneToManyRelation('inhabitants', 'people', { originKey: 'town_id' })

      // Towns electricity is supplied by power plants that are shared with other towns
      .addManyToManyRelation('energyProviders', 'powerPlants', 'utilityContracts', {
        originKey: 'town_id',
        foreignKey: 'power_plant_id',
      })

      // Towns have a list of honorary citizen that is retrievable through a public API
      .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;
        },
      }),
  );
  ```

  ```ruby Ruby theme={null}
  ForestAdmin.customize do
    customize_collection('towns') do |collection|
      collection
        # Towns belong to 1 country
        .add_many_to_one_relation('country', 'countries', foreign_key: 'country_id')

        # Towns have 1 mayor
        .add_one_to_one_relation('mayor', 'mayors', origin_key: 'town_id')

        # Towns have multiple inhabitants
        .add_one_to_many_relation('inhabitants', 'people', origin_key: 'town_id')

        # Towns electricity is supplied by power plants that are shared with other towns
        .add_many_to_many_relation('energyProviders', 'powerPlants', 'utilityContracts',
          origin_key: 'town_id',
          foreign_key: 'power_plant_id'
        )

        # Towns have a list of honorary citizen that is retrievable through a public API
        .add_external_relation('honoraryCitizen',
          schema: { 'firstName' => 'String', 'lastName' => 'String' },
          list_records: ->(record) {
            response = Faraday.get("https://api.mytown.com/cities/#{record['id']}/honorary-citizen")
            JSON.parse(response.body)
          }
        )
    end
  end
  ```
</CodeGroup>