Unlocking GraphQL: How Its Type System and Query Language Enable Precise Data Requests

0. Introduction

Through the previous article we gained a basic understanding of GraphQL. We know GraphQL uses a Schema to describe data and defines a Domain Specific Query Language (DSQL) that supports Schema queries. The Schema abstracts complex business model data into fine‑grained structures, while DSQL implementation gives front‑end developers the freedom to organize and customize request data. If visualized, GraphQL can be seen as a bridge that, based on a generic basic business data model , tightly and freely connects traditional backend services with front‑end pages.

Why can a GraphQL Schema represent the complex business model data supported by the server, and how does GraphQL’s Query empower front‑end developers to customize data? This article analyzes GraphQL’s design to answer these questions.

1. GraphQL Design

GraphQL consists of the following components:

Type System

Query Language

Execution Semantics

Static Validation

Type Introspection

As a DSL that decouples data models from concrete interface implementations, the most important component of GraphQL is its type system.

1.1 Type System

The GraphQL type system can be divided into scalar types and other advanced data types. Scalar types represent the most fine‑grained data structures and correspond to JavaScript primitive types. The GraphQL specification currently supports the following scalar types:

Int : integer, corresponds to JavaScript Number

Float : floating‑point number, corresponds to JavaScript Number

String : string, corresponds to JavaScript String

Boolean : boolean value, corresponds to JavaScript Boolean

ID : unique identifier string, similar to ES2015 Symbol

The JavaScript reference implementation of Scalar Types can be found here.

Other advanced data types include:

Object : used to describe hierarchical or tree‑like structures. Almost all GraphQL types are object types. An object type has a name field and a crucial fields field that describes the full structure. Example of an address object:

const AddressType = new GraphQLObjectType({
  name: 'Address',
  fields: {
    street: { type: GraphQLString },
    number: { type: GraphQLInt },
    formatted: {
      type: GraphQLString,
      resolve(obj) {
        return obj.number + ' ' + obj.street;
      }
    }
  }
});

Interface : describes common fields shared by multiple types. Example:

const EntityType = new GraphQLInterfaceType({
  name: 'Entity',
  fields: {
    name: { type: GraphQLString }
  }
});

Union : represents a field that may return one of several types. Example of a pet union (cat or dog):

const PetType = new GraphQLUnionType({
  name: 'Pet',
  types: [DogType, CatType],
  resolveType(value) {
    if (value instanceof Dog) {
      return DogType;
    }
    if (value instanceof Cat) {
      return CatType;
    }
  }
});

Enum : enumerated values. Example of an RGB enum:

const RGBType = new GraphQLEnumType({
  name: 'RGB',
  values: {
    RED: { value: 0 },
    GREEN: { value: 1 },
    BLUE: { value: 2 },
  }
});

Input Object : defined for queries; cannot reuse Object because of potential circular references. Reference implementation:

export type GraphQLInputType =
  GraphQLScalarType |
  GraphQLEnumType |
  GraphQLInputObjectType |
  GraphQLList<GraphQLInputType> |
  GraphQLNonNull<
    GraphQLScalarType |
    GraphQLEnumType |
    GraphQLInputObjectType |
    GraphQLList<GraphQLInputType>
  >;

export function isInputType(type: ?GraphQLType): boolean {
  const namedType = getNamedType(type);
  return (
    namedType instanceof GraphQLScalarType ||
    namedType instanceof GraphQLEnumType ||
    namedType instanceof GraphQLInputObjectType
  );
}

Object, Interface, and Union cannot be used as input object types.

List : wraps other types, commonly used for object field descriptions. Example of a Person type with parents and children fields:

const PersonType = new GraphQLObjectType({
  name: 'Person',
  fields: () => ({
    parents: { type: new GraphQLList(Person) },
    children: { type: new GraphQLList(Person) },
  })
});

Non-Null : forces a field’s value to be non‑null; errors if null. Example for a database row ID:

const RowType = new GraphQLObjectType({
  name: 'Row',
  fields: () => ({
    id: { type: new GraphQLNonNull(GraphQLString) }
  })
});

Another important type is the schema type, which describes the data a backend server can provide. Its detailed discussion is deferred to later sections.

1.2 Query Language

The type system corresponds to the Schema that describes server‑side data, while the query language decouples front‑end developers from backend interface dependencies, allowing them to freely compose and customize business data.

A GraphQL query request is called a query document, a string that the GraphQL service can parse, validate, and execute. A query consists of Operations and Fragments. Only queries that contain Operations are executed, but fragments can be parsed and reused across multiple queries.

Queries with a single operation may omit the operation name or use a shorthand (the query keyword plus the operation name). When multiple operations exist, each must be named.

Operations

GraphQL supports two operation types:

query: read‑only data fetching

mutation: data fetching with write side‑effects

The reference implementation also includes a subscription operation for real‑time updates, but it is experimental and not recommended for production.

The query model can be visualized as:

Selection Sets

Selection sets represent the currently selected data fields, formatted as:

{
  Field            // field name
  FragmentSpread   // fragment spread
  InlineFragment   // inline fragment
}

Refer to the graphql‑js implementation for usage.

Field

Field syntax: alias:name(argument:value) where alias is the field’s alias, name is the field name defined in the schema, argument is the parameter name, and value is the argument value matching a scalar type.

Example request:

http://yunhe.taobao.com/?query={banner{backgroundURL:bg,biaoti:slogan}}

Here backgroundURL is the alias bg.

Fragment

Fragments enable reuse of repeated field selections. They come in two forms: FragmentSpread and InlineFragment. Without fragments, a query might look like:

query noFragments {
  user(id: 4) {
    friends(first: 10) {
      id
      name
      profilePic(size: 50)
    }
    mutualFriends(first: 10) {
      id
      name
      profilePic(size: 50)
    }
  }
}

The repeated selection set is:

{
  id
  name
  profilePic(size: 50)
}

Using a fragment simplifies it:

query withFragments {
  user(id: 4) {
    friends(first: 10) {
      ...friendFields
    }
    mutualFriends(first: 10) {
      ...friendFields
    }
  }
}

fragment friendFields on User {
  id
  name
  profilePic(size: 50)
}

The ... operator expands the fragment content.

Inline fragment example:

query inlineFragmentTyping {
  profiles(handles: ["zuck", "cocacola"]) {
    handle
    ... on User {
      friends {
        count
      }
    }
    ... on Page {
      likers {
        count
      }
    }
  }
}

Directives

Directives address situations where field arguments cannot be overridden at execution time, such as conditionally including or skipping fields.

Example:

query hasConditionalFragment($condition: Boolean) {
  ...maybeFragment @include(if: $condition)
}

fragment maybeFragment on Query {
  me {
    name
  }
}

The @include directive includes the fragment only when if is true; the @skip directive skips the fragment when if is true.

Having become familiar with the type system and query language , we can now use GraphQL to implement application‑level data requests. The remaining three GraphQL components focus more on DSL implementation details and are omitted here; interested readers can consult the specification and reference implementation for deeper study.

2. Summary

GraphQL abstracts business data models at the application layer and provides a DSQL for customized data requests. It decouples interfaces from data, organizes business data structures, and allows different scenarios to reuse the same foundational model, which is the greatest benefit GraphQL brings.