Cyclic queries

4 min

🚧 Important This feature is experimental and highly incompatible with many third-party libraries.

Description

Cyclic queries let you traverse self-referenced and cross-referenced CMS content with a single GraphQL request, so you can render deeply linked structures (such as nested content areas that point back to their parents) without issuing multiple round trips.

Optimizely Graph sits on top of Optimizely CMS and mostly reflects the data structure of CMS. Referenced content is common in the CMS structure, and Graph follows the CMS model. The declaration is straightforward, but it violates the GraphQL specification, so it is disabled by default.

To solve the self-referenced data problem, Graph introduced the recursive directiverecursive directive, which lets you declare self-references. For example, ContentA -> ContentB -> ContentC -> ContentA content. However, it does not solve the problem fully because the actual data structure also contains cross-references. For example, ContentA -> ContentB AND ContenB -> ContentA data.

As a complete solution, Graph lets you query with self-references or cross-references. For information, see the following examples.

🚧 Important Although your queries work on the GraphiQL page, they might be broken on your client app due to the limitations of your third-party libraries.

Self-referenced query example

query self {
  Content {
    items {
      ...IContent
    }
  }
}

fragment IContent on IContent {
  ... on StartPage {
    MainContentArea {
      ContentLink {
        Expanded {
          ...IContent
        }
      }
    }
  }
}

Cross-referenced query example

query cross {
  Content {
    items {
      ...IContent
    }
  }
}

fragment IContent on IContent {
  Name
  ... on StandardPage {
    ...StandardPage
  }
}

fragment StandardPage on StandardPage {
  Status
  MainContentArea {
    ContentLink {
      Expanded {
        ...IContent
      }
    }
  }
}

Limitations

Review these constraints before adopting cyclic queries so you can plan around the supported fields and tooling.

Graph does not support the _link and _children fields with cyclic fragments.

Only the items root field is supported.

If you use @graphql-codegen/cli, the typescript-operations plugin is not supported.