---
title: Visual Builder queries
slug: cms-saas/docs/visual-builder-queries-saas
docTags: 
createdAt: 2026-07-30T20:18:07.000Z
---

Visual Builder is a way of composing content and layout. See [Visual Builder](docId\:fw42GyhbrcH5AIDDT18VZ) for information. When an experience is indexed in Optimizely, the layout and the data parts are merged into a composition model.

## Graph schema

A composition is a structure of `CompositionNode` instances.

### CompositionNode

`CompositionNode` is the base type for nodes in the composition structure. The [Optimizely Graph](docId\:aM0WpNsNXe_n26IhkX5sG) schema for `CompositionNode` is defined as:

| Field                | Type                         | Description                                                                                                                                                       |
| -------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`               | String                       | The node content type, if the node has a corresponding content type. Example types: `BlankExperience` , `BlankSection`, `ImageElement`, `TextElement`.            |
| `nodeType`           | String                       | The node type. Available types: `experience` , `section`, `row`, `column`, and `component`.                                                                       |
| `layoutType`         | String                       | The layout type. Available types: `outline` and `grid`.                                                                                                           |
| `displayName`        | String                       | The name of the node.                                                                                                                                             |
| `key`                | String                       | A unique key for the node within the composition. Typically used for marking up live preview attributes. See [Enable live preview](docId\:UCf2VD_0Jqh32jliPbPzm). |
| `displayTemplateKey` | String                       | Optional key specifying which Display Template is used by the node (if any).                                                                                      |
| `displaySettings`    | \[CompositionDisplaySetting] | An array of display settings that are defined for the node.                                                                                                       |

### CompositionStructureNode

A subtype of `CompositionNode` that represents a structural node in the composition structure. The Optimizely Graph schema for `CompositionStructureNode` is defined as the following:

| Field       | Type               | Description                                                                                                  |
| ----------- | ------------------ | ------------------------------------------------------------------------------------------------------------ |
| `nodes`     | \[CompositionNode] | The children nodes to the current node.                                                                      |
| `component` | \_IComponent       | The associated data for section nodes. For structure nodes like `row` and `column`, the `component` is null. |

### CompositionComponentNode

A subtype to `CompositionNode` that contains a VisualBuilder component. The Optimizely Graph schema for `CompositionComponentNode` is defined as the following:

| Field       | Type         | Description                                                                                                                               |
| ----------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `component` | \_IComponent | The component instance used. It can be cast to a specific component based on content type, like `ImageElement`, `TextElement`, and so on. |

### CompositionDisplaySetting

Represents a display setting value for a composition node. The Optimizely Graph schema for `CompositionDisplaySetting` is defined as the following:

| Field   | Type   | Description                                                                                            |
| ------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `key`   | String | The key for the display setting. Should match a key defined in the corresponding Display Template.     |
| `value` | String | The value for the display setting. Available values are defined in the corresponding Display Template. |

## Explicit query

Content types based on `Experience` and `Section` have a property `composition` that contains the merged structure from the defined layout and data for the Visual Builder output. An experience composition contains a list of sections. A section is grid-based and consists of rows where each row has columns, and each column has components. Given that structural knowledge, a query to get a composition can be specified as the following:

```graphql
query ExplicitExperienceQuery {
  _Experience {
    items {
      composition {
        displayName
        displaySettings {
          key
          value
        }
        displayTemplateKey
        key
        nodeType
        nodes {
          displayName
          displaySettings {
            key
            value
          }
          displayTemplateKey
          key
          nodeType
          type
          ... on CompositionStructureNode {
            displayName
            displayTemplateKey
            key
            nodeType
            component {
              ...compositionComponent
            }
            nodes {
              displayName
              displaySettings {
                key
                value
              }
              displayTemplateKey
              key
              nodeType
              type
              ... on CompositionStructureNode {
                displayName
                displaySettings {
                  key
                  value
                }
                displayTemplateKey
                key
                nodeType
                type
                nodes {
                  displayName
                  displaySettings {
                    key
                    value
                  }
                  displayTemplateKey
                  key
                  nodeType
                  type
                  ... on CompositionStructureNode {
                    displayName
                    displaySettings {
                      key
                      value
                    }
                    displayTemplateKey
                    key
                    nodeType
                    type
                    nodes {
                      displayName
                      displaySettings {
                        key
                        value
                      }
                      displayTemplateKey
                      key
                      nodeType
                      type
                      ... on CompositionComponentNode {
                        displayName
                        displaySettings {
                          key
                          value
                        }
                        displayTemplateKey
                        key
                        nodeType
                        type
                        component {
                          ...compositionComponent
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

fragment compositionComponent on _IComponent {
  ... on DescriptiveSection {
    Description
  }
  ... on HeadingElement {
    Heading: Body
  }
  ... on RichTextElement {
    Body {
      json
    }
  }
  ... on ImageElement {
    AltText
    Image {
      url {
        default
      }
    }
  }
}
```

## Recursive query

The previous explicit query is repetitive because you query for a structure node in a fixed number of nested levels (given that you know that the structure of an experience is experience/section/row/column/component). For each level, you query for all available values (`type`, `nodetype`, `displaySettings`, and so on). An alternative is to write a recursive query. See [Recursive queries](docId:3peEweP1FjuUNE_prLNSc) in the Optimizely Graph documentation for information. The analogous recursive query to the explicit query above is:

```graphql
query RecursiveExperienceQuery {
  _Experience {
    items {
      composition {
        ...structureNode
      }
    }
  }
}

fragment structureNode on ICompositionNode {
  ... on CompositionStructureNode {
    key
    displayName
    type
    nodeType
    displayTemplateKey
    displaySettings {
      key
      value
    }
    component {
      ...compositionComponent
    }
    nodes @recursive {
      type
    }
  }
  ... on CompositionComponentNode {
    key
    displayName
    type
    nodeType
    displayTemplateKey
    displaySettings {
      key
      value
    }
    component {
      ...compositionComponent
    }
  }
}

fragment compositionComponent on _IComponent {
  ... on DescriptiveSection {
    Description
  }
  ... on HeadingElement {
    Heading: Body
  }
  ... on RichTextElement {
    Body {
      json
    }
  }
  ... on ImageElement {
    AltText
    Image {
      url {
        default
      }
    }
  }
}
```