Grafting instructions

gistfile1.txt

## Grafting onto Existing Subgraphs

When a subgraph is first deployed, it starts indexing events at the genesis block
of the corresponding chain (or at the `startBlock` defined with each data source)
In some circumstances, it is beneficial to reuse the data from an existing
subgraph and start indexing at a much later block. This mode of indexing is
called _Grafting_. Grafting is, for example, useful during development to get
past simple errors in the mappings quickly, or to temporarily get an existing
subgraph working again after it has failed.

A subgraph is grafted onto a base subgraph when the subgraph manifest in
`subgraph.yaml` contains a `graft` block at the toplevel:
```yaml
description: ...
graft:
  base: Qm...      # Subgraph ID of base subgraph
  block: 7345624   # Block number
```

When a subgraph whose manifest contains a `graft` block is deployed, Graph Node
will copy the data of the `base` subgraph up to and including the given `block`
and then continue indexing the new subgraph from that block on. The base subgraph
must exist on the target Graph Node instance and must have indexed up to at least
the given block. Because of this restriction, grafting should only be used during
development or during an emergency to speed up producing an equivalent non-grafted
subgraph.

Because grafting copies rather than indexes base data it is much quicker in
getting the subgraph to the desired block than indexing from scratch, though
the initial data copy can still take several hours for very large subgraphs.
While the grafted subgraph is being initialized, the Graph Node will log
information about the entity types that have already been copied.

The grafted subgraph can use a GraphQL schema that is not identical to the one
of the base subgraph, but merely compatible with it. It has to be a valid
subgraph schema in its own right but may deviate from the base subgraph's
schema in the following ways:

* It adds or removes entity types
* It removes attributes from entity types
* It adds nullable attributes to entity types
* It turns non-nullable attributes into nullable attributes
* It adds values to enums
* It adds or removes interfaces
* It changes for which entity types an interface is implemented