Anatomy of GraphQL Queries

Gentleman's term set

A new data acquisition standard GraphQL has become popular recently. The development of this technology is being actively discussed, new tools are emerging. One of the advantages of GraphQL is that it gives the development team a universal language for describing what data is available in the API. But in what terms to discuss the query language itself and the technology as a whole?

The GraphQL specification contains an almost comprehensive set of terms in all aspects of GraphQL. But the specification is quite voluminous. In this article, we will learn the most important concepts and terms with concrete examples that are sufficient for discussing GraphQL at the expert level.

Note - This article is not the best choice for learning GraphQL from scratch. First, it is recommended that you read 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.

Basic GraphQL Queries

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

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

What is the simplest operation? For example, take a very simple GraphQL document.

Fig. The parts of a simple query.

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

• Field The unit of requested data that becomes the field in the JSON response. Note that these parts are called “fields”, no matter how deep they are in the query structure. The field at the top of the operation acts the same way as being a level 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. 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, which allows expressing the need for data as concisely as possible. But the GraphQL operation may include three additional parts. They are used when you need to perform a different action than querying data, or send dynamically generated variables.

The following example shows all these parts.

Fig. More detailed request and its components.

• The type of operation (Operation type). Perhaps one of three values: 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). Assigning names is convenient for debugging and logging on the server. If something is wrong with the network logs or a tool like Apollo Optics shows problems on the GraphQL server, it is easier to find the problematic query in the project by name than to parse the contents of the query. The name of an operation is similar to the name of a function in a programming language.
• Variable definitions. A GraphQL query may have a dynamic part, which changes during different accesses to the server, while the query text remains constant. These are query variables . GraphQL has static typing that allows you to check the values ​​of variables. In this part, the types of variables are declared.

Variables are transmitted separately from the text of the request in the format adopted at the transport level. Modern graphQL implementations typically use JSON. Here’s what an object with variables for a previously shown query might look like:

Fig. An example of an object with variables.

As you can see, the key coincides with the name specified in the description of the variables. The value is taken from the Episode enumeration type.

• Variables . Value Dictionary accompanying GraphQL operations. Contains dynamic parameters of the operation.

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?

The term selection set is constantly found in the GraphQL specification. It is associated with the recursive nature of GraphQL, in which nested queries are possible.

• Selection (Selection set). A set of fields requested in an operation or inside another field. For a field, you must specify a selection if the field returns an object data type. On the contrary, for scalar fields of type Int and String it is not allowed to specify a selection.

Fragments

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

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

• 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 useful 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 properly chosen name makes it easier to find a place in the code where a fragment is specified.
• Applicability to type (Type condition). Unlike the GraphQL operation, which always starts with one of the types: query, mutation, or subscription, the fragment can be used in different samples. In order for a fragment to be checked by itself for compliance with the scheme itself, a custom data type is indicated, to which the fragment is applicable.

Using fragments in operations

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

Fig. Two types of fragments in the request.

• Fragment spread scan. To insert a fragment into an operation or into another fragment, it is indicated … before the name of the fragment. This is called a sweep. It may be present in a sample that applies to the same type as a 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 embedded fragment is similar to the named one, 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

With the help of directives, additional functions of GraphQL server are implemented. Directives do not affect the resulting values, but can affect the composition of the returned data and, possibly, how they are obtained. Directives can be found almost anywhere in the query, but this article only mentions the skip and include directives that are defined in the current GraphQL specification.

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

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

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

Join the discussion

An important advantage of GraphQL is the availability of a universal language with which you can describe data retrieval. You now have a gentlemanly set of terms for GraphQL discussion, for example in the ongoing discussion about GraphQL subscriptions .

In this article, we touched on only part of the GraphQL specification, which is devoted to the query language. In the following articles, we may consider the terms in which the GraphQL scheme is described.

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

Translation of the article . Original author Sashko Stubailo