How To Use GraphQL

Learn useful terminology and concepts for using the Arize GraphQL API.

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.