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:\

interface X {
  some_field: String!
  other_field: String!
}

type Y implements X {
  some_field: String!
  other_field: String!
  new_field: String!
}

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 {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}

Query __type to get details about any type:

query {
  __type(name: "Model") {
    name
    kind
    description
    fields {
      name
    }
  }
}

We would love to hear from you! Please reach out to [e-mail] and join our community slack. Let's build great things together.