Skip to content

Commit

Permalink
re: #643 -- s/index/indexer, where appropriate
Browse files Browse the repository at this point in the history
  • Loading branch information
deekerno committed Mar 13, 2023
1 parent 302c8d1 commit 11079e3
Show file tree
Hide file tree
Showing 21 changed files with 72 additions and 72 deletions.
30 changes: 15 additions & 15 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,15 +189,15 @@ You should see output indicating the successful creation of a database and start

> You can `Ctrl+C` to exit the `forc index start` process, and your indexer service and database should still be running in the background.
### 2.3 Creating a new index
### 2.3 Creating a new indexer

Now that we have our development environment set up, the next step is to create an index.
Now that we have our development environment set up, the next step is to create an indexer.

```bash
forc index new hello-index --namespace my_project && cd hello-index
```

> The `namespace` of your project is a required option. You can think of a `namespace` as your organization name or company name. Your index project might contain one or many indices all under the same `namespace`.
> The `namespace` of your project is a required option. You can think of a `namespace` as your organization name or company name. Your project might contain one or many indexers all under the same `namespace`.
```text
forc index new hello-index --namespace my_project
Expand Down Expand Up @@ -243,11 +243,11 @@ Take a quick tour.
Stop a running index.
```

> IMPORTANT: If you want more details on how this index works, check out our [block explorer index example](https://fuellabs.github.io/fuel-indexer/master/examples/block-explorer.html).
> IMPORTANT: If you want more details on how this indexer works, check out our [block explorer indexer example](https://fuellabs.github.io/fuel-indexer/master/examples/block-explorer.html).
### 2.4 Deploying our index
### 2.4 Deploying our indexer

At this point, we have a brand new index that will index some blocks and transactions. And with our database and Fuel indexer service up and running, all that's left is to build and deploy the index in order to see it in action. but now we need to build and deploy it in order to see it in action.
At this point, we have a brand new indexer that will index some blocks and transactions. And with our database and Fuel indexer service up and running, all that's left is to build and deploy the indexer in order to see it in action. but now we need to build and deploy it in order to see it in action.

```bash
forc index deploy --manifest hello_index.manifest.yaml
Expand All @@ -259,7 +259,7 @@ If all goes well, you should see the following:
▹▹▸▹▹ ⏰ Building... Finished dev [unoptimized + debuginfo] target(s) in 0.87s
▪▪▪▪▪ ✅ Build succeeded.
Deploying index at hello_index.manifest.yaml to http://127.0.0.1:29987/api/index/my_project/hello_index
Deploying indexer at hello_index.manifest.yaml to http://127.0.0.1:29987/api/index/my_project/hello_index
▹▸▹▹▹ 🚀 Deploying...
{
"assets": [
Expand All @@ -284,12 +284,12 @@ Deploying index at hello_index.manifest.yaml to http://127.0.0.1:29987/api/index
],
"success": "true"
}
▪▪▪▪▪ ✅ Successfully deployed index.
▪▪▪▪▪ ✅ Successfully deployed indexer.
```

## 3. Querying for data

With our index deployed, we should be able to query for newly indexed data after a few seconds.
With our indexer deployed, we should be able to query for newly indexed data after a few seconds.

Below, we write a simple GraphQL query that simply returns a few fields from all transactions that we've indexed.

Expand Down Expand Up @@ -322,7 +322,7 @@ curl -X POST http://127.0.0.1:29987/api/graph/my_project/hello_index \

### Finished! 🥳

Congrats, you just created, built, and deployed your first index on the world's fastest execution layer. For more detailed info on how the Fuel indexer service works, make sure you [**read the book**](https://fuellabs.github.io/fuel-indexer/master/).
Congrats, you just created, built, and deployed your first indexer on the world's fastest execution layer. For more detailed info on how the Fuel indexer service works, make sure you [**read the book**](https://fuellabs.github.io/fuel-indexer/master/).

## `forc-index` Plugin

Expand All @@ -342,31 +342,31 @@ forc index check

### `forc index new`

Create new index project at the provided path.
Create new indexer project at the provided path.

```bash
forc index new --namespace my_org_name
```

### `forc index init`

Create a new index project at the provided path. If no path is provided the current working directory will be used.
Create a new indexer project at the provided path. If no path is provided the current working directory will be used.

```bash
forc index init --namespace my_org_name
```

### `forc index build`

Build the index in the current directory.
Build the indexer in the current directory.

```bash
forc index build --manifest my_index.manifest.yaml
```

### `forc index deploy`

Deploy a given index project to a particular endpoint
Deploy a given indexer project to a particular endpoint

```bash
forc index deploy --url https://index.swaysway.io --manifest my_index.manifest.yaml
Expand Down Expand Up @@ -447,7 +447,7 @@ At this time, the Fuel indexer requires the use of a database. We currently supp

> Note: The following explanation is for demonstration purposes only. A production setup should use secure users, permissions, and passwords.

On macOS systems, you can install PostgreSQL through Homebrew. If it isn't present on your system, you can install it according to the [instructions](https://brew.sh/). Once installed, you can add PostgreSQL to your system by running `brew install postgresql`. You can then start the service through `brew services start postgresql`. You'll need to create a database for your index data, which you can do by running `createdb [DATABASE_NAME]`. You may also need to create the `postgres` role; you can do so by running `createuser -s postgres`.
On macOS systems, you can install PostgreSQL through Homebrew. If it isn't present on your system, you can install it according to the [instructions](https://brew.sh/). Once installed, you can add PostgreSQL to your system by running `brew install postgresql`. You can then start the service through `brew services start postgresql`. You'll need to create a database for your indexed data, which you can do by running `createdb [DATABASE_NAME]`. You may also need to create the `postgres` role; you can do so by running `createuser -s postgres`.

For Linux-based systems, the installation process is similar. First, you should install PostgreSQL according to your distribution's instructions. Once installed, there should be a new `postgres` user account; you can switch to that account by running `sudo -i -u postgres`. After you have switched accounts, you may need to create a `postgres` database role by running `createuser --interactive`. You will be asked a few questions; the name of the role should be `postgres` and you should elect for the new role to be a superuser. Finally, you can create a database by running `createdb [DATABASE_NAME]`.

Expand Down
2 changes: 1 addition & 1 deletion docs/src/for-contributors/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ At this time, the Fuel indexer requires the use of a database. We currently supp

> Note: The following explanation is for demonstration purposes only. A production setup should use secure users, permissions, and passwords.
On macOS systems, you can install PostgreSQL through Homebrew. If it isn't present on your system, you can install it according to the [instructions](https://brew.sh/). Once installed, you can add PostgreSQL to your system by running `brew install postgresql`. You can then start the service through `brew services start postgresql`. You'll need to create a database for your index data, which you can do by running `createdb [DATABASE_NAME]`. You may also need to create the `postgres` role; you can do so by running `createuser -s postgres`.
On macOS systems, you can install PostgreSQL through Homebrew. If it isn't present on your system, you can install it according to the [instructions](https://brew.sh/). Once installed, you can add PostgreSQL to your system by running `brew install postgresql`. You can then start the service through `brew services start postgresql`. You'll need to create a database for your indexed data, which you can do by running `createdb [DATABASE_NAME]`. You may also need to create the `postgres` role; you can do so by running `createuser -s postgres`.

For Linux-based systems, the installation process is similar. First, you should install PostgreSQL according to your distribution's instructions. Once installed, there should be a new `postgres` user account; you can switch to that account by running `sudo -i -u postgres`. After you have switched accounts, you may need to create a `postgres` database role by running `createuser --interactive`. You will be asked a few questions; the name of the role should be `postgres` and you should elect for the new role to be a superuser. Finally, you can create a database by running `createdb [DATABASE_NAME]`.

Expand Down
4 changes: 2 additions & 2 deletions docs/src/getting-started/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,6 @@ The Fuel indexer is meant to run alongside a Fuel node and a database. Generally

1. A Sway smart contract emits receipts during its execution on the Fuel node.
2. Blocks, transactions, and receipts from the node are monitored by the Fuel indexer service and checked for specific user-defined event types.
3. When a specific event type is found, the indexer executes the corresponding handler from an index module.
4. The handler processes the event and stores the index information in the database.
3. When a specific event type is found, the indexer executes the corresponding handler from an indexer module.
4. The handler processes the event and stores the indexed information in the database.
5. A dApp queries for blockchain data by using the indexer's GraphQL API endpoint, which fetches the desired information from the corresponding index in the database and returns it to the user.
2 changes: 1 addition & 1 deletion docs/src/getting-started/starting-the-fuel-indexer.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ OPTIONS:
[possible values: info, debug, error, warn]
-m, --manifest <MANIFEST>
Index config file.
Indexer config file.
--max-body <MAX_BODY>
Max body size for WASM binary uploads in bytes. [default: 5242880]
Expand Down
6 changes: 3 additions & 3 deletions docs/src/reference-guide/components/assets/index.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Assets

A Fuel index is constructed of a few assets: a manifest file, a GraphQL schema file, and a WASM module.
An indexer is constructed of a few assets: a manifest file, a GraphQL schema file, and a WASM module.

- [Manifest](./manifest.md)
- Supplies metadata regarding how a given index should be built and run.
- Supplies metadata regarding how a given indexer should be built and run.
- [Schema](./schema.md)
- A GraphQL schema file that defines your index data model via GraphQL types.
- [Module](./module.md)
- A compiled WASM binary index that gets registered into a Fuel indexer at runtime.
- An executor that gets registered into a Fuel indexer at runtime.
12 changes: 6 additions & 6 deletions docs/src/reference-guide/components/assets/manifest.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Manifest

A manifest serves as the YAML configuration file for a given index. A proper manifest has the following structure:
A manifest serves as the YAML configuration file for a given indexer. A proper manifest has the following structure:

```yaml
namespace: fuel
Expand All @@ -16,26 +16,26 @@ report_metrics: true
## `namespace`

- Think of the `namespace` as an organization identifier. If you're familiar with say, [Java package naming](https://stackoverflow.com/questions/6247849/java-package-naming), then think of an index's `namespace` as being its _domain name_. The `namespace` is unique to a given index operator -- i.e., index operators will not be able to support more than one `namespace` of the same name.
- Think of the `namespace` as an organization identifier. If you're familiar with say, [Java package naming](https://stackoverflow.com/questions/6247849/java-package-naming), then think of an indexer's `namespace` as being its _domain name_. The `namespace` is unique to a given indexer operator -- i.e., indexer operators will not be able to support more than one `namespace` of the same name.

## `identifier`

- The `identifier` field is used to (quite literally) identify the given index. If `namespace` is the organization/domain name, then think of `identifier` as the name of an index within that organization/domain.
- As an example, if a provided `namespace` is `"fuel"` and a provided `identifier` is `"index1"`, then the unique identifier for the given index will be `fuel.index1`.
- The `identifier` field is used to (quite literally) identify the given indexer. If `namespace` is the organization/domain name, then think of `identifier` as the name of an indexer within that organization/domain.
- As an example, if a provided `namespace` is `"fuel"` and a provided `identifier` is `"index1"`, then the unique identifier for the given indexer will be `fuel.index1`.

## `abi`

- The `abi` option is used to provide a link to the Sway JSON application binary interface (JSON ABI) that is generated when you build your Sway project. This generated ABI contains all types, type IDs, and logged types used in your Sway contract.

## `contract_id`

- The `contract_id` specifies which particular contract you would like your index to subscribe to. Setting this field to an empty string will index events from any contract that is currently executing on the network.
- The `contract_id` specifies which particular contract you would like your indexer to subscribe to. Setting this field to an empty string will index events from any contract that is currently executing on the network.

> Important: Contract IDs are unique to the content of a contract. If you are subscribing to a certain contract and then the contract itself is changed or updated, you will need to change the `contract_id` field of the manifest to the new ID.

## `graphql_schema`

- The `graphql_schema` field contains the file path that points to the GraphQL schema for the given index. This schema file holds the structures of the data that will eventually reside in your database. You can read more about the format of the schema file [here](schema.md).
- The `graphql_schema` field contains the file path that points to the GraphQL schema for the given indexer. This schema file holds the structures of the data that will eventually reside in your database. You can read more about the format of the schema file [here](./schema.md).

> Important: The objects defined in your GraphQL schema are called 'entities'. These entities are what will be eventually be stored in the database.

Expand Down
4 changes: 2 additions & 2 deletions docs/src/reference-guide/components/assets/module.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,13 @@ instance.save();

## Usage

To compile your index code to WASM, you'll first need to install the `wasm32-unknown-unknown` target platform through `rustup`, if you haven't done so already.
To compile your indexer code to WASM, you'll first need to install the `wasm32-unknown-unknown` target platform through `rustup`, if you haven't done so already.

```bash
rustup add target wasm32-unknown-unknown
```

After that, you would compile your index code by navigating to the root folder for your index code and build. An example of this can be found below:
After that, you would compile your indexer code by navigating to the root folder for your indexer code and build. An example of this can be found below:

```bash
cd /my/index-lib && cargo build --release
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,6 @@ Finally, you can run the Fuel indexer as part of a project that uses other compo

Every Fuel indexer project requires three components:

- a [Manifest](../components/assets/manifest.md) describing index metadata
- a [Manifest](../components/assets/manifest.md) describing indexer metadata
- a [Schema](../components/assets/schema.md) containing models for the data you want to index
- an [Execution Module](../components/assets/module.md) which houses the logic for creating the aforementioned data models
4 changes: 2 additions & 2 deletions docs/src/reference-guide/components/graphql/directives.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Using our `Library` and `Book` example from the previous [Foreign Keys](../datab

## `@indexed`

The `@indexed` directive adds an index to the underlying database column for the indicated field of that type. Generally, an index is a data structure that allows you to quickly locate data without having to search each row in a database table.
The `@indexed` directive adds a database index to the underlying column for the indicated field of that type. Generally, a database index is a data structure that allows you to quickly locate data without having to search each row in a database table.

```graphql
schema {
Expand All @@ -37,7 +37,7 @@ type Library {

In this example, a single `BTREE INDEX` constraint will be created on the `book` table's `name` column, which allows for faster lookups on that field.

> Important: At the moment, index constraint support is limited to `BTREE` in Postgres with `ON DELETE`, and `ON UPDATE` actions not being supported.
> Important: At the moment, database index constraint support is limited to `BTREE` in Postgres with `ON DELETE`, and `ON UPDATE` actions not being supported.

## `@unique`

Expand Down
6 changes: 3 additions & 3 deletions docs/src/reference-guide/components/graphql/schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ types can be found in [the Types section](../../data-types/types.md).

## Required and Optional Fields

Required fields are denoted with a `!` following its type; for example, the `value` field of the `FirstThing` type is a `UInt8` and is required to be present for the index to successfully persist the entity. If a certain piece of information is essential to your use case, then you should mark that field as required.
Required fields are denoted with a `!` following its type; for example, the `value` field of the `FirstThing` type is a `UInt8` and is required to be present for the indexer to successfully persist the entity. If a certain piece of information is essential to your use case, then you should mark that field as required.

In contrast, optional fields are not required to be present for the index to persist the entity in storage. You can denote an optional field by just using the type name; for example, the `optional_value` field of the `SecondThing` type is optional, and should be a `UInt8` if present. If it's possible that a value might not always exist in the data you wish to index, consider making that the corresponding field optional. In your index code, you will need to use the `Option` Rust type when assigning a value to an optional field; values that are present should be assigned after being wrapped in `Some(..)` while absent values should be assigned using `None`.
In contrast, optional fields are not required to be present for the indexer to persist the entity in storage. You can denote an optional field by just using the type name; for example, the `optional_value` field of the `SecondThing` type is optional, and should be a `UInt8` if present. If it's possible that a value might not always exist in the data you wish to index, consider making that the corresponding field optional. In your indexer code, you will need to use the `Option` Rust type when assigning a value to an optional field; values that are present should be assigned after being wrapped in `Some(..)` while absent values should be assigned using `None`.

> Important: The `ID` field is _always_ required. An index **will** return an error if an optional value is used for the `ID` field.
> Important: The `ID` field is _always_ required. An indexer **will** return an error if an optional value is used for the `ID` field.
2 changes: 1 addition & 1 deletion docs/src/reference-guide/components/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@ Understanding how these components interact is critical to understanding how to
- [Database](./database/index.md)
- [Fuel Node](./fuel-node.md)
- [GraphQL API](./graphql/index.md)
- [Indices](./indices/index.md)
- [Indexers](./indexers/index.md)
8 changes: 8 additions & 0 deletions docs/src/reference-guide/components/indexers/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Indexers

Indices are the one of the core building blocks of the Fuel indexer service. Indices allow indexer operators and dApp authors to index specific blockchain events into a database.

A given indexer is constructed of a few assets: a manifest file, a GraphQL schema file, and a WASM module. Read more about this in the [Assets](./../assets/index.md) section.

- [Registering Indices](./registration.md)
- How to register a new indexer with a Fuel indexer service
Loading

0 comments on commit 11079e3

Please sign in to comment.