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" },
          "description": { "type": "string" },
          "annotations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "value": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "quoted": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["types"]
}

The following figure 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](get_graphql_schema.html#GUID-51719531-16C6-44F8-8017-E4DD34F3120B) API.

Figure 1: Relational Schema to GraphQL Schema Mapping

• Each relational table is mapped to a GraphQL type:

  • For the relational schema set up inSetting 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 the following sub-fields: type, nullable, quoted, description, and annotations. The type field represents the data type of the column. The nullable field is a Boolean value 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 value, where TRUE represents that the column name is quoted. The description field is a string that contains the comment defined for the column. The annotations field is an array of objects, each with two string fields, name and value, representing an annotation name and its corresponding value.

  • 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 preceding 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 preceding 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 bidirectional 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 TRUE.

  • The quoted field is a Boolean value, where TRUE represents that the table name is quoted.

Note:

The GraphQL standard allows only alphanumeric 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 not case-sensitive and all alphanumeric 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:

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