Custom GraphQL Syntax in Oracle

The GraphQL type system serves as a structured schema that defines the data model for an API, specifying the types of data available, their relationships, and how they can be queried or modified.

This chapter introduces the standard GraphQL type system and describes the custom GraphQL syntax used in Oracle.

A standard GraphQL type is basically a logical representation of an entity and it’s attributes. The following example provides the GraphQL type system for the relational tables created in Setting up the Car Racing Dataset.

Example 2-1 GraphQL Type System for the Car-Racing Relational Tables

# Represents a racing team
type Team {
  team_id: ID!           # Team primary key
  name: String!          # Team name
  points: Int!           # Points team has scored
  driver: [Driver!]!     # List of drivers on the team
}

# Represents an individual driver
type Driver {
  driver_id: ID!          # Driver primary key
  name: String!           # Driver name
  points: Int!            # Points the driver has scored
  team: Team              # The team the driver belongs to
  race: [DriverRaceMap!]! # Races the driver has participated in
}

# Mapping table representing a driver participating in a race
type DriverRaceMap {
  driverRaceMapId: ID!   # Primary key for this mapping
  race: Race!            # Associated race
  position: Int          # Driver's finishing position in the race
}

# Represents a race event
type Race {
  _id: ID!                  # Race primary key
  name: String!             # Race name
  laps: Int!                # Number of laps in the race
  date: String              # Race date/time as ISO string
  podium: JSON              # JSON data about podium finishers (unstructured)
  result: [DriverRaceMap!]! # Results mapping driver to positions
}

The GraphQL type system is organized around these foundational elements:

• Schema : Acts as the API's master blueprint, aggregating all data types and governing available operations (queries, mutations, subscriptions). SeeGraphQL Schema Conventions in Oracle AI Database to understand how the relational schema is mapped to a GraphQL schema. The GraphQL object schema is entirely based on the RDBMS table definitions. The GET_GRAPHQL_SCHEMA function of the DBMS_JSON_DUALITY PL/SQL package allows you to view the underlying relational schema in the form of GraphQL Schema, which will assist you in formulating the right queries. This GraphQL schema can then also be used for performing the semantic analysis of the GraphQL queries. This GraphQL schema is a JSON document having GraphQL types of the corresponding relational tables.

• Data Types: Types describe the shape and structure of the data. Standard GraphQL employs six primary type classifications:

  • Scalars: Primitive data types such as Int, Float, String, Boolean, and ID. These represent single values and cannot have sub-fields. Oracle AI Database supports additional GraphQL scalar types, which correspond to Oracle JSON-language scalar types and to SQL scalar types. See Custom GraphQL Scalars in Oracle for detailed description of custom scalar types.

  • Objects: Structured entities with defined attributes. For example, a user type might have fields like name and email.

  • Enums: Used when a field can have one of a predefined set of values.

  • Interfaces: Define a set of fields that multiple object types can implement, ensuring consistency across those types.

  • Unions: Allow a field to return one of several object types, useful for flexible APIs.

  • Inputs: Used for complex inputs, such as when passing structured data to mutations.

• Root Types: Each type contains fields, and fields can accept arguments, allowing for fine-grained queries and mutations.

  • Query Type: Entry point for read operations. A query defines the entry points into your data graph and allows clients to fetch precisely the data they want, in a single request. A query consists of one or more of the following components: Fields, Arguments, Return Types, Fragments, Directives and Variables. ReadGraphQL Queries to understand the GraphQL query structure and its components.

  • Mutation Type: Entry point for modifications/writes.

  • Subscription Type: Entry point for real-time data and updates.

• Type Modifiers: You can also use List ([Type]) and Non-Null (Type!) modifiers to express lists of values or required fields/arguments.

Note: Standard GraphQL supports all of the preceding types. However, GraphQL in Oracle focuses only on the Scalar, Objects and Query Types and this book provides detailed information only about these types. Read the official GraphQL documentation to gain a better understanding of other types in the GraphQL type system.

• GraphQL Schema Conventions in Oracle AI Database
  The schema consists of two JSON arrays, namely “types” and “quoted”.

• Custom GraphQL Scalars in Oracle
  GraphQL natively supports the following types: String, Float, Int, Boolean, and ID.

• Implicit Field Aliasing Support for GraphQL in Oracle
  When using GraphQL with Oracle, implicit field aliasing enables a streamlined mapping of SQL column names to JSON document fields.

• Generating a GraphQL Schema from a Relational Schema
  Use the GET_GRAPHQL_SCHEMA function to obtain the underlying relational schema in the form of a GraphQL schema.