3 GraphQL Queries

A GraphQL query is a way to request specific data from a GraphQL server.

When you use a GraphQL query, you're describing exactly what information you want, and the server responds with data that matches the structure of your request. The output exactly matches the request, nothing more or nothing less is returned. This approach gives clients precise control over the data they receive, unlike traditional APIs that may send extra, unnecessary information or require multiple requests to gather related data. The Query type is essentially an object type at the root of a GraphQL schema. It contains fields, each representing a unique entry point or resource clients can query. Each field on the Query type corresponds to a distinct endpoint of data retrieval. Fields are named and typed, clearly defining what can be requested and what will be returned.

A GraphQL query is written using these foundation blocks:
  • Query Type and Fields : The Query type defines what entry points your clients can request. For example, in our car racing schema:
    type Query {
      driver(id: ID!): Driver
      race(id: ID!): Race
      drivers: [Driver!]!
      races: [Race!]!
    }
    You can see that each field has:
    • Return Type: What kind of object or primitive is returned (e.g. Driver, Race, or a list). The above specified query type defines that, driver and race fetches a specific driver or race by their ID. drivers and races provides a list of all drivers and races available.

    • Arguments: Optional or required inputs for fetching or filtering specific data. Fields like driver(id: ID!) as specified above take arguments to specify which object to fetch:
      query {
        driver(id: "101") {
          name
          team {
            name
          }
        }
      }
      The id argument precisely fetches driver #101, allowing you to tailor the data they get.
    • Selection Sets : You can specify exactly which fields to retrieve from the types, minimizing over-fetching. The following query would return race name, date and each driver's finishing position and name. Fields not requested (such as laps or podium) are omitted.
      query {
        race(id:"202") {
          name 
          date 
          result {
            finalPosition 
            driver {
              name
            }
          }
        }
      }
  • Fragments : Fragments let you construct sets of fields, and then include them in queries where needed. This provides reusability as instead of querying the same fields in multiple queries, you can simply query the defined fragment.
  • Directives: A GraphQL directive is an annotation, prefixed with @, that can be attached to parts of a GraphQL schema or operation (such as fields, fragments, or queries) to alter the execution behavior at runtime. @include and @skip are the two native directives defined in the standard GraphQL specification. Oracle supports custom GraphQL directives. See Custom Directives in Oracle GraphQL for detailed description of custom directives.
  • Variables : Variables helps you to parameterize queries for reusability. They keep queries generic and reusable. Instead of hard coding the field values in a query, utilizing a GraphQL Variable in Oracle would allow you to pass the value to a variable separately. See GraphQL Variables for usage and examples.