GraphQL Glossary

Argument

A set of key-value pairs attached to a specific field. Arguments can be literal values or variables.

{
  users(per_page: 1, filter: { id: { value: "200" } }) {
    results {
      email
      bio: property(name: "bio")
    }
  }
}

Alias

An alternative name given to the result of a field to avoid conflicts during data fetching.

{
  notes: records(per_page: 20, filter: { table: { value: "notes" } }) {
    results { id }
  }

  cars: records(per_page: 20, filter: { table: { value: "cars"} }) {
    results {
      name: property(name: "name")
    }
  }
}

Directive

A declaration prefixed with an character that encapsulates programming logic for query execution on the client or server. There are built-in directives such as or . Directives can be used for features such as authentication, incremental data loading, etc.

query clients($is_client: Boolean!) {
  users(per_page: 20) {
    results {
      email
      created_at @skip(if: $is_client)
    }
  }
}

Document

A file or request string that contains one or multiple definitions of a GraphQL type system and can be interpreted by a GraphQL execution engine.

Field

A unit of data you are asking for in a Schema, which ends up as a field in your JSON response data.

type User {
  id: ID!
  first_name: String
  last_name: String
}

Fragment

A selection set that can be reused in multiple query operations. A GraphQL fragment is a shared piece of query logic.

fragment UserData on User {
  id
  email
  first_name
  last_name
}

{
  users(per_page: 20) {
    results {
      ...UserData
    }
  }
}

GraphQL Playground

An in-browser IDE for GraphQL development and workflow. Added benefits exist such as theme change, automatic schema reloading, HTTP headers configuration, query history and GraphQL subscription support.

Introspection

A technique to provide detailed information about a GraphQL API's schema. Types and fields used in introspection are prefixed with two underscores.

{
  __schema {
    types {
      name
    }
  }
}

Mutation

An operation for creating, modifying and destroying data.

mutation edit_car($car_id: ID!, $color: String!) {
  record_update(
    id: $car_id
    record: {
      properties: [{ name: "color", value: $color }]
    }
  ) { id }
}

Object Type

A type in a GraphQL schema that has fields.

type User {
   name: String!
}

is an Object type in the example above.

Operation

A query, mutation, or subscription that can be interpreted by a GraphQL execution engine.

Operation Name

A name for a single query, mutation, or subscription. Identifying a query or mutation by name is very useful for logging and debugging when something goes wrong in a GraphQL server.

mutation store_in_session($token: Any!) {
  session_create_field(name: "token", value: $token)
}

query find_user($id: ID!) {
  users(per_page: 1, filter: { id: { value: $id } }) {
    results {
      email
    }
  }
}

Query

A read-only fetch operation to request data from a GraphQL service.

Schema

A GraphQL schema is at the centre of any GraphQL server implementation and describes the functionality available to the clients which connect to it.

Schema Definition Language

The syntax for writing GraphQL Schemas. It is otherwise known as Interface Definition Language. It is the lingua franca shared by all for building GraphQL APIs regardless of the programming language chosen.

# A table defined in app/schema
type Table {
  id: ID!
  name: String!
  properties: [Property!]!
  records_count: Int!
  created_at: JSONDate!
  updated_at: JSONDate!
}

# A row stored in a table
type Record {
  id: ID
  table: String
  user_id: ID
  created_at: JSONDate!
  updated_at: JSONDate!
}

Scalar Type

A type that qualifies the data a GraphQL field resolves. GraphQL ships with five scalar types: , , , and . A service can add custom scalars. Insites adds scalars such as , and .

Type System

A collection of types that characterises the set of data that can be validated, queried and executed on a GraphQL API.