---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Query record data using the GraphQL API framework

# Query record data using the GraphQL API framework {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 minutes to read

Create a custom GraphQL API to query record data from a component or a third-party system.

For example, you can create a component that displays the cases associated with an SLA. You can use the Next Experience UI Framework to develop the component you need, and access case data from the platform by creating a GraphQL schema that defines data in the Case table.

To learn more about developing components, see [Developing components for
Workspace](https://www.servicenow.com/docs/access?context=custom-components&version=xanadu&pubname=xanadu-application-development&ft:locale=en-US).

## Benefits of GraphQL {#scripted-graph-ql__section_ztd_cf1_dlb}

GraphQL is a web query language optimized for client-side development. Using scripted
GraphQL, you can:  
* Discover fields and objects available to query through introspection.
* Query the exact data you need from a component.
* Manage multiple possible queries from a single API, as opposed to multiple endpoints for a REST request.
* Integrate with third-party systems by making the schema public.
* Generate the GraphQL query from your component and handle the response.
{#scripted-graph-ql__ul_pp2_myf_dlb}

## What to know before you begin {#scripted-graph-ql__section_yrj_nh1_dlb}

Before you start creating custom GraphQL APIs, make sure you have:  
* GraphQL knowledge to create a schema.
* JavaScript knowledge to define the API behavior.
* General knowledge of web component concepts.
* A custom Workspace component to consume record data.
* Understanding of the ServiceNow data model that you want to expose in the schema.
* GlideRecord knowledge to map fields to record data in your resolver scripts.
{#scripted-graph-ql__ul_zj1_qh1_dlb}

## GraphQL overview {#scripted-graph-ql__section_wqr_bf1_dlb}

Creating a scripted GraphQL API includes these parts:  

GraphQL Schema Definition Language (SDL)
:   Define the structure and data type of fields available in a GraphQL query. You can define the SDL using the Schema script field in the GraphQL Scripted Schemas \[sys_graphql_schema\] table. The SDL
    only supports Query and Mutation operations.

Resolvers
:   Define the data returned by each field. You can define the resolvers for each field in the GraphQL Scripted Resolvers related list on the GraphQL Scripted Schemas form.

Typeresolvers
:   Resolve interfaces and unions into concrete GraphQL types. For example, you might define a union between an `incident` type and a `problem` type. Use the typeresolver script to define when
    to return which. You can define the typeresolvers in the GraphQL Scripted Typeresolvers related list on the GraphQL Scripted Schemas form.

Resolver mappings
:   Map resolvers to fields in the schema. You can define resolver mappings in the GraphQL Scripted Resolver Mappings related list on the GraphQL Scripted Schemas form.

To learn more about the GraphQL query language, see the [GraphQL website](https://graphql.org/).

To test queries to your GraphQL APIs, you can use the GraphQL Explorer, an integrated GraphQL testing tool. For more information, see [Test GraphQL APIs with GraphQL Explorer](https://servicenow-prod.fluidtopics.net/7z~log34oQsxmqI7Flxsrw "Test query your GraphQL APIs using an integrated GraphQL testing tool.").

## Limitations {#scripted-graph-ql__section_ymn_b2j_dlb}

The following GraphQL features aren't supported:  
* Subscription operations
* Custom scalar types
{#scripted-graph-ql__ul_fns_g3v_flb}

## Introspection {#scripted-graph-ql__section_vxz_rw5_flb}

By default, introspective queries into your custom schemas aren't enabled. To turn on introspection, see [Enable introspective queries for GraphQL schemas](https://servicenow-prod.fluidtopics.net/LoFxFHhB5nhLxHuy2AinJw "Discover the queries and mutations supported by schemas on your instance by enabling introspection.").

## Namespaces {#scripted-graph-ql__section_frl_yyh_dlb}

GraphQL APIs have two different namespaces:  

Application namespace
:   The namespace for the custom application. To learn more about application
    namespaces, see [Application scope](https://www.servicenow.com/docs/access?context=c_ApplicationScope&version=xanadu&pubname=xanadu-application-development&ft:locale=en-US).

Schema namespace
:   The namespace for the schema to ensure that all queries are unique. You can have
    multiple schema namespaces in a single application.

When querying data, you must include both namespaces in your query. For example, the
following query is searching for data with the following namespaces:  
* Application namespace: `x_graph_scope`
* Schema namespace: `planet`
{#scripted-graph-ql__ul_ihg_pzh_dlb}  

    query {
      x_graph_scope {
        planet {
          findAll {
            name
            mass
            distance
          }
        }
      }
    }

## Directives and global functions {#scripted-graph-ql__section_zdw_rnc_glb}

`@source` schema directive

:   Maps a GraphQL field to the value of a property of the parent object. If the field has a separate resolver script, the system uses the record that it resolves to instead of the parent object.

    Use the `@source` directive in your schema script.

`@defer` query directive
:   Defer processing of a GraphQL fragment until later in the query. Use this query directive to delay returning data for slow-responding fields within a fragment. Stream the field results of the deferred fragment as a multi-part response.  
    Note:  
    To use the `@defer` directive, your GraphQL client must accept multipart/mixed HTTP headers. For example, set the HTTP headers to `Accept: multipart/mixed; boundary="-"`.

    Use the `@defer` directive to improve user time to interaction. Avoid applying this query directive indiscriminately as it can also cause performance degradations. Conduct performance testing to determine which fields can be deferred for better performance.

Resolver functions

:   These functions are available on the global env object.

    * getArguments(): Returns the arguments of the previous field.
    * getSource(): Returns the parent object.
    {#scripted-graph-ql__ul_t2l_vrx_glb}

    Use in your resolver script.

Typeresolver functions

:   These functions are available on the global env object.

    * getArguments(): Returns the arguments of the previous field.
    * getObject(): Returns the parent object.
    * getTypeName(): Returns the name of the interface or union type.
    {#scripted-graph-ql__ul_e1w_vrx_glb}

    Use in your typeresolver script.

## Demo application {#scripted-graph-ql__section_ubj_21v_flb}

To see a demo GraphQL PTO calendar schema with mutations and queries, enable the GraphQL
Framework Demo Application plugin (com.glide.graphql.framework.demo).
* **[Create a GraphQL schema](https://servicenow-prod.fluidtopics.net/vVM3t_ip4ibLxOWMnsjmqQ#build-graphql-scripted-schema)**   
  Create a GraphQL schema to make data available to GraphQL queries.
* **[Enable introspective queries for GraphQL schemas](https://servicenow-prod.fluidtopics.net/LoFxFHhB5nhLxHuy2AinJw)**   
  Discover the queries and mutations supported by schemas on your instance by enabling introspection.
* **[Test GraphQL APIs with GraphQL Explorer](https://servicenow-prod.fluidtopics.net/7z~log34oQsxmqI7Flxsrw)**   
  Test query your GraphQL APIs using an integrated GraphQL testing tool.
* **[Query a GraphQL schema from a component](https://servicenow-prod.fluidtopics.net/WL1D25TUCaMTN7ZfYR6pjA)**   
  Access record data in a component by querying your scripted GraphQL schema.
* **[GraphQL system properties](https://servicenow-prod.fluidtopics.net/3XahwDhxEgPgYgvzxQOegQ)**   
  Configure GraphQL API framework behavior. For example, you can configure whether to allow introspective queries into your schema.