---
title: Common mistakes working with Optimizely Graph
slug: graph/docs/common-mistakes-working-with-graph
createdAt: 2026-10-05T11:45:47.000Z
---

This page describes the most common mistakes developers make when building sites with Optimizely Graph, why each one causes problems, and what to do instead. Most of these mistakes have the same root cause – queries that are larger than they need to be – which increases parse time, request latency, and cache churn.

For the prescriptive version of these recommendations, see [GraphQL best practices](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/graphql-best-practices).

## Which schema your examples use

Every mistake on this page applies to all CMS versions, but the query shapes differ. CMS 13 and CMS (SaaS) expose the native Graph schema. CMS 12 exposes the synchronization client schema.

| Concept                 | Native Graph schema (CMS 13, CMS SaaS)                                    | Synchronization client schema (CMS 12)                             |
| ----------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| System fields           | `_metadata { displayName types url { default } }`                         | Top-level `Name`, `RelativePath`, `ContentType`, `Status`          |
| Filter by URL           | `_metadata: { url: { default: { eq: $url } } }`                           | `RelativePath: { eq: $path }`                                      |
| Content type of an item | `_metadata { types }`                                                     | `__typename`, `ContentType`                                        |
| Content area items      | Block fields, `_metadata`, and `_json` directly on the content-area field | Wrapper items – reach the block through `ContentLink { Expanded }` |
| Register an interface   | `[ContentType]` attribute                                                 | Conventions API `IncludeInterface<T>()`                            |

Each section leads with the native schema and gives the CMS 12 equivalent where the shape differs.

:::hint{type="info"}
**Note**
Do not mix fields from the two schemas in the same query. `RelativePath` and `_metadata` never appear on the same document. To confirm which schema your instance exposes, see [Explore your schema](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/explore-your-schema) for CMS 12 and [Explore your schema (SaaS)](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/explore-your-schema-saas) for CMS (SaaS).
:::

## Building one large query for all content types

**The mistake**

A common pattern is to fetch a content item by URL using the generic `_Content` type and then add an inline fragment (`... on Type`) for every content type the URL might resolve to.

```graphql
# Anti-pattern – one query to rule them all
query GetContentByUrl($locale: Locales, $url: String) {
  _Content(
    locale: [NEUTRAL, $locale]
    where: { _metadata: { url: { default: { eq: $url } } } }
  ) {
    item {
      _metadata {
        displayName
      }
      ... on StartPage {
        HeroTitle
      }
      ... on ArticlePage {
        TeaserText
        MainBody {
          html
        }
      }
      ... on NewsPage {
        PublishDate
      }
      # ... fragments for many more content types
    }
  }
}
```

**Why it is a problem**

The more content types and inline fragments a query contains, the larger it becomes and the longer Optimizely Graph takes to parse it and build the correct underlying queries. A single query that tries to cover every content type is slow to execute and hard to maintain.

**Do this instead**

Keep queries small by querying the specific type you need. When you query `ArticlePage` directly, you can request exactly the fields that type exposes and the query stays small.

```graphql
# Query the specific type you need
query GetArticlePage($locale: Locales, $url: String) {
  ArticlePage(
    locale: [NEUTRAL, $locale]
    where: { _metadata: { url: { default: { eq: $url } } } }
  ) {
    item {
      _metadata {
        displayName
      }
      MainBody {
        html
      }
    }
  }
}
```

On CMS 12, filter on `RelativePath` and select top-level fields:

```graphql
# CMS 12 equivalent
query GetArticleByPath($path: String!) {
  ArticlePage(where: { RelativePath: { eq: $path } }) {
    item {
      Name
      TeaserText
      MainBody
    }
  }
}
```

## Fetching full content just to determine its type

**The mistake**

If you do not know which content type a URL resolves to, it is tempting to fetch everything (the large query above) and let the front end work out the type from the result.

**Why it is a problem**

You pay the cost of the oversized query on every request, only to use a fraction of the data.

**Do this instead**

Determine the type cheaply, then run a small, type-specific query. There are two common approaches:

- **Query only the type metadata and cache a URL-to-type map.** Ask Graph for just the content type of a URL, cache the result, and use it to route to the correct type-specific query. On subsequent requests you already know the type and can skip this lookup.

```graphql
  # Look up only the type for a URL, then cache it
  query GetContentType($url: String) {
    _Content(
      where: { _metadata: { url: { default: { eq: $url } } } }
    ) {
      item {
        _metadata {
          types
          url {
            default
          }
        }
      }
    }
  }
  
```

`_metadata.types` returns every type the item belongs to, including its base types. On CMS 12, query `__typename` and `ContentType` instead:

```graphql
  # CMS 12 equivalent
  query GetTypeForPath($path: String!) {
    _Content(where: { RelativePath: { eq: $path } }) {
      item {
        __typename
        ContentType
        RelativePath
      }
    }
  }
  
```

- **Own the routing in the front end.** If you control the routing layer (for example, the Next.js router in a React application), you already know which query to run for a given URL because you know exactly what to render, so no type-lookup query is needed.

