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

# Single-record relationships

Relationships that point to a single record are displayed in your back-office as links.

Once configured, they appear in charts, filters, scopes, and segments.

<Info>
  For performance reasons when sorting a Table View on customizer-defined relationships, Forest will always sort on the primary key of the related collection.
</Info>

## Many-to-One relationships

Many-to-One relationships are by far the most common type of relationship: many records from a Collection are attached to another Collection record.

Think about countries and towns: a town belongs to a single country, but each country can have multiple towns.

<CodeGroup>
  ```javascript Node.js / Cloud theme={null}
  agent.customizeCollection('towns', collection =>
    collection.addManyToOneRelation('country', 'countries', {
      foreignKey: 'country_id',
      foreignKeyTarget: 'id', // Optional (uses `country` primary key by default)
    }),
  );
  ```

  ```ruby Ruby theme={null}
  ForestAdmin.customize do
    customize_collection('towns') do |collection|
      collection.add_many_to_one_relation('country', 'countries',
        foreign_key: 'country_id',
        foreign_key_target: 'id' # Optional (uses `country` primary key by default)
      )
    end
  end
  ```
</CodeGroup>

## One-to-One relationships

In a one-to-one relationship, there is a one-to-one mapping between records in 2 Collections. The relationship can be unset for some records, but no record from the first Collection can be linked to more than one record in the other Collection.

Think about cities and mayors: A city can have at most one mayor, and each mayor belongs to a single city.

<Warning>
  Take note that the inverse of a `one-to-one` is a `many-to-one`.

  This may seem counter-intuitive: the side of the relationship which should be configured as `many-to-one` is the one that carries the foreign key.
</Warning>

<CodeGroup>
  ```javascript Node.js / Cloud theme={null}
  // Configure one side of the relationship ...
  agent.customizeCollection('mayors', collection => {
    collection.addOneToOneRelation('city', 'cities', {
      originKey: 'mayor_id',
      originKeyTarget: 'id', // Optional (uses `mayors` primary key by default)
    });
  });

  // ... and the other one.
  agent.customizeCollection('cities', collection => {
    // ⚠️ Not 'OneToOne'
    collection.addManyToOneRelation('mayor', 'mayors', {
      foreignKey: 'mayor_id',
      foreignKeyTarget: 'id', // Optional (uses `mayors` primary key by default)
    });
  });
  ```

  ```ruby Ruby theme={null}
  ForestAdmin.customize do
    # Configure one side of the relationship ...
    customize_collection('mayors') do |collection|
      collection.add_one_to_one_relation('city', 'cities',
        origin_key: 'mayor_id',
        origin_key_target: 'id' # Optional (uses `mayors` primary key by default)
      )
    end

    # ... and the other one.
    customize_collection('cities') do |collection|
      # ⚠️ Not 'one_to_one'
      collection.add_many_to_one_relation('mayor', 'mayors',
        foreign_key: 'mayor_id',
        foreign_key_target: 'id' # Optional (uses `mayors` primary key by default)
      )
    end
  end
  ```
</CodeGroup>