---
title: 'Relationships and Scopes'
description: 'Reference and usage guidance for Relationships and Scopes.'
---

# Relationships and Scopes

Relationships connect entities. For a full guide to project-level scope configuration and Studio behavior, see [Scopes](/docs/schema/scopes).

## Single Relationship

Use `mode: 'single'` for one-to-one or many-to-one links.

```tsx
{
  name: 'company',
  label: 'Company',
  scope: 'relationship',
  dataType: 'string',
  inputType: 'relationship',
  defaultValue: '',
  relationship: {
    mode: 'single',
    entity: 'company',
    field: 'name',
  },
}
```

## Multiple Relationship

Use `mode: 'multiple'` for one-to-many or many-to-many links.

```tsx
{
  name: 'tags',
  label: 'Tags',
  scope: 'relationship',
  dataType: 'string',
  inputType: 'relationship',
  defaultValue: '',
  relationship: {
    mode: 'multiple',
    entity: 'tag',
    field: 'name',
  },
}
```

## Ordered Asset Relationship

Use a multiple relationship to `_asset` when a field needs a reusable ordered asset gallery. The order is stored on the relationship edge, so the same asset can appear in different galleries with different positions.

```tsx
{
  name: 'images',
  label: 'Images',
  scope: 'relationship',
  dataType: 'string',
  inputType: 'relationship',
  relationship: {
    mode: 'multiple',
    entity: '_asset',
    field: 'originalFilename',
  },
  options: {
    accept: 'image/*',
    comment: 'Product gallery images',
  },
}
```

Read ordered asset metadata through the generated connection field so each asset node is returned with its edge properties:

```graphql
query ProductImages {
  products {
    imagesConnection {
      edges {
        properties {
          sortOrder
        }
        node {
          _id
          originalFilename
          path
        }
      }
    }
  }
}
```

When connecting assets in mutations, write the order in the generated `edge` payload:

```graphql
mutation ConnectProductImage {
  updateProducts(
    where: { _id: { eq: "product-id" } }
    update: { images: [{ connect: [{ where: { node: { _id: { eq: "asset-id" } } }, edge: { sortOrder: 0 } }] }] }
  ) {
    products {
      _id
    }
  }
}
```

Persisting `sortOrder` does not guarantee the plain `images` list is returned sorted. Query the connection edge data and sort by `sortOrder` in the client unless your generated GraphQL schema exposes a suitable connection sort argument.

## Relationship Modeling Guidance

- Use entity names that exist in your schema.
- Use `_asset` only for multiple asset gallery fields.
- Set `field` to a stable, user-friendly target attribute (usually primary field).
- Prefer normalized relationship entities for reusable dimensions (tags, currencies, countries, suppliers).
- Use `single` when cardinality is strictly one.

## Scope Types

- `global`: same value in all scopes.
- `local`: value per scope (for example localized name or region-specific price).
- `relationship`: relationship-oriented field semantics.

## Scoped Defaults

In non-default scopes, local fields can inherit from the default scope. The form presents a **Use default value** toggle for scoped behavior.

Practical pattern:

- Keep global invariants in `global` scope (`sku`, `createdAt`).
- Keep market-specific values in `local` scope (`title`, `price`, `seoTitle`).
- Keep entity links in relationship fields.

## Avoid Common Mistakes

- Relationship input without `relationship` object.
- `relationship.entity` typo that points to a missing entity.
- Setting a business-critical multi-select as `single` mode.
- Using free-text fields where controlled relationships are required.


---

[View full sitemap](/docs/sitemap.md)