Schema

TigerGraph GraphQL Service translates TigerGraph’s GSQL schema into a GraphQL schema. Vertices and edges are translated to Object types in GraphQL, and outgoing and incoming reverse edges in GSQL schema are mapped to fields in the corresponding vertex type. Vertex types are included as fields in top-level type for the entire graph.

Within the GraphQL client, you can click on the Schema button on the right side of the screen to view the entire GraphQL schema.

Currently, TigerGraph GraphQL service cannot automatically react to schema changes happening in TigerGraph. When a schema change happens, you need to restart the service to keep the GraphQL schema in sync with TigerGraph schema.

Query

Every GraphQL schema starts with a top level Query type. The Query type only has one field whose name and type name are the same as the GSQL graph name.

If you have a graph in GSQL named DemoGraph, then in your GraphQL schema, there will be the following type Query:

type Query { (1)
  DemoGraph: DemoGraph
}
1 Top level query type with a single field named after the graph the service is connected to.

Graph

The graph connected to the service is translated into an Object type in GraphQL, with all vertex types included as fields in top-level type for the entire graph. Each vertex field has five arguments: where, whereExpr, order_by, limit, and offset, which are used for filtering, sorting and pagination.

For example, suppose to have the following schema in TigerGraph:

Example schema
Figure 1. Example schema

The following is a portion of the translated GraphQL schema for the Graph:

type DemoGraph { (1)
  city( (2)
    where: cityFilter
    whereExpr: String
    order_by: cityOrderBy
    limit: Int
    offset: Int
  ): [city]

  person(
    where: personFilter
    whereExpr: String
    order_by: personOrderBy
    limit: Int
    offset: Int
  ): [person]
…
}
1 DemoGraph type contains fields for all vertices, in this case person and city, school, company and skill.
2 Each vertex field has the same arguments: where, whereExpr, order_by, limit, and offset, which are used for filtering, sorting and pagination.

Vertex types

Each vertex type in GSQL will be translated into an Object type in GraphQL. Edge types connected to the vertex type are mapped to fields on the corresponding vertex object. Therefore, the city and person vertex types have the following GraphQL schema.

type person {
  birthYear: Int64 (1)
  gender: String
  height: Float
  id: String
  married: Boolean
  name: String
  born_in(where: born_inFilter, whereExpr: String): [born_in] (2)
  ...
}

type city {
  id: String
  name: String
  population: Int64
  taxRate: Float
  ...
}
1 Vertex type properties in GraphQL are translated to object type fields.
2 Edges are mapped to fields on the corresponding object.

Edge types

Edge types are translated differently depending on whether the edge is directed or undirected.

Directed edges

A directed edge type is translated into a single GraphQL Object type, with properties of the edge type mapped to fields of the edge Object type. In addition, the TO vertex connected to the edge is mapped to a field of the corresponding edge Object type.

For example, if a born_in directed edge type pointing from the person vertex type and to the city vertex type will be translated into the following:

type born_in {
  birthday: Datetime
  to(where: cityFilter, whereExpr: String): city
}

Reverse edges

In GSQL, you can enable WITH REVERSE_EDGE on directed edge types. Doing so creates a directed edge type pointing in the reversed direction of the original edge type, and a prefix rev is added to the name of the edge.

Reverse edges types are treated the same as any other directed edge when translated into GraphQL schema.

Undirected edges

An undirected edge type is translated into two GraphQL Object types, one for each direction. The two Object types are distinguished by a From_<type> prefix to indicate the direction of the edge.

An exception is the case of self-edges, where the FROM and TO vertex types of the edge are the same. In this case, the undirected edge type will be translated into a single Object type, with the vertex type it is connected to mapped to the to field of the edge Object type.

For example, if an undirected partner edge exists between two vertex types company and school, the translated GraphQL Object type will include two Object types:

type From_company_partner {
    to(where: schoolFilter, whereExpr: String): school
}

type From_school_partner {
    to(where: companyFilter, whereExpr: String): company
}

However, if an undirected self-edge is_friend_of exists between person vertices, the edge type will only be translated into a single GraphQL object type.

type is_friend_of {
  to(where: personFilter, whereExpr: String): person
}