:::hint{type="warning"}
**Important**
Links inside an `XhtmlString` property are rendered with URLs that follow the CMS content hierarchy, not your front-end routing rules. The CMS cannot yet accept third-party routing rules, so those links may not match the URLs your router expects. Until it can, the URL-to-type map described above is the more reliable option.
:::

## Overusing inline fragments for content areas

**The mistake**

Even when you query a specific type, a content area lets editors add any block (or page) type. To read those blocks you may fall back to an inline fragment for each possible block type, which makes the query large again.

```graphql
# Anti-pattern – an inline fragment per block type in a content area
query GetArticlePage($locale: Locales, $url: String) {
  ArticlePage(
    locale: [NEUTRAL, $locale]
    where: { _metadata: { url: { default: { eq: $url } } } }
  ) {
    item {
      _metadata {
        displayName
      }
      MainContentArea {
        ... on TeaserBlock {
          Heading
          Text
        }
        ... on ImageBlock {
          Url
        }
        # ... an inline fragment for every block type
      }
    }
  }
}
```

:::hint{type="info"}
**Note**
On CMS 12, a content area does not return the blocks themselves. It returns wrapper items that expose `ContentLink`, `DisplayOption`, and `Tag`, so every selection on a block – including the inline fragments above and the `_json` field below – belongs inside `ContentLink { Expanded { … } }`.
:::

**Why it is a problem**

Content areas can hold many different block types, and blocks can be nested inside other blocks. Enumerating every type with inline fragments recreates the oversized-query problem you avoided by querying a specific type.

**Do this instead**

Use the `_json` field to return each block – including deeply nested content areas – as fully resolved JSON, then map the results to your strongly typed blocks in the front end. Your schema still describes every block type, so you keep type safety on the client.

```graphql
# Return the content area as JSON in one field
query GetArticlePage($locale: Locales, $url: String) {
  ArticlePage(
    locale: [NEUTRAL, $locale]
    where: { _metadata: { url: { default: { eq: $url } } } }
  ) {
    item {
      _metadata {
        displayName
      }
      MainBody {
        html
      }
      MainContentArea {
        _json
      }
    }
  }
}
```

On CMS 12, request `_json` on the expanded reference:

```graphql
# CMS 12 equivalent
query GetArticle($path: String!) {
  ArticlePage(where: { RelativePath: { eq: $path } }) {
    item {
      Name
      MainBody
      MainContentArea {
        ContentLink {
          Expanded {
            _json
          }
        }
      }
    }
  }
}
```

If you cannot query a specific type at all and keep falling back to inline fragments, you can request `_json` directly on `item` to return the whole content item as JSON. This is a workaround rather than a recommendation – it makes Graph behave more like a REST API and gives up the field-level control that keeps queries small – but it is preferable to enumerating every type.

:::hint{type="info"}
**Note**
The `_json` field is locked behind a feature flag and requires an API key with read access to the target content. If `_json` does not display in your GraphQL schema, contact your system administrator to enable the feature flag.
:::

For more detail, see [\_json field](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/json-field) and [Inline fragments for content schema](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/inline-fragments-for-content-schema).

## Using `items` when you expect a single result

**The mistake**

Using `items` for queries that can only return one result – for example, a lookup by URL or another unique identifier.

**Why it is a problem**

`item` and `items` use different caching mechanisms. When you use `item`, Graph assumes exactly one result matches the criteria in your `where` clause and uses that returned item as the cache key, so the cached result is purged only when that specific item is published again – it lives in the cache for a very long time. When you use `items`, Graph cannot know whether a newly published or changed content item belongs in the result, so it falls back to a much simpler mechanism and purges the cached result of every query containing `items` as soon as any content is published. As a result, query caches for `items` live only very briefly.

**Do this instead**

Use `item` whenever you expect a single result.

```graphql
# Use item for single results – better cache hit ratio
query GetArticlePage($locale: Locales, $url: String) {
  ArticlePage(
    locale: [NEUTRAL, $locale]
    where: { _metadata: { url: { default: { eq: $url } } } }
  ) {
    item {
      _metadata {
        displayName
      }
      MainBody {
        html
      }
      MainContentArea {
        _json
      }
    }
  }
}
```

For more detail, see [Item queries for single entities](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/item-queries-for-single-entities).

## Repeating the same fragment across many blocks

**The mistake**

When many block types share a property – for example, a reference to a Digital Asset Management (DAM) item that needs special join handling – repeating the same field selection for that property inside a separate inline fragment for every block type that has it.

```graphql
# Anti-pattern – repeat the reference handling for every block type
query GetArticlePage($locale: Locales, $url: String) {
  ArticlePage(
    locale: [NEUTRAL, $locale]
    where: { _metadata: { url: { default: { eq: $url } } } }
  ) {
    item {
      MainContentArea {
        ... on TeaserBlock {
          Asset {
            Name
            Url
          }
        }
        ... on HeroBlock {
          Asset {
            Name
            Url
          }
        }
        # ... repeated for every block that references a DAM item
      }
    }
  }
}
```

**Why it is a problem**

If 300 of your 500 blocks reference a DAM item, you end up repeating the same reference handling 300 times and the query becomes large again.

