GraphQL Schema Conventions in Oracle AI Database

The schema consists of two JSON arrays, namely "types" and "quoted".

A typical GraphQL schema has the following structure where each relational table is represented by a GraphQL type, the columns of the tables are represented as fields of the GraphQL types. The "quoted" array contains the names of the tables that are quoted.

Example 2-2 JSON Schema for GraphQL Schema Representation

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "types": {
      "type": "array",
      "items": {
        "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "nullable": {
              "type": "boolean"
            },
            "quoted": {
              "type": "boolean"
            }
          }
      }
    }
    },
    "quoted": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": ["types"]
}

The figure below displays a sample mapping between a relational schema and the corresponding GraphQL schema. The relational schema specified here is defined in Setting up the Car Racing Dataset. The GraphQL schema is obtained using the GET_GRAPHQL_SCHEMA API.

Figure 2-1 Relational Schema to GraphQL Schema Mapping

• Each relational table is mapped to a GraphQL type:
  • For the relational schema set up in Setting up the Car Racing Dataset, the GraphQL schema would have four types corresponding to each relational table: team, driver, race, and driver_race_map respectively.
  • Naming Convention for a GraphQL Type: The name of a type corresponding unquoted table name from the relational schema is same as table name, with the first character being capitalized, and the remaining characters in lower case. In the example depicted by the figure, the table name race from the relational schema is named as type Race in the GraphQL schema. Quoted table names from the relational schema are represented unaltered.
• Within each GraphQL type there is a field corresponding to the columns of the table:
  • Recall that the table teams has three columns: team_id, name, and points.
  • So, the GraphQL schema type Teams has three fields corresponding to each column from the relational table.
  • Each field under a GraphQL type is a JSON object containing three sub-fields: type, nullable, and quoted. The type field represents the data type of the column. The nullable field is a boolean which can be TRUE or FALSE depending on whether a not null constraint has been imposed on the column. The quoted field is also a boolean, where TRUE represents that the column name is quoted.
  • Naming Convention for a field under a GraphQL Type: The name of a field corresponding unquoted column name from a relational table is same as the column name, all characters in lower case. You can see in the above figure that the column names from the table race : race_id, race_date, podium, name, and laps are named identical in the GraphQL schema. Quoted column names from the relational table is represented unaltered.
• Each GraphQL type also has an additional field listing any foreign key relationship referenced by or referencing that particular relational table.
  • In the above figure, you can see that the table driver_race_map references the driver_id field from the driver table. This relationship is listed as a field under the Driver type denoted as driver_race_map in the figure.
  • Naming Convention for a foreign key field under a GraphQL Type: The field name in lower case is same as the referenced or referencing table name from the relational schema. Similar to the column field, the foreign key fields is also a JSON object containing three sub-fields: type, nullable, and quoted.
  • The type sub-field is same as the referenced or referencing table name, with first character in upper case and other characters in lower case for unquoted names.
    • If the field represents the referencing table, then the value of the "type" is enclosed in the square brackets.
    • If there is a bi-directional relationship (in cases where both table references each other, or if a table references itself), then, field name ambiguity is resolved by appending "_Obj" to the referenced table field and "_List" to the referencing table field.
  • The sub-field "nullable" is always FALSE.
  • The quoted field is a boolean, where TRUE represents that the table name is quoted.

Note:

The GraphQL standard allows only alphanumerical ASCII characters and the underscore (_) for naming types, fields, directives and arguments, with all the names being case-sensitive. While names can start with an underscore (_), the only exception is that the names starting with double underscore (__) are disallowed. In RDBMS the unquoted names are case-insensitive and all alphanumerical characters are allowed in addition to special chars (_, $, #). The quoted names are case-sensitive with double quotes (") and null is not allowed in quoted names.

Relaxations in GraphQL schema for the Oracle DB relational schema:

• Non-ASCII characters are allowed.
• Quoted names which begin with an alphabet and contain only upper case alphabets, digits or symbols (#, $, _) are treated as unquoted names.