---
title: Reference properties
slug: graph/docs/reference-properties
createdAt: 2026-10-05T11:45:47.000Z
---

A reference property points from one content item to another. Optimizely Graph resolves the reference at query time. One query returns the item you requested and the content it references, so you skip the second lookup.

Use a reference property when a property in your content model points at another item. Examples include a page's hero image, a start page's featured products, and a category's parent category. Use [joins with linking](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/joins-with-linking) instead to discover relationships that your content model does not express as pointers. For a side-by-side comparison, see [Choose between a reference and a link](https://docs.optimizely.com/graph/docs/reference-properties#choose-between-a-reference-and-a-link).

Working with a reference property takes three steps:

- Define the `ref` object on the property.
- Send the target identifier in the content data.
- Select the property in a query.

## Prerequisites

Before you define a reference property, make sure you have the following:

- A content source registered with Optimizely Graph.
- A content types definition that you control.
- Credentials for the sync API.

## Define a reference property

One `ref` definition makes the property resolvable in every query against the content type. Add a `ref` object to a property in your [content types definition](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/sync-content-types-for-external-data). The `ref` object tells Optimizely Graph what to resolve the stored value into.

```json
{
  "contentTypes": {
    "StartPage": {
      "properties": {
        "ProductSingleRef": {
          "type": "IProduct",
          "ref": { "type": "Product", "id": "_id" }
        },
        "ProductMultiRef": {
          "type": "[IProduct]",
          "ref": { "type": "Product", "id": "_id" }
        }
      }
    }
  }
}
```

The `ref` object accepts two optional keys.

