Understanding GQL Documentation

Summary

The GraphQL API documentation is extensive. It includes several hundred of pages of information. Those pages are grouped by queries, mutations, and datatypes.

Each query and mutation page contains a significant amount of text, and links to related pages with more details โ€” and perhaps some redundancy. To make it easier visually to scan these pages, to find what you need quickly, a certain page structure is used.

Document Groups

The GraphQL API documentation pages are organized into three primary groups: queries, mutations, and datatypes. Many queries and mutations use standard datatypes, such as string, boolean, and integer. However, these are not always sufficient for more complex requirements of most LogScale queries and mutations (i.e., functions). To fulfill those needs, special datatypes have been created for them. Although these special datatypes may be composed of standard dataypes, by making special datatypes that contain clusters of standard ones, they may be reused And they make GQL functions easier to use or comprehend โ€” especially when the sub-choices are optional. Of course, some special datatypes contain more special datatypes, sub-datatypes, so to speak.

This may be overwhelming and confusing to a newcomer, but it's the nature of a Graph Query Language. It's less structured per se, and allows for defining datatypes and making multiple connections through a schema. Queries are used for connecting nodes of data and retrieving results. Mutations are used for changing data, for which results are returned โ€” often confirmation of success, but sometimes data that might normally be gotten through use of a query. See the WikiPedia page on GraphQL for more on how GraphQL is typically designed and used.

There are three main special datatypes:

  • Input Structures: These are datatypes used for inputing, not storing data.

  • Types: These are regular datatypes for storing data, referred to simply as types.

  • Enumerators: Each of these contain an enumerated list of choices. For some you may choose more than one, depending on the syntax of the function. And for some you can forego choosing a value and a default or null value will be used.

There are two other datatype classifications of sorts:

  • Unions: A union allows you to choose one or more datatypes in the same query. For example, you might get data for a group and for users with the execution of one query.

  • Interfaces: An interface connects multiple similiar, possibly identical datatypes to the same function โ€” or another datatype. For example, the datatype SearchDomain is an interface for the Repository and the View datatypes โ€” after all, a search domain can be a repository or a view.

Page Structure

Each documentation page for each query and mutation has a basic structure, although it's not used for all pages. There are typically six sections. You can scroll through a documentation page to see them, or you can click on the links to them in the right margin of a page โ€” which are collapsed by default in the GQL documentation.

  • Summary: This describes briefly the function, what information a query will retrieve, and what data it can change for mutations. It's a starting point to understanding the function.

  • Related: Any related functions are listed here, with links to the documentation pages for them.

  • Syntax: This is the syntax for using the function, which includes the fields and their datatypes. It's very clinical and only useful as a as a reference. You'll need to read the subsequent sections to understand how to use a particular function.

  • Example: For almost all functions, a minimal, usually generic example is given of how it may be used. The parameters given are often the required ones only, and the results contain one to three returned values so as not to clutter the page. It's just to enough to provide some clarity since the syntax can be less than obvious.

  • Input Parameters: This is the same as what's contained in the syntax. There usually will be a table listing the parameters that use standard datatypes, with explanations of each. For many of functions, besides standaard datatypes, special datatypes are used. A table for each special datatype will be shown with its parameters and explanations. For each parameter, whether using standard or special datatypes, there will be an explanation and an as to whether it's required, and the default values, if any, for optional parameters.

    Some special datatypes use other datatypes. These sub-datatypes are linked to another documentation page containing a table listing the parameters and descriptions of them. Following each link can be overwhelming. For some special datatypes, the table for the main sub-datatype is included on the same page. Otherwise, you may have to drill down to each datatype's page โ€” or open them in separate tabs in your web browser.

  • Returned Values: This table will list the fields you may request in the results when executing a function. This is almost always a special datatype. In which case, a table listing the fields is shown. However, for a few functions there are no special datatypes used. For example, there may be a boolean to indicate success or not for mutations, or a string for the only straightforward return value of a function.