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 preceding 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 in the preceding example 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 runtime execution. @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. SeeGraphQL Variables for usage and examples.

Note: Oracle AI Database Support for GraphQL implements a practical subset of GraphQL. See Oracle Database Support for GraphQL – Constraints and Limitations for details.

• GraphQL Table Function
  In addition to accessing Oracle AI Database using SQL, starting in 26ai, you can use GraphQL to query Oracle AI Database tables and get the result in form of JSON objects.

• Custom GraphQL Directives
  In Oracle AI Database’s GraphQL integration, directives play a crucial role in adding expressive power and flexibility to queries and view definitions.

• GraphQL Filter Specifications: Arguments
  Filtering using GraphQL in Oracle AI Database is achieved by using arguments.

• GraphQL Filter Specifications: QBE
  While you can perform equality comparisons using GraphQL arguments, you can perform all other comparisons using the query-by-example (QBE) syntax.

• GraphQL Variables
  Variables keep the queries generic and reusable. Instead of hard coding the a value in the query, using a variable would allow you to pass the value separately.

• Query and Variable Descriptions, and Default Variable Values
  GraphQL supports descriptions to provide documentation for operations and variables.

• Comments within a GraphQL Query
  Comments are annotations embedded in the GraphQL query that serve to explain and document a specific statement making the query easier to understand and maintain.