How To Use GraphQL
GraphQL provides developers with the ability to build more powerful tools with precise and flexible queries. This represents an architectural and conceptual shift from the well-known REST API.
Since GraphQL is relatively new, you'll likely encounter unfamiliar terminology in the GraphQL API. Use this page as a recourse to help you navigate the necessary terminology and concepts to implement the Arize GraphQL API.
Schema
A schema defines a GraphQL API's type system and resides on the GraphQL API server.
It describes the complete set of possible data (objects, fields, relationships, everything) that a client can access. Calls from the client are validated and executed against the schema. A client can find information about the schema via introspection.
Field
A field is a unit of data you can retrieve from an object. As the official GraphQL docs notes that: "The GraphQL query language is basically about selecting fields on objects."
The official spec also details the following:
All GraphQL operations must specify their selections down to fields which return scalar values to ensure an unambiguously shaped response.
This means that if you try to return a field that is not a scalar, schema validation it will throw an error. There must be nested subfields added until all fields return scalars.
Argument
An argument is a set of key-value pairs attached to a specific field. Some fields require an argument. Mutations require an input object as an argument.
Implementation
A GraphQL schema may use the term implements to define how an object inherits from an interface.
Here's a contrived example of a schema that defines interface X
and object Y
:\
This means object Y
requires the same fields/arguments/return types that interface X
does, while adding new fields specific to object Y
. (The !
means the field is required.)
Connection
Connections let you query related objects as part of the same call. With connections, you can use a single GraphQL call where you would have to use multiple calls to a REST API.
It's helpful to picture a graph: dots connected by lines. The dots are nodes, the lines are edges. A connection defines a relationship between nodes.
Edge
Edges represent connections between nodes. When you query a connection, you traverse its edges to get to its nodes. Every edges
field has a node
field and a cursor
field. Cursors are used for pagination.
Node
Node is a generic term for an object. You can look up a node directly, or you can access related nodes via a connection. If you specify a node
that does not return a scalar, you must include subfields until all fields return scalars.
Discovering the GraphQL API
GraphQL is introspective. This means you can query a GraphQL schema for details about itself.
Query __schema
to list all types defined in the schema and get details about each:
Query __type
to get details about any type:
Was this helpful?