diff --git a/site/learn/Learn-Queries.md b/site/learn/Learn-Queries.md index 27c71203a0..15ac8422f8 100644 --- a/site/learn/Learn-Queries.md +++ b/site/learn/Learn-Queries.md @@ -4,7 +4,7 @@ layout: ../_core/DocsLayout category: Learn permalink: /learn/queries/ next: /learn/schema/ -sublinks: Fields,Arguments,Aliases,Fragments,Variables,Operation Name,Directives,Mutations,Inline Fragments +sublinks: Fields,Arguments,Aliases,Fragments,Operation Name,Variables,Directives,Mutations,Inline Fragments --- On this page, you'll learn in detail about how to query a GraphQL server. @@ -124,6 +124,33 @@ fragment comparisonFields on Character { You can see how the above query would be pretty repetitive if the fields were repeated. The concept of fragments is frequently used to split complicated application data requirements into smaller chunks, especially when you need to combine lots of UI components with different fragments into one initial data fetch. +## Operation name + +Up until now, we have been using a shorthand syntax where we omit both the `query` keyword and the query name, but in production apps it's useful to use these to make our code less ambiguous. +You'll need these optional parts to a GraphQL operation if you want to execute something other than a query or pass dynamic variables. + +Here’s an example that includes the keyword `query` as _operation type_ and `HeroNameAndFriends` as _operation name_ : + +```graphql +# { "graphiql": true } +query HeroNameAndFriends { + hero { + name + friends { + name + } + } +} +``` + +The _operation type_ is either _query_, _mutation_, or _subscription_ and describes what type of operation you're intending to do. + +The _operation name_ is a meaningful and explicit name for your operation. It can be very useful for debugging and server-side logging reasons. +When something goes wrong either in your network logs or your GraphQL server, it is easier to identify a query in your codebase by name instead of trying to decipher the contents. +Think of this just like a function name in your favorite programming language. +For example, in JavaScript we can easily work only with anonymous functions, but when we give a function a name, it's easier to track it down, debug our code, +and log when it's called. In the same way, GraphQL query and mutation names, along with fragment names, can be a useful debugging tool on the server side to identify +different GraphQL requests. ## Variables @@ -182,13 +209,6 @@ query HeroNameAndFriends($episode: Episode = "JEDI") { When default values are provided for all variables, you can call the query without passing any variables. If any variables are passed as part of the variables dictionary, they will override the defaults. -## Operation name - -One thing we also saw in the example above is that our query has acquired an _operation name_. Up until now, we have been using a shorthand syntax where we omit both the `query` keyword and the query name, but in production apps it's useful to use these to make our code less ambiguous. - -Think of this just like a function name in your favorite programming language. For example, in JavaScript we can easily work only with anonymous functions, but when we give a function a name, it's easier to track it down, debug our code, and log when it's called. In the same way, GraphQL query and mutation names, along with fragment names, can be a useful debugging tool on the server side to identify different GraphQL requests. - - ## Directives We discussed above how variables enable us to avoid doing manual string interpolation to construct dynamic queries. Passing variables in arguments solves a pretty big class of these problems, but we might also need a way to dynamically change the structure and shape of our queries using variables. For example, we can imagine a UI component that has a summarized and detailed view, where one includes more fields than the other.