GraphQL Query Anatomy

Gentleman's set of terms

GraphQL's new data acquisition standard has become popular just recently. Now the development of this technology is being actively discussed, more and more new tools are appearing. One of GraphQL’s strengths is that it gives the development team a universal language for describing what data is available in the API. But in what terms should the query language itself and the technology as a whole be discussed?

The GraphQL specification contains an almost comprehensive set of terms for all aspects of GraphQL. But the specification is quite voluminous. In this article, we will use concrete examples to find out the most important concepts and terms, which are enough to discuss GraphQL at the specialist level.

Note - This article is not the best choice for learning GraphQL from scratch. First, it is recommended that you familiarize yourself with the materials on graphql.org , try GraphQL in an excellent course, Learn Apollo, and then return to the article to immerse yourself in the language of technical terms.

Key GraphQL Queries

Often, a query is called everything that goes to the GraphQL server. There is some confusion about this. What is the task for the server that it asks for? It can be a query of data (query), mutation (mutation) or a subscription (subscription). The word "request" is strongly associated with network request in the understanding of HTTP and transport layer. Therefore, you should start with a few general concepts:

• Document GraphQL (GraphQL document). GraphQl string describing one or more operations or fragments.
• Operation (Operation). A single data request, mutation, or subscription that the GraphQL executable interprets.

What does the simplest operation consist of? For example, take a very simple GraphQL document.

Fig. The components of a simple request.

Here are the basic GraphQL constructs that describe the requested data.

• Field (Field). A unit of requested data that becomes a field in the JSON response. Please note that these parts are called “fields”, however deep in the structure of the query. The field at the top of the operation acts the same as the one deeper.
• Arguments (Arguments). A set of key-value pairs associated with a specific field. They are transmitted to the server by the field handler and affect the receipt of data. The arguments can be literals, as shown above, or variables, as in the following example. It should be noted that any field can have arguments, regardless of its nesting level.

The above query is a somewhat abbreviated form of GraphQL, allowing you to express the need for data as concisely as possible. But the GraphQL operation may include three additional parts. They are used when it is necessary to perform a different action than requesting data, or to send dynamically generated variables.

The following example shows all of these parts.

Fig. A more detailed request and its components.

• Type of operation (Operation type). One of three values ​​is possible: query , mutation , subscription , which indicates the type of operation being performed. Although language constructs with different operations look similar, the GraphQL specification provides for them different execution modes on the server.
• The name of the operation (Operation name). Naming is convenient for debugging and logging on the server. If something is wrong in the network logs or a tool like Apollo Optics shows problems on the GraphQL server, it is easier to find the problem request in the project by name than to parse the contents of the request. The name of the operation is similar to the name of a function in a programming language.
• Definition of variables (Variable definitions). A GraphQL query can have a dynamic part that changes with different calls to the server, while the query text remains constant. These are query variables . GraphQL has static typing, which allows you to check the values ​​of variables. In this section, variable types are declared.

Variables are transmitted separately from the request text in a format accepted at the transport level. Modern GraphQL implementations typically use JSON. Here's what an object with variables might look like for the query shown earlier:

Fig. An example of an object with variables.

As you can see, the key matches the name specified in the description of the variables. The value is taken from an enumerated type Episode.

• Variables (Variables). A dictionary of values ​​associated with the GraphQL operation. Contains dynamic operation parameters.

Another basic concept is not often mentioned, but it is important when discussing the technical aspects of GraphQL - what is it that is enclosed in curly braces?

Term sampling (selection set) are constantly found in GraphQL specification. The recursive nature of GraphQL is associated with it, in which nested queries are possible.

• The sample (Selection set). A set of fields requested in an operation or inside another field. You must specify a selection for the field if the field returns an object data type. On the contrary, for scalar fields of type Intand Stringit is not allowed to specify a selection.

Fragments

Snippets bring even more features to GraphQL. However, new concepts are coming.

• Determination fragment (Fragment definition). The part of a GraphQL document that describes a GraphQL fragment. Also called a named fragment, as opposed to an inline fragment, which will be discussed later.

• Name fragment (Fragment name). Each fragment has a unique name within the document. It is used to refer to a fragment in an operation or in another fragment. This name, as well as the name of the operation, is conveniently used for logging on the server. Therefore, it is recommended to give clear names that indicate the purpose of the fragment. If you need to optimize queries, a correctly chosen name makes it easier to find the place in the code where the fragment is specified.
• Applicability to type (Type condition). Unlike the GraphQL operation, which always starts with one of the types: query, mutation, or subscription, a fragment can be used in different selections. In order for a fragment to be able to verify on its own for compliance with the scheme, the user data type to which the fragment is applicable is indicated.

Using fragments in operations

Fragments are not particularly useful outside of operations. There are two ways to insert fragments, as shown below.

Fig. Two types of fragments in a request.

• Scan fragment (Fragment spread). To insert a fragment in an operation or in another fragment, it is indicated …before the fragment name. This is called a sweep. It may be present in a sample that applies to the same type as the fragment.
• Built fragment (Inline fragment). Adds fields to the selection, depending on the type to which the selection applies. This does not create an external fragment definition. The inline fragment is similar to the named fragment, but is specified in the request itself. The difference from the named fragment is that it is not necessary to specify the data type. More often such fragments are used together with directives, as will be shown later.

Directives

Using directives, additional functions of the GraphQL server are implemented. Directives do not affect the resulting values, but may affect the composition of the returned data and, possibly, how they are received. Directives can be found almost anywhere in the query, but this article only refers to the skip and include directives , which are defined in the current GraphQL specification.

Fig. The constructions shown are unlikely to be found in one request, but it is convenient to demonstrate them at once in this form.

The figure shows unrelated examples of where directives skipand can be used include. They set the conditions for the GraphQL executable to ignore fields and not include their values ​​in the result. The directive syntax is open, and with their help, various GraphQL implementations can add new features, without greatly complicating the analysis and execution of queries.

• Directive (Directives). Annotations of fields, fragments, and operations that affect their execution and return of results.
• Arguments guidelines (Directive arguments). They have the same meaning as field arguments, but are processed in the GraphQL executable and not passed to field handler functions.

Join the discussion

An important advantage of GraphQL is the presence of a universal language with which you can describe how to obtain data. You now have a gentlemanly set of terms for discussing GraphQL, for example as part of an ongoing discussion about GraphQL subscriptions .

In this article, we have covered only part of the GraphQL specification, which is devoted to the query language. In the following articles, we may consider terms that describe the GraphQL schema.

Want to use GraphQL technology in your daily work? We have various vacancies on frontend, backend and open source!

Translation of the article . Original by Sashko Stubailo