The Subgraph Schema

Let's review.  There are three aspects of subgraph definition.  We covered how the subgraph.yaml manifest file fits into things in the last lesson.  In this one, we'll go over how to build out the entities that define the subgraph schema in schema.graphql.

1. subgraph.yaml - the subgraph manifest.  It defines the data sources of interest and how they should be processed.  NEAR is a new kind of data source.
2. schema.graphql - a schema file that defines what data is stored for your subgraph, and how to query it via GraphQL. 
3. AssemblyScript mapping.ts - AS code that translates from the log data to the entities defined in our schema.  For NEAR, there are NEAR-specific data types and JSON parsing functionality.

schema.graphql

A schema describes the structure of a resulting subgraph database and the relationships between entities.  It doesn't matter what data source is used.  Schemas are built using the GraphQL interface definition language.

It's important to think about how data is structured and linked.  All queries are made against the data model defined in the subgraph schema and the entities indexed by the subgraph.  Thus, it's a good idea to define the subgraph schema to match the needs of your application.  Imagine them as "objects containing data" instead of functions.  You want to structure entities around objects, not events.

We define entity types in schema.graphql and Graph Node will generate top level fields for querying single instances and collections of that entity type.  Each type that is an entity gets annotated with the @entity directive.

For our implementation, this is super straight forward. We simply need an entity that stores all the values of the JSON object that we get from the contract log string so we can then query for them later on in our application. Remember that you or your developer ensured the contract is emitting logs in NEP 171 (JSON) format.

The Graph support for NEAR provides a handy `json.fromString` function you can use. Unless you're going to pass back the entire JSON string and work with it in the frontend, you'll definitely want to break up the object as it unlocks the power of GraphQL queries.

Recall that our DID Registry contract is outputting logs in the following format for the `init` and `putDID` methods.

From our template, we've defined two entities that correspond to the data being returned in those logs - an Account entity that defines a relationship between the account and its logs and a Log entity that contains proper that reflect the types of data that can be extracted from the log JSON object.

Required fields are marked with !.  If it is not set in the mapping, you'll get the following error:

Each entity requires an id field which is of type ID! (string).  This serves as a primary key and must be unique among all entities of the same type.

The GraphQL API supports the following scalars (single-value data types):

Action Steps

With our entities defined, we need to run 'codegen' in order to generate the boilerplate code from the entities.  

The 'codegen' command creates some boilerplate code under the `generated` folder. This boilerplate code defines typescript classes for each `entities` (have a look at `generated/schema.ts`). We will use this code in the next step to define the mappings between our entities and the NEAR contract logs being emitted.

Run 'codegen' like this:

Next Steps

With the schema for our subgraph defined, we're ready to move onto the third and final file - mapping.ts.  You're so very close to building and deploying your first NEAR subgraph.  Keep going - on to mapping.