GraphQL Documentation Page Notations and Caveats

Summary

The GraphQL API documentation pages use some notations and special markings to indicate a variety of things. These may be obvious, but in case you're unsure, they're explained here.

All queries and mutations, like functions, use a convention of following them with a pair of parentheses (for example, some_query()). They are also underlined and a different color to indicate that you can select them to open the documentation page for the query or mutation. Datatypes are also linked to their documentation pages, but are not shown with parentheses.

For the input parameters of some functions, you must provide a unique identifier of whatever you are querying or mutating. If you do not already know this identifier, you must first run a query to get it. For those functions, you will see a right-pointing double-chevron (that is, ») with text in small-caps that reads something like Show something Query. Select that to expand it and view the query needed to get the identifier or other prerequisite data.

Stability for each item appears on the individual reference page. On groupings pages, stability is shown as an inline label after the description, such as [Preview] or [Deprecated]. For full definitions of each stability level, see API Stability.

Required input parameters are marked distinctly from optional ones on each reference page. When a parameter is required, you must supply it for the query or mutation to run. Optional parameters have default values or can be omitted.

  • (): Parentheses after a name indicate a query or mutation. Datatypes appear on reference pages but do not use parentheses.

  • »: A double right-pointing chevron before a small-caps label indicates a collapsed prerequisite section. Select it to view the query needed to retrieve a required identifier.

  • [Preview]: The item is at Preview stability. It may change or be removed before general availability. See API Stability for details.

  • [Deprecated]: The item is deprecated and will be removed in a future version. Migrate away from it and use the recommended replacement.