**Do this instead**

Define a shared interface for the property (for example, all blocks that contain a DAM reference) and implement it on every relevant block type. You then spread the interface once and the reference handling applies to all implementing types.

Graph does not add interfaces to your schema automatically. Mark the interface with the `[ContentType]` attribute:

```csharp
[ContentType]
public interface IDamReference : IContentData
{
    ContentReference Asset { get; set; }
}
```

On CMS 12, register the interface with the [Conventions API](https://docs.developers.optimizely.com/content-management-system/v12.0.0-cms/docs/conventions-api) in an initializable module instead:

```csharp
conventionRepo.IncludeInterface<IDamReference>();
```

Either way, run the Optimizely Graph synchronization job afterwards. Neither the attribute nor a convention change resyncs on its own, and until your content types are synced again, `... on IDamReference` refers to a type that does not exist in your schema.

You can then spread the interface once:

```graphql
# Spread a shared interface once
query GetArticlePage($locale: Locales, $url: String) {
  ArticlePage(
    locale: [NEUTRAL, $locale]
    where: { _metadata: { url: { default: { eq: $url } } } }
  ) {
    item {
      MainContentArea {
        _metadata {
          key
        }
        ... on IDamReference {
          Asset {
            Name
            Url
          }
        }
        _json
      }
    }
  }
}
```

On CMS 12, spread the interface inside the expanded reference:

```graphql
# CMS 12 equivalent
query GetArticle($path: String!) {
  ArticlePage(where: { RelativePath: { eq: $path } }) {
    item {
      MainContentArea {
        ContentLink {
          Expanded {
            ... on IDamReference {
              Asset {
                Name
                Url
              }
            }
          }
        }
      }
    }
  }
}
```

:::hint{type="info"}
**Note**
Unlike abstract types, interface types cannot be cast to other types in the inheritance chain. If you need that, use an abstract base type instead.
:::

## C# SDK mistakes

Optimizely provides two .NET clients for Graph, and they do not share an API. Check which one your project uses before copying the examples below.

|                 | C# SDK for CMS 13            | Optimizely Graph .NET Source SDK      |
| --------------- | ---------------------------- | ------------------------------------- |
| Used by         | CMS 13 and CMS (SaaS)        | CMS 12                                |
| Package         | `Optimizely.Graph.Cms.Query` | `Optimizely.ContentGraph.Cms.NetCore` |
| Entry point     | `IGraphContentClient`        | `queryBuilder`                        |
| Runtime filters | `BuildFilter<T>()`           | `BooleanFilter.AndFilter<T>()`        |

See [Optimizely Graph .NET Source SDK](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/optimizely-graph-net-source-sdk) for the CMS 12 client.

### Not using `GetAsContentAsync` when you need resolved content

**The mistake**

Working with raw Graph results when you actually want fully resolved `IContent` objects. This applies to the C# SDK for CMS 13.

**Why it is a problem**

Raw results require extra mapping before you can use them as CMS content, which adds boilerplate and room for error.

**Do this instead**

Use `GetAsContentAsync` when possible – it returns fully resolved `IContent` objects that you can use directly.

```csharp
// Raw Graph results – you map them yourself
var results = await _graphClient
    .QueryContent<ISitePageData>()
    .SearchFor("optimizely graph")
        .UsingFullText()
    .Fields<SitePageViewModel>(x => x.Name, x => x.TeaserText)
    .GetAsync();

// Fully resolved IContent objects
var content = await _graphClient
    .QueryContent<ISitePageData>()
    .SearchFor("optimizely graph")
        .UsingFullText()
    .GetAsContentAsync();
```

### Hardcoding filters that vary at runtime

**The mistake**

Writing fixed inline `.Where(...)` conditions for filters whose values or combinations are only known at runtime.

**Why it is a problem**

Fixed conditions cannot express filters that change based on user input or application state, which leads to duplicated query-building code or invalid queries.

**Do this instead**

Use inline `.Where(...)` for fixed conditions, and build runtime-variable filters with a filter builder so you can combine conditions dynamically.

In the C# SDK for CMS 13, use `BuildFilter<T>`:

```csharp
var filters = _graphClient.BuildFilter<ArticlePage>()
    .And(x => x.Name.FilterStartsWith("Alloy"));

if (publishedBefore.HasValue)
{
    filters = filters.And(x => x.StartPublish.LessThan(publishedBefore.Value));
}

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .Where(filters)
    .GetAsContentAsync();
```

In the .NET Source SDK, use `BooleanFilter` with the `AndFilter`, `OrFilter`, and `NotFilter` classes:

```csharp
var andFilter = BooleanFilter
  .AndFilter<ArticlePage>()
  .And(x => x.Name.Eq("Your page name"))
  .And(x => x.Status.Eq("Published"));

var query = queryBuilder
  .ForType<ArticlePage>()
  .Fields(x => x.Name, x => x.MetaDescription)
  .Where(andFilter)
  .ToQuery()
  .BuildQueries();
```

For more detail, see [Where filter](https://docs.developers.optimizely.com/platform-optimizely/v1.4.1-optimizely-graph/docs/where-filter).
