2 OracleのカスタムGraphQL構文

GraphQL型システムは、APIのデータ・モデルを定義する構造化スキーマとして機能し、使用可能なデータ型、それらの関係、およびそれらの問合せ方法または変更方法を指定します。

この章では、標準のGraphQL型システムを紹介し、Oracleで使用されるカスタムGraphQL構文について説明します。

標準のGraphQL型は、基本的にエンティティとその属性の論理表現です。次の例は、「カー・レース・データセットの設定」で作成したリレーショナル表のGraphQL型システムを示しています。

例2-1 カー・レース・リレーショナル表のGraphQL型システム

# 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
}
GraphQL型システムは、次の基本要素を中心に編成されています:
  • スキーマ: APIのマスター・ブループリントとして機能し、すべてのデータ型を集約して、使用可能な操作(問合せ、突然変異、サブスクリプション)を管理します。リレーショナル・スキーマをGraphQLスキーマにマップする仕組みを理解するには、「Oracle AI DatabaseでのGraphQLスキーマの規則」を参照してください。GraphQLオブジェクト・スキーマは、すべてRDBMSの表定義に基づいています。DBMS_JSON_DUALITY PL/SQLパッケージのGET_GRAPHQL_SCHEMAファンクションを使用すると、基礎となるリレーショナル・スキーマをGraphQLスキーマの形式で表示できます。これは、適切な問合せを形成するために役立ちます。このGraphQLスキーマは、GraphQL問合せのセマンティック分析の実行にも使用できます。このGraphQLスキーマは、対応するリレーショナル表のGraphQL型を持つJSONドキュメントです。
  • データ型: データの形状と動作を記述します。標準GraphQLでは、6つの主要な型の分類が使用されます:
    • スカラー: Int、Float、String、Boolean、IDなどのプリミティブ・データ型。これらは単一の値を表し、サブフィールドを持つことはできません。Oracle AI Databaseでは、Oracle JSON言語スカラー型およびSQLスカラー型に対応する追加のGraphQLスカラー型がサポートされています。カスタム・スカラー型の詳細は、「OracleのカスタムGraphQLスカラー」を参照してください。
    • オブジェクト: 属性が定義された構造化エンティティ。たとえば、ユーザー型には、名前やEメールなどのフィールドがあります。
    • 列挙: フィールドが事前定義済の値セットのいずれかを持つことができる場合に使用します。
    • インタフェース: 複数のオブジェクト・タイプで実装できる一連のフィールドを定義し、それらの型の間で一貫性を確保します。
    • ユニオン: 複数のオブジェクト型のいずれかをフィールドに返すことができ、柔軟なAPIに役立ちます。
    • 入力: 構造化データを変異した形式に渡す場合など、複雑な入力に使用されます。
  • ルート型: 各型にはフィールドが含まれていて、フィールドは引数を受け取ることができるため、きめ細かな問合せおよび変更が可能になります。
    • 問合せ型: 読取り操作のエントリ・ポイント。問合せは、データ・グラフへのエントリ・ポイントを定義し、クライアントが単一の要求で必要なデータを正確にフェッチできるようにします。問合せは、フィールド、引数、戻り型、フラグメント、ディレクティブおよび変数の1つ以上のコンポーネントで構成されます。GraphQL問合せの構造とそのコンポーネントを理解するには、「GraphQL問合せ」をお読みください。
    • 変更型: 変更/書込みのエントリ・ポイント。
    • サブスクリプション型: リアルタイム・データおよび更新のエントリ・ポイント。
  • 型修飾子: リスト([Type])修飾子および非Null (Type!)修飾子を使用して、値リストまたは必須フィールド/引数を表現することもできます。

ノート:

標準GraphQLでは、前述のすべての型がサポートされます。ただし、OracleのGraphQLでは、スカラー型、オブジェクト型および問合せ型のみに焦点を当てています。このマニュアルでは、これらの型についてのみ詳細情報を提供します。GraphQL型システムの他の型について理解を深めるには、公式のGraphQLドキュメントをお読みください。