GraphQL Schema

2021-10-17 About 4 min

# GraphQL Schema

# Defining Entities

The schema.graphql file defines the various GraphQL schemas. Due to the way that the GraphQL query language works, the schema file essentially dictates the shape of your data from SubQuery. To learn more about how to write in GraphQL schema language, we recommend checking out Schemas and Types (opens new window).

Important: When you make any changes to the schema file, please ensure that you regenerate your types directory with the following command yarn codegen

# Entities

Each entity must define its required fields id with the type of ID!. It is used as the primary key and unique among all entities of the same type.

Non-nullable fields in the entity are indicated by !. Please see the example below:

type Example @entity {
  id: ID! # id field is always required and must look like this
  name: String! # This is a required field
  address: String # This is an optional field
}
1
2
3
4
5

# Supported scalars and types

We currently supporting flowing scalars types:

  • ID
  • Int
  • String
  • BigInt
  • Date
  • Boolean
  • <EntityName> for nested relationship entities, you might use the defined entity's name as one of the fields. Please see in Entity Relationships.
  • JSON can alternatively store structured data, please see JSON type

# Indexing by non-primary-key field

To improve query performance, index an entity field simply by implementing the @index annotation on a non-primary-key field.

However, we don't allow users to add @index annotation on any JSON object. By default, indexes are automatically added to foreign keys and for JSON fields in the database, but only to enhance query service performance.

Here is an example.

type User @entity {
  id: ID!
  name: String! @index(unique: true) # unique can be set to true or false
  title: Title! # Indexes are automatically added to foreign key field 
}

type Title @entity {
  id: ID!  
  name: String! @index(unique:true)
}
1
2
3
4
5
6
7
8
9
10

Assuming we knew this user's name, but we don't know the exact id value, rather than extract all users and then filtering by name we can add @index behind the name field. This makes querying much faster and we can additionally pass the unique: true to ensure uniqueness.

If a field is not unique, the maximum result set size is 100

When code generation is run, this will automatically create a getByName under the User model, and the foreign key field title will create a getByTitleId method, which both can directly be accessed in the mapping function.

/* Prepare a record for title entity */
INSERT INTO titles (id, name) VALUES ('id_1', 'Captain')
1
2
// Handler in mapping function
import {User} from "../types/models/User"
import {Title} from "../types/models/Title"

const jack = await User.getByName('Jack Sparrow');

const captainTitle = await Title.getByName('Captain');

const pirateLords = await User.getByTitleId(captainTitle.id); // List of all Captains
1
2
3
4
5
6
7
8
9

# Entity Relationships

An entity often has nested relationships with other entities. Setting the field value to another entity name will define a one-to-one relationship between these two entities by default.

Different entity relationships (one-to-one, one-to-many, and many-to-many) can be configured using the examples below.

# One-to-One Relationships

One-to-one relationships are the default when only a single entity is mapped to another.

Example: A passport will only belong to one person and a person only has one passport (in this example):

type Person @entity {
  id: ID!
}

type Passport @entity {
  id: ID!
  owner: Person!
}
1
2
3
4
5
6
7
8

or

type Person @entity {
  id: ID!
  passport: Passport!
}

type Passport @entity {
  id: ID!
  owner: Person!
}
1
2
3
4
5
6
7
8
9

# One-to-Many relationships

You can use square brackets to indicate that a field type includes multiple entities.

Example: A person can have multiple accounts.

type Person @entity {
  id: ID!
  accounts: [Account] 
}

type Account @entity {
  id: ID!
  publicAddress: String!
}
1
2
3
4
5
6
7
8
9

# Many-to-Many relationships

A many-to-many relationship can be achieved by implementing a mapping entity to connect the other two entities.

Example: Each person is a part of multiple groups (PersonGroup) and groups have multiple different people (PersonGroup).

type Person @entity {
  id: ID!
  name: String!
  groups: [PersonGroup]
}

type PersonGroup @entity {
  id: ID!
  person: Person!
  Group: Group!
}

type Group @entity {
  id: ID!
  name: String!
  persons: [PersonGroup]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Also, it is possible to create a connection of the same entity in multiple fields of the middle entity.

For example, an account can have multiple transfers, and each transfer has a source and destination account.

This will establish a bi-directional relationship between two Accounts (from and to) through Transfer table.

type Account @entity {
  id: ID!
  publicAddress: String!
}

type Transfer @entity {
  id: ID!
  amount: BigInt
  from: Account!
  to: Account!
}
1
2
3
4
5
6
7
8
9
10
11

# Reverse Lookups

To enable a reverse lookup on an entity to a relation, attach @derivedFrom to the field and point to its reverse lookup field of another entity.

This creates a virtual field on the entity that can be queried.

The Transfer "from" an Account is accessible from the Account entity by setting the sentTransfer or receivedTransfer as having their value derived from the respective from or to fields.

type Account @entity {
  id: ID!
  publicAddress: String!
  sentTransfers: [Transfer] @derivedFrom(field: "from")
  receivedTransfers: [Transfer] @derivedFrom(field: "to")
}

type Transfer @entity {
  id: ID!
  amount: BigInt
  from: Account!
  to: Account!
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# JSON type

We are supporting saving data as a JSON type, which is a fast way to store structured data. We'll automatically generate corresponding JSON interfaces for querying this data and save you time defining and managing entities.

We recommend users use the JSON type in the following scenarios:

  • When storing structured data in a single field is more manageable than creating multiple separate entities.
  • Saving arbitrary key/value user preferences (where the value can be boolean, textual, or numeric, and you don't want to have separate columns for different data types)
  • The schema is volatile and changes frequently

# Define JSON directive

Define the property as a JSON type by adding the jsonField annotation in the entity. This will automatically generate interfaces for all JSON objects in your project under types/interfaces.ts, and you can access them in your mapping function.

Unlike the entity, the jsonField directive object does not require any id field. A JSON object is also able to nest with other JSON objects.

type AddressDetail @jsonField {
  street: String!
  district: String!
}

type ContactCard @jsonField {
  phone: String!
  address: AddressDetail # Nested JSON
}

type User @entity {
  id: ID! 
  contact: [ContactCard] # Store a list of JSON objects
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Querying JSON fields

The drawback of using JSON types is a slight impact on query efficiency when filtering, as each time it performs a text search, it is on the entire entity.

However, the impact is still acceptable in our query service. Here is an example of how to use the contains operator in the GraphQL query on a JSON field to find the first 5 users who own a phone number that contains '0064'.

#To find the the first 5 users own phone numbers contains '0064'.

query{
  user(
    first: 5,
    filter: {
      contactCard: {
        contains: [{ phone: "0064" }]
    }
}){
    nodes{
      id
      contactCard
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Last update: October 17, 2021 08:07