GQL Documentation Page Structure

Summary

Each GraphQL API query and mutation documentation 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 quickly what you need, a certain page structure is used.

The basic structure contain 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 is collapsed by default in the GQL documentation.

  • Summary: Each function page starts with the name of the query or mutation, followed by a summary that describes briefly the function, what information it will retrieve for a query, or what data it can change for a mutation.

  • Related: Any related functions are listed, and includes a very brief description and a link to their documentation page. For functions that are deprecated, a link to its replacement or an alternative function is provided.

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

  • Example: For almost every function, a minimal, generic example is shown as to how it may be used. The given parameters are often only those that are required, and the results contain only one to three returned values to reduce clutter. Sometimes ellipses are used to denote removed results. However, be aware that ellipses are used by functions that utilize a union datatype (see Docs Sorting).

  • Input Parameters: For functions with parameters that use standard datatypes, there will be a table listing them. Many functions, though, use special input datatypes. There will be tables with their parameters. For each parameter, whether a standard or special datatype, there will be an explanation, a check-mark to indicate whether it's required, and the default value, if any, for optional parameters.

    Some special datatypes use other special datatypes. Each of these sub-datatypes will be linked to another documentation page containing a table listing its own parameters and descriptions. For some special datatypes, the table for the main sub-datatype is included on the same page. Otherwise, you have to drill down to each datatype's page — or open them in separate tabs in your web browser.

  • Returned Values: This section will include a table that lists the fields you may request in the results when executing a function. For union datatypes, each table which is part of the union will be included.

    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. There won't be a Returned Values section.