| Key        | Required | Description                                                                                                                                                                                                       |
| ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref.type` | No       | The content type to resolve the reference into. Defaults to the property's own `type`. If that type is an interface (such as `IProduct`), Optimizely Graph resolves it to the matching concrete type (`Product`). |
| `ref.id`   | No       | The property on the referenced content type that holds the identifier. Defaults to `_id`, the identifier Optimizely Graph assigns to every indexed document.                                                      |

The property's own `type` controls the shape of the result:

- `"type": "IProduct"` – a single reference. The query returns one object.
- `"type": "[IProduct]"` – multiple references. The query returns a list of objects.

Omit `ref.type` to fall back to the declared type. The following example resolves against `Data`, the root type that every content type derives from. It matches on a custom identifier property named `Id` instead of `_id`:

```json
"ProductCustomRef": {
  "type": "[IData]",
  "ref": { "id": "Id" }
}
```

:::hint{type="info"}
**Note**
A reference that points at nothing is not an error. It returns an empty object (`{}`) for a single reference, or an empty list (`[]`) for multiple references.
:::

## Send reference values in content data

Optimizely Graph matches the identifier you send against the target item, so the two documents stay independent in the index. The value you send for a reference property is the identifier of the target item, not a nested object. Send a string for a single reference and an array of strings for multiple references. Each value must match the value of the `ref.id` property on the item you are pointing at.

Given the previous `StartPage` definition, [sync the content data](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/sync-content-data) like this:

```json
{
  "ContentType": ["Content", "StartPage"],
  "__typename": "StartPage",
  "Name___searchable": "StartPage title",
  "ProductSingleRef": "shopify_item_3",
  "ProductMultiRef": ["shopify_item_2", "shopify_item_4", "shopify_item_1"]
}
```

The referenced products are separate documents, indexed on their own:

```json
{
  "ContentType": ["ShopifyProduct", "Product", "Catalog"],
  "__typename": "ShopifyProduct",
  "_id": "shopify_item_3",
  "Name___searchable": "Shopify Product 3",
  "Color": "Green",
  "Size": 38,
  "Quantity": 5
}
```

You do not have to index the referenced item before the item that points at it. Optimizely Graph resolves references at query time, so the order in which you sync the two items does not matter.

The referenced item lives in any source. A source is a registered origin of content, such as a CMS instance or an external system. Optimizely Graph resolves cross-source references automatically. No extra configuration applies, and the reference field takes no `source` argument.

## Query a reference

One query returns the parent item and its referenced content together, so the client makes a single round trip. Select the reference property as if it were a nested content type. Because the declared type is usually an interface, use an [inline fragment](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/inline-fragments-for-content-schema) to select the fields of the concrete type.

```graphql
{
  StartPage {
    items {
      Name
      ProductSingleRef {
        ... on ShopifyProduct {
          Name
          Color
          Size
        }
      }
      ProductMultiRef {
        ... on ShopifyProduct {
          Name
          Color
          Size
        }
      }
    }
  }
}
```

The single reference returns an object and the multiple reference returns a list, in the order you sent the identifiers:

```json
{
  "data": {
    "StartPage": {
      "items": [
        {
          "Name": "StartPage title",
          "ProductSingleRef": {
            "Name": "Shopify Product 3",
            "Color": "Green",
            "Size": 38
          },
          "ProductMultiRef": [
            { "Name": "Shopify Product 2", "Color": "Blue", "Size": 36 },
            { "Name": "Shopify Product 4", "Color": "Yellow", "Size": 40 },
            { "Name": "Shopify Product 1", "Color": "Red", "Size": 42 }
          ]
        }
      ]
    }
  }
}
```

A reference property carries a `reference` table in its field description showing the resolved `type` and `id`. Open the **Docs** tab on the [GraphiQL page](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/get-started-with-the-graphql-api#access-the-interactive-graphiql-page) and select the property. The table confirms the target type and the matching property, so you do not open the content types definition.

![Screenshot of the GraphiQL Docs tab for the ProductMultiRef property where the reference table shows type Product and id \_id](../../assets/graphiql-reference-table.png)

The example declares `ProductMultiRef` as `[IProduct]`. The table confirms that Optimizely Graph resolves it into `Product` by matching on `_id`.

## `ContentReference` property type

Optimizely CMS (SaaS) exposes references through a shared property type, so one definition serves every content type. Instead of putting `ref` directly on the content type property, CMS (SaaS) uses a shared property type named `ContentReference`. That type wraps the reference in an object alongside other data about the target:

```json
{
  "propertyTypes": {
    "ContentReference": {
      "properties": {
        "key":  { "type": "String", "index": true },
        "url":  { "type": "ContentUrl", "index": true },
        "item": { "type": "IData", "ref": { "type": "Data", "id": "_id" } }
      }
    }
  }
}
```

The `ref` sits on the inner `item` property. `key` and `url` are ordinary indexed properties that you read without resolving anything. `item` holds the reference that Optimizely Graph resolves into the referenced content.

Content types then use `ContentReference` as a normal property type, either singly or as a list:

```json
"StartPage": {
  "properties": {
    "Image":     { "type": "ContentReference",   "index": true },
    "ImageList": { "type": "[ContentReference]", "index": true }
  }
}
```

In the content data, each `ContentReference` is an object. The `item` property carries the identifier of the target:

```json
{
  "Image": {
    "key": "Image_1",
    "item": "Image_1",
    "__typename": "ContentReference"
  },
  "ImageList": [
    { "key": "Image_2", "item": "Image_2", "__typename": "ContentReference" },
    { "key": "Image_3", "item": "Image_3", "__typename": "ContentReference" }
  ]
}
```

Query `key` and `url` directly, and go through `item` to reach the referenced content. Note that `ImageList` is a list of references, but each entry still exposes a single `item`:

```graphql
{
  StartPage {
    items {
      Image {
        key
        item {
          _id
          ... on cmp_Asset {
            Name
            Url
          }
        }
      }
      ImageList {
        key
        item {
          _id
          ... on cmp_Asset {
            Name
            Url
          }
        }
      }
    }
  }
}
```

Selecting only `key` does not resolve anything, so it costs nothing beyond the parent query. Add `item` only when you need fields from the referenced content.

## Limit the number of resolved items

Raise the resolution cap when a query returns more parent items than the default lookup covers. Optimizely Graph resolves the references for every item in the parent result set with a single batched lookup. For single references, that lookup returns at most 10 items by default. A query that returns more than 10 parent items leaves the extra references unresolved.

Change the cap with the `maxSubRequestSize` variable, up to a maximum of 100. Send it in the `variables` payload of the GraphQL request. Do not declare it in the operation. Optimizely Graph reads it from the request variables, and GraphQL rejects a declared variable that the operation never uses.

```json
{
  "query": "{ StartPage { items { ProductSingleRef { ... on ShopifyProduct { Name } } } } }",
  "variables": { "maxSubRequestSize": 50 }
}
```

The cap behaves as follows at its boundaries:

- A value above 100 returns the error `maxSubRequestSize must be less than or equal to 100`.
- A value below one resolves nothing.
- The cap does not apply to multiple references. Optimizely Graph ignores `maxSubRequestSize` for a list-typed reference property, and returns no error when you set it above 100.

## Cache invalidation for resolved references

Optimizely Graph tags a cached response with the identifier of every published item the query resolved. That set covers the referenced items and the items you queried directly. Editing a referenced item invalidates the cached response of any query that pointed at it. Stale content never reaches the reader.

Cache tagging applies only to published items. Unpublished referenced content contributes no cache tag.

## Reference property limitations

Optimizely Graph resolves reference properties in a separate lookup against the referenced content. The following restrictions follow from that design.

- **Filter, sort, and facet arguments** – Optimizely Graph does not add the property that carries the `ref` to `where`, `orderBy`, `facets`, or `autocomplete`. Filter on the referenced content type in its own query, or model the value as an ordinary property. `key` and `url` on the `ContentReference` property type stay filterable.
- **Highlight** – A reference property never highlights, even when you mark it as `searchable`.
- **Nested references** – A reference property inside a resolved reference returns an error. References resolve one level deep.
- `_link` inside a reference – Combine joins and references at the same level instead of nesting one inside the other.
- **Query cost** – Optimizely Graph costs a reference like a link. A query that resolves several references costs more than the same query without them. Check the `costSummary` in the response `extensions` for the breakdown.

## Choose between a reference and a link

Both features connect content items, but they solve different problems.

| Characteristic | Reference property                                                               | `_link`                                                                                    |
| -------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Modeled as     | A property on the content type that holds a pointer                              | A named link type defined once at the root of the source                                   |
| Direction      | From the item that stores the identifier to the item it names                    | Either direction, wherever the `from` and `to` values match                                |
| Result shape   | Nested under the property name                                                   | Nested under `_link`, grouped by content type                                              |
| Depth          | One level                                                                        | Up to three levels                                                                         |
| Best for       | Deliberate pointers in your content model, such as an image or a related product | Discovering relationships across content types by matching values, such as tags or authors |
