GraphQL Terminology and Punctuation

This section defines some of the most commonly used GraphQL terminology and syntax punctuation.

This section includes the following topics:

GraphQL Terminology

This section defines some of the common terminology you will encounter when using GraphQL in SL1.

This is not an exhaustive list of GraphQL terminology. For other GraphQL terminology definitions, see the GraphQL documentation.

Schema

A schema describes all of the system data that you can request or modify in GraphQL. It defines the full hierarchy of types and fields, and all of the possible queries and mutations that are available in the GraphQL API.

For more information, see the section on The GraphQL Schema.

Types

Types are the fundamental units of any GraphQL schema. There are multiple kinds of types that are defined in the schema; many of these types are defined below and described in further detail throughout this section.

Operations

Operations are executable actions within a GraphQL document. There are three types of operations in GraphQL: Queries, mutations, and subscriptions. The SL1 GraphQL API supports queries and mutations, which are described in greater detail in this section; it does not support subscriptions. For more information about subscriptions, see the GraphQL documentation.

Queries

Queries are GraphQL operations that search for and return data from fields in your schema. A single query can search for and return data for a single field or multiple fields.

For more information, see the section on Queries.

Mutations

Mutations are GraphQL operations that modify data in the system and then return a value. Typically, mutations create new data, update existing data, or delete existing data.

For more information, see the section on Mutations.

Object Types

Object types are the most basic components of a schema, representing objects that you can fetch from SL1. All object types have a name and one or more fields.

For more information, see the section on Basic Query Syntax.

Fields

Fields are units of data within object types. Each field has a name, potentially a list of arguments, and a return type. Every GraphQL query requests one or more fields from an object, while mutations modify one or more fields.

For more information, see the section on Basic Query Syntax.

Arguments

Arguments are parameters, written as field name: value type pairs, that are passed into a field in a query or mutation. They help you define exactly what data you want GraphQL to search for and return in your query or provide specific parameters for your mutation.

Most argument fields in the schema include one of the following defined scalar types as a value type: 

• Int: A signed, 32-bit integer
• Float: A signed, double-precision, fractional value
• String: Textual data, represented as UTF-8 character sequences
• Boolean: true or false
• ID: A unique identifier, often used to fetch an object or as key for a cache.

Additionally, there are other value types in the SL1 GraphQL schema beyond those scalar types listed above. Examples of these other types include connection types and search types.

For more information, see the section on Basic Query Syntax.

Return Types

Return types specify the manner in which field data resolves in an operation. Typically, return types indicate the specific fields that you want GraphQL to return values for when you execute the operation.

For more information, see the section on Basic Query Syntax.

Connections

Connections are types within the GraphQL schema that are used to connect other defined elements in the schema. A connection consists of a group of related edges.

For more information, see the section on Connections, Edges, and Nodes.

Edges

Edges are types that connect two nodes, representing some sort of relationship between them. Edge types must have at least two fields: node and cursor.

For more information, see the section on Connections, Edges, and Nodes.

Nodes

Nodes are individual object types that are defined in the schema, consisting of one or more fields.

For more information, see the section on Connections, Edges, and Nodes.

Variables

Variables are dynamic values that can be used to replace arguments in your operation, enabling you to reuse the operation for multiple objects by changing the variable value.

For more information, see the section on Variables.

Fragments

Fragments are reusable units that you can include in multiple queries or mutations. Each fragment consists of a group of fields that are all associated with the same type.

For more information, see the section on Fragments.

Directives

Directives are keywords that you can use to make GraphQL perform custom logic in your operations. They can be attached to a field or a fragment that you are including in your operation, and can affect the operation execution and the results that GraphQL fetches.

For more information, see the section on Directives.

Case-Sensitivity

The GraphQL schema is full of named elements. Operations, objects, fields, arguments, types, variables, fragments, and directives all have names.

Names in GraphQL are limited to ASCII characters and are case-sensitive. For example, in the SL1 GraphQL schema, the object name account is different from the type name Account. Therefore, when forming queries and mutations, it is important to double-check that all of the included elements are using the correct case.

Punctuation

GraphQL uses certain special characters as punctuation to help define the structure of data. This section defines some of the common punctuation you will encounter when using GraphQL in SL1.

This is not an exhaustive list of GraphQL punctuation. For other GraphQL punctuation and special characters, see the GraphQL documentation.

When browsing the schema or writing your queries or mutations, you might encounter or use the following punctuation:

Punctuation	Function
{ }	Pass input objects and fields to the query or mutation object. They also represent the indentation levels within the hierarchy of the query or mutation.
( )	Pass parameters such as arguments to query or mutation objects.
:	Define a field or a type, such as in a field: value pair used in an argument or when defining a variable.
!	Indicates a non-nullable value type. By default, all value types in GraphQL can result in a null value. If a value type includes an exclamation point, it means that value cannot be null. The implications of a non-nullable type vary slightly based on the context in which it is used: When used with an input field, such as an argument or variable, it means that field is required; it must be included and have a value. When used with an output field, such as in a return type field, it means that GraphQL cannot return a null value for that field. If it does return a null value, the response will fail validation and trigger a GraphQL execution error, indicating that something has gone wrong. Can also be used as a filter operator.
[ ]	Indicates a list value type. The implications of a list type vary slightly based on the context in which it is used: When used with an input field, such as an argument, GraphQL accepts the list values only when each item in the list can be accepted by the list's item type. For example, if the list's expected item type is an integer (Int), GraphQL would accept the list values [1, 2, 3] but it would not accept the list values [1, 2, c]. When used with an output field, such as in a return type field, GraphQL must return an ordered list as a result of the list type. If it does not return an ordered list, the response will fail validation and trigger a GraphQL execution error, indicating that something has gone wrong.
$	Indicates a variable name. For more information about variables, see the section on Variables.
=	Indicates the default value of a variable. For more information about variables, see the section on Variables. Can also be used as a filter operator.
< >	Can be used together or separately as filter operators.
...	Indicates a fragment name. For more information about fragments, see the section on Fragments.
@	Indicates a directive, such as the default directives @include and @skip. For more information about directives, see the section on Directives.
#	Used at the beginning of a line within an operation to indicate a line that GraphQL can ignore when executing that operation. For example, you could include comments in your query by preceding them with the # symbol at the beginning of the line and GraphQL will ignore them when executing the query.