Skip to main content
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 support@arize.com and join our community slack. Let’s build great things together.