Breaking up creating subgraph flow #811
Conversation
There was a problem hiding this comment.
Splitting up the 'create subgraph' docs this way makes a lot of sense to me. I left a lot of comments on two of the files for places that need more work; I think the other files also need an in-depth review, but those two have already taken quite a bit of time, and we should schedule that one file at a time, but that shouldn't hold up these changes.
website/pages/en/developing/creating-a-subgraph/install-the-cli.mdx
Outdated
Show resolved
Hide resolved
|
|
||
| The [Graph CLI](https://github.com/graphprotocol/graph-tooling/tree/main/packages/cli) is a command-line interface that facilitates developers' commands for The Graph. It processes a [subgraph manifest](/creating-a-subgraph/subgraph-manifest/) and compiles the [mappings](/creating-a-subgraph/assemblyscript-mappings/) to create a ready-to-use version of the subgraph. | ||
|
|
||
| You need The Graph CLI to build and deploy a subgraph. |
There was a problem hiding this comment.
If you go with my suggestion, this becomes redundant
|
|
||
| ### Install the Graph CLI | ||
|
|
||
| The Graph CLI is written in TypeScript, and you must have `node` and either `npm` or `yarn` installed to use it. Check for the [most recent](https://github.com/graphprotocol/graph-tooling/releases?q=%40graphprotocol%2Fgraph-cli&expanded=true) CLI version. |
There was a problem hiding this comment.
This is something that devs with more Javascript experience should weigh in on: we should tell people how to install these things, incuding actual commands to run, for popular platforms, or link to the instructions upstream. As somebody who has little JS experience, I always found these steps very annoying and intimidating.
I've also been using pnpm instead of yarn lately, and it seems nicer/faster. We should have a set of tools that we recommend and where we have good instructions for how to install them, and just mention the other ones.
But all this needs input from people who actually know what they are doing with JavaScript (not me)
|
|
||
| - This `graph init` command can also create a subgraph in Subgraph Studio by passing in `--product subgraph-studio`. | ||
|
|
||
| - If you already have a smart contract deployed to your preferred network, you can bootstrap a new subgraph from that contract to get started. |
There was a problem hiding this comment.
Instead of a bulleted list, I would just make this a paragraph. I would just say that users can create a new subgraph from an existing contract or an example subgraph, and the the following subsections explain the details. I am not sure what the --product subgraph-studio flag is trying to tell me here, and it raises the question of what happens when I don't include that.
Not sure who's best equipped to answer that, either studio folks or Graph CLI devs?
|
|
||
| - The [example subgraph](https://github.com/graphprotocol/example-subgraph) is based on the Gravity contract by Dani Grant, which manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. | ||
|
|
||
| - The subgraph handles these events by writing `Gravatar` entities to the Graph Node store and ensuring these are updated according to the events. |
There was a problem hiding this comment.
That's more for devrel: we should have a better example subgraph than the Gravatar. The example should show off some best practices, and be heavily commented and explain what the various constructs do and in what situation they are needed.
| - All queries will be made against the data model defined in the subgraph schema and the entities indexed by the subgraph. As a result, it is good to define the subgraph schema in a way that matches the needs of your dapp. | ||
| - It may be useful to imagine entities as "objects containing data", rather than as events or functions. | ||
| - You 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 should be an entity is required to be annotated with an `@entity` directive. |
There was a problem hiding this comment.
Since spec version 1.1.0, types can also have a @aggregation annotation instead of @entity. This section needs to be rewritten to better reflect what kinds of types can be defined and how they work.
Feel free to hound me to provide something there.
There was a problem hiding this comment.
@lutter Will do when I start detailed edits 😃
| - Mutability comes at a price, so for entity types that will never be modified, such as those containing data extracted verbatim from the chain, it is recommended to mark them as immutable with `@entity(immutable: true)`. | ||
| - If changes happen in the same block in which the entity was created, then mappings can make changes to immutable entities. Immutable entities are much faster to write and to query so they should be used whenever possible. | ||
|
|
||
| #### Good Example |
There was a problem hiding this comment.
This section was written as a bit of a knee-jerk reaction to people creating lots of subgraphs that just stored events. I am not sure we need to give this example that much room.
|
|
||
| Each entity must have an `id` field, which must be of type `Bytes!` or `String!`. It is generally recommended to use `Bytes!`, unless the `id` contains human-readable text, since entities with `Bytes!` id's will be faster to write and query as those with a `String!` `id`. The `id` field serves as the primary key, and needs to be unique among all entities of the same type. For historical reasons, the type `ID!` is also accepted and is a synonym for `String!`. | ||
|
|
||
| For some entity types the `id` is constructed from the id's of two other entities; that is possible using `concat`, e.g., `let id = left.id.concat(right.id) ` to form the id from the id's of `left` and `right`. Similarly, to construct an id from the id of an existing entity and a counter `count`, `let id = left.id.concatI32(count)` can be used. The concatenation is guaranteed to produce unique id's as long as the length of `left` is the same for all such entities, for example, because `left.id` is an `Address`. |
There was a problem hiding this comment.
This needs to make it clearer that we are talking about id's of type Bytes here.
…aking-up-creating-subgraph-flow
install-the-cli;subgraph-manifest;ql-schema;assemblyscript-mappings;advancedinstall-the-cli&ql-schemahave content with some feedback implemented