GraphiQL

This topic describes the user interface for Optimizely Content Management System (CMS 13) Settings > GraphiQL. See the Optimizely Graph documentation, and start with GraphQL basics for information about the GraphQL fundamentals of Optimizely Graph.

GraphiQL views

The GraphiQL tab has the following views.

• Show Documentation Explorer – Browse the schema and construct your queries.

  

• Show History – View previously executed queries.

  

• Show GraphiQL Explorer – Lists the types and fields available in your GraphQL schema.

You can visually construct your GraphQL queries by interacting with your schema. Instead of manually typing out the entire query, you:

• Browse the schema – See all available types and their fields.

• Select types – Choose the main type you want to query (e.g., Block1).

• Select fields – Check the boxes or radio buttons next to the specific fields you want to retrieve for that type (e.g., ids, limit, total).

• Specify arguments – Use the input fields or dropdowns next to arguments like limit, skip, orderBy, or where to filter, paginate, or sort your results.

• Drill down – Expand complex fields (using the triangle/arrow) to select their nested sub-fields or arguments, building out the structure of your query.

  As you make these selections, the Explorer automatically generates the corresponding GraphQL query in the Query Editor panel, making it much easier to discover and build queries.

• Show Flags – You can save frequently used GraphQL queries and reuse them. The main benefit is faster query execution, especially when you run the same query structure multiple times but only change the input parameters (variables). By using a stored template, the system can optimize how it processes these queries, leading to quicker results. Off is selected by default.

  

• Refetch GraphQL schema – Click to make a request to your Optimizely Graph API endpoint to download the latest version of its schema definition. You would typically do this if:

  • The underlying GraphQL API was updated: For example, new content types, fields, or mutations were added, modified, or removed in your Optimizely instance.
  • GraphiQL's cached schema might be outdated: To ensure that the Explorer panel, autocomplete suggestions, and documentation within GraphiQL are accurate and reflect the current state of your API.

• Open Short-keys dialog – Displays keyboard shortcuts to common commands.

  

• Open Settings dialog – Lets you customize your GraphiQL experience.

  • Persist headers – If you select On, any HTTP headers you have set up (for example, for authentication) are saved and automatically reloaded when you refresh the page or revisit GraphiQL.

    🚧

    Caution

    Only enable if you trust this device, as sensitive headers could be exposed on an untrusted computer.

  • Theme – Lets you change the visual color scheme of the GraphiQL interface.

    • System – GraphiQL automatically matches your operating system's light or dark mode setting.
    • Light – Forces the interface to always display with a light background.
    • Dark – Forces the interface to always display with a dark background.

  • Clear storage – Click Clear data to remove all data that GraphiQL has stored locally in your browser, such as your query history, saved queries, and other preferences. It is useful if you want to start with a completely fresh setup or troubleshoot issues.

    ❗️

    Warning

    This action is irreversible for the locally stored data.

  

Query Editor panel

The Query Editor is the main text area where the GraphQL query is written and edited.

• Execute Query (Play icon) – Ctrl-Enter – Click to send the GraphQL query written in the Query Editor to the server and receive a response. The results, or any errors, will then appear in the Results/Error Viewer panel.
• Prettify Query – Shift-Ctrl-P – Formats the GraphQL query in the Query Editor. It indents code, adds appropriate line breaks, and generally cleans up the query's structure to make it more readable and consistent.
• Copy Query – Shift-Ctrl-C – Click to copy the entire GraphQL query text from the Query Editor to your system's clipboard. This is useful for sharing queries, saving them externally, or using them in other tools.
• Merge fragments into Query – Shift-Ctrl-M – Fragments let you define reusable sets of fields. This function takes any fragments defined within your query and expands them directly into the main query, showing the full, unfragmented query structure. This can help understand the complete query being sent, or for debugging.
• Cache – Toggle on or off. It controls whether the results of your GraphQL queries are stored locally in your browser's cache. When caching is enabled, repeated queries for the same data may be served faster from the local cache, reducing network requests and improving performance.
• Stored Query – Toggle on or off. When on, the system can recognize and use pre-defined query templates. This can lead to faster query execution, especially for queries with the same structure but different input parameters (variables), as the system can optimize their processing.
• Use new deployment – Toggle Old or New. This lets you switch the target GraphQL API endpoint between different deployments or versions of your Optimizely Graph. Old would typically point to a stable, production environment, while New might point to a staging, development, or experimental deployment. This is essential for testing new features or changes before they are released to a live environment.
• Variables tab – GraphQL queries can be made dynamic by using variables. This tab provides a dedicated area where you can define the JSON values for these variables, keeping them separate from the main query text. If your query defines variables (for example, query MyQuery($limit: Int) ), you would enter a JSON object in this tab where the keys match your variable names and the values are their corresponding data (for example, {"limit": 10}).
• Headers tab – Lets you include custom HTTP headers with your GraphQL requests. This is commonly used for purposes like authentication (such as passing an Authorization token), specifying content types, or including other custom metadata required by the API. Enter key-value pairs for the HTTP headers you want to send (such as {"Authorization": "Bearer your_token_here"}).

The Results/Error Viewer Panel shows the JSON response from the GraphQL server after a query is executed.