Skip to content
This repository has been archived by the owner on Oct 25, 2024. It is now read-only.

docs: major documentation update #1312

Merged
merged 33 commits into from
Sep 18, 2023
Merged
Show file tree
Hide file tree
Changes from 31 commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
3aba6aa
Remove outdated 'M1 Docker not supported' blurb
deekerno Aug 25, 2023
1c9d75d
Remove hello world as it's too complicated
deekerno Aug 25, 2023
2074060
Move Queries section under GraphQL section
deekerno Aug 25, 2023
8b03587
Add page for GraphQL scalars
deekerno Aug 25, 2023
f1e3203
Remove database pages; move foreign key page to GraphQL section
deekerno Aug 25, 2023
b2facc8
Move data types section to Database section
deekerno Aug 29, 2023
44b7473
Redo data types table; clean up type sorting
deekerno Aug 29, 2023
b4c06d1
Add info to 'Starting the Fuel Indexer'
deekerno Aug 30, 2023
01e0d5d
Fix doc tests
deekerno Aug 30, 2023
a325b9e
rashad: piggy back on deekerno's doc improvements
Aug 31, 2023
c6e5a58
breakout indexing section
Sep 1, 2023
4f0930a
simplify examples
Sep 1, 2023
f6149ba
update usage
Sep 8, 2023
fb151f5
add types section for gql
Sep 12, 2023
bcf4453
breakout gql queries + remove plugins
Sep 12, 2023
9344418
add comparison chart
Sep 12, 2023
abb8253
Condense receipts section into receipts page to mirror style of specs…
deekerno Sep 12, 2023
4bfda0c
Condense TransactionStatus section into Transactions page
deekerno Sep 12, 2023
dd084f8
Finish 'Indexing Fuel Types section' adjustments
deekerno Sep 12, 2023
b7d90b9
Flatten sections
deekerno Sep 13, 2023
62ae614
Improve Module section
deekerno Sep 13, 2023
3dc9ff2
Add GQL stuff that I accidentally removed ._.
deekerno Sep 15, 2023
6ed30ca
Rename infrastructure page
deekerno Sep 15, 2023
8d0a91e
Adjust sections on GraphQL index page
deekerno Sep 15, 2023
e608bb0
Move api-server.md contents into infrastructure page
deekerno Sep 15, 2023
73af6ac
Add content explaining how to index custom types
deekerno Sep 17, 2023
dc1eeac
Fix doc tests failures
deekerno Sep 17, 2023
17bbba0
up until 'designing a schema'
Sep 18, 2023
e59c723
up to 'storing records' section
Sep 18, 2023
e1151a2
Flesh out comparison page
deekerno Sep 18, 2023
f9d20f8
Fix doc tests failures
deekerno Sep 18, 2023
ca93c3d
Update docs/src/getting-started/dependencies.md
deekerno Sep 18, 2023
eddfab6
Update docs/src/getting-started/indexer-service-infrastructure.md
deekerno Sep 18, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ indexer_net_config: false
# The number of WASM opcodes after which the indexer will stop execution.
metering_points: 30000000000

# Allow the web API to accept raw SQL queries.
# Allow the web server to accept raw SQL queries.
accept_sql_queries: false

# Amount of blocks to return in a request to a Fuel node.
Expand Down Expand Up @@ -64,7 +64,7 @@ web_api:
# Web API port.
port: 29987

# Max body size for web API requests.
# Max body size for web server requests.
max_body_size: "5242880"

# ******************************
Expand Down
65 changes: 27 additions & 38 deletions docs/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,60 +6,49 @@
# Getting Started

- [Dependencies](./getting-started/dependencies.md)
- [Service Infrastructure](./getting-started/indexer-service-infrastructure.md)
- [How it Compares](./getting-started/how-it-compares.md)
- [Quickstart](./getting-started/quickstart.md)
- [Hello World](./getting-started/hello-world.md)
- [Starting the Fuel Indexer](./getting-started/starting-the-fuel-indexer.md)

# Reference Guide

- [Project Components](./project-components/index.md)
- [Manifest](./project-components/manifest.md)
- [Schema](./project-components/schema.md)
- [Module](./project-components/module.md)
- [Indexing](./indexing/index.md)
- [Blocks and Transactions](./indexing/blocks-and-transactions.md)
- [Receipts](./indexing/receipts.md)
- [Burn](./indexing/burn.md)
- [Call](./indexing/call.md)
- [Log](./indexing/log.md)
- [LogData](./indexing/logdata.md)
- [MessageOut](./indexing/messageout.md)
- [Mint](./indexing/mint.md)
- [Panic](./indexing/panic.md)
- [Return](./indexing/return.md)
- [ReturnData](./indexing/returndata.md)
- [Revert](./indexing/revert.md)
- [ScriptResult](./indexing/scriptresult.md)
- [Transfer](./indexing/transfer.md)
- [TransferOut](./indexing/transferout.md)
- [Data Types](./data-types/types.md)
- [GraphQL](./graphql/index.md)
- [Directives](./graphql/directives.md)
- [API Server](./graphql/api-server.md)
- [Playground](./graphql/playground.md)
- [Queries](./queries/index.md)
- [Search and Filtering](./queries/search-filtering.md)
- [Pagination](./queries/pagination.md)
- [A Full Example](./queries/full-example.md)
- [Database](./database/index.md)
- [Foreign Keys](./database/foreign-keys.md)
- [ID Types](./database/ids.md)
- [Designing a Schema](./designing-a-schema/index.md)
- [Types](./designing-a-schema/types.md)
- [Scalars](./designing-a-schema/scalars.md)
- [Directives](./designing-a-schema/directives.md)
- [Relationships](./designing-a-schema/relationships.md)
- [Indexing Fuel Types](./indexing-fuel-types/index.md)
- [Blocks](./indexing-fuel-types/blocks.md)
- [Transactions](./indexing-fuel-types/transactions.md)
- [Receipts](./indexing-fuel-types/receipts.md)
- [Indexing Custom Types](./indexing-custom-types/index.md)
- [Storing Records](./storing-records/index.md)
- [Querying](./querying/index.md)
- [Basic Queries](./querying/basic-queries.md)
- [Playground](./querying/playground.md)
- [Search and Filtering](./querying/search-and-filtering.md)
- [Pagination](./querying/pagination.md)
- [A Full Example](./querying/full-example.md)
- [Authentication](./authentication/index.md)
- [forc index](./forc-index/index.md)
- [new](./forc-index/new.md)
- [check](./forc-index/check.md)
- [auth](./forc-index/auth.md)
- [build](./forc-index/build.md)
- [start](./forc-index/start.md)
- [check](./forc-index/check.md)
- [deploy](./forc-index/deploy.md)
- [remove](./forc-index/remove.md)
- [kill](./forc-index/kill.md)
- [auth](./forc-index/auth.md)
- [new](./forc-index/new.md)
- [remove](./forc-index/remove.md)
- [start](./forc-index/start.md)
- [status](./forc-index/status.md)
- [forc index postgres](./forc-postgres/index.md)
- [forc postgres](./forc-postgres/index.md)
- [create](./forc-postgres/create.md)
- [drop](./forc-postgres/drop.md)
- [start](./forc-postgres/start.md)
- [stop](./forc-postgres/stop.md)
- [drop](./forc-postgres/drop.md)
- [Authentication](./authentication/index.md) -->

# For Contributors

Expand Down
6 changes: 3 additions & 3 deletions docs/src/authentication/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@ The new authentication functionality offers a flexible and secure way for users

## Usage

Below is a demonstration of basic JWT authentication using an indexer operator at "https://beta-3-indexer.fuel.network"
Below is a demonstration of basic JWT authentication using an indexer operator at "https://beta-4-indexer.fuel.network"

```bash
forc index auth --url https://beta-3-indexer.fuel.network:29987
forc index auth --url https://beta-4-indexer.fuel.network:29987
```

You will first be prompted for the password for your wallet:
Expand All @@ -25,7 +25,7 @@ Please enter your wallet password:
After successfully entering your wallet password you should be presented with your new JWT token.

```text
✅ Successfully authenticated at https://beta-3-indexer.fuel.network:29987/api/auth/signature.
✅ Successfully authenticated at https://beta-4-indexer.fuel.network:29987/api/auth/signature.

Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiODNlNjhiOTFmNDhjYWM4M....
```
Expand Down
60 changes: 0 additions & 60 deletions docs/src/data-types/types.md

This file was deleted.

18 changes: 0 additions & 18 deletions docs/src/database/ids.md

This file was deleted.

10 changes: 0 additions & 10 deletions docs/src/database/index.md

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,9 @@

As of this writing, the list of supported Fuel GraphQL schema directives includes:

- `@indexed`
- `@unique`
- `@join`
- `@virtual`
- `@indexed`: Denotes that a field should include a B-tree index in the database.
- `@unique`: Denotes that field should include a unique index in the database.
- `@join`: Denotes that a field has a "relationship" to another object type.

## `@indexed`

Expand Down Expand Up @@ -65,23 +64,4 @@ type Library @entity {
}
```

A foreign key constraint will be created on `library.book` that references `book.name`, which relates the `Book`s in a `Library` to the underlying `Book` table.

## `@virtual`

The `@virtual` directive instructs the indexer's SQL schema builder to _not_ build SQL tables from types that include this directive on any field.

```graphql
type Title @entity {
name: CharField! @virtual
}

type Book @entity {
id: ID!
title: Title!
}
```

When SQL tables are generated for the entities above, a table will be created for `Book`, but no table will be created for `Title`. Rather, the `title` field on the `Book` object will exist on the `book` table as a `JSON` field.

> Important: When using the `@virtual` directive with GraphQL `union` types, each member of the `union` type must either include _only_ types that are not virtual, or _only_ types that are virtual. We do not support mixing and matching virtual types with non-virtual types in unions.
A foreign key constraint will be created on `library.book` that references `book.name`, which relates the `Book`s in a `Library` to the underlying `Book` table. For more info on what exactly is happening here, please see the [Relationships](./relationships.md) section.
39 changes: 39 additions & 0 deletions docs/src/designing-a-schema/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Designing a Schema

The Fuel indexer uses GraphQL in order to allow users to query for indexed data. In this chapter, you can find information on how to leverage our supported features to efficiently get the data you want.

> ⚠️ Please note that the Fuel indexer does not support the full GraphQL specification; however, we do our best to reasonably support as much as we can.

- [Types](./types.md)
- [Scalars](./scalars.md)
- [Directives](./directives.md)
- [Relationships](./relationships.md)

## Supported Functionality

While we do our best to maintain compliance with the GraphQL specification and parity with other implementations, there are a few things that are under development or will not be implemented. Here's a table describing our GraphQL functionality:

Legend:

- 🟩 : Functionally complete
- 🟨 : Partially complete
- 🟥 : Planned but incomplete
- ⛔ : Not planned

| Functionality | Status | Notes |
|------|----------|-------|
| Arguments | 🟩 | [read the Search and Filtering section](../querying/search-and-filtering.md) |
| Aliases | 🟩 | |
| Fragments | 🟨 | inline fragments are currently not supported |
| Introspection | 🟩 | |
| GraphQL Playground | 🟩 | [read the Playground section](../querying/playground.md) |
| Pagination | 🟨 | [read the Pagination section](../querying/pagination.md) |
| Directives |🟨 | [read the Directives section](./directives.md) |
| List Types |🟨 | |
| Union Types |🟨 | |
| Federation |⛔ | |
| Variables | ⛔ | |
| Mutations | ⛔ | |
| Enums | 🟨 | |
| Interfaces | ⛔ | |
| Input Types| ⛔ | |
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
# Foreign Keys
# Relationships

- The Fuel indexer service supports foreign key constraints and relationships using a combination of GraphQL schema and a database.
- There are two types of uses for foreign keys - _implicit_ and _explicit_.
The Fuel indexer service supports foreign key relationships and constraints. There are two types of relationship specifications: _implicit_ and _explicit_.

> IMPORTANT:
>
Expand All @@ -18,35 +17,31 @@ Let's learn how to use each foreign key type by looking at some GraphQL schema e
### Implicit foreign keys

```graphql
type Book @entity {
type Library @entity {
id: ID!
name: Bytes8!
name: Charfield!
}

type Library @entity {
type Book @entity {
id: ID!
book: Book!
library: Library!
}
```

#### Implicit foreign key breakdown

Given the above schema, two entities will be created: a `Book` entity, and a `Library` entity. As you can see, we add the `Book` entity as an attribute on the `Library` entity, thus conveying that we want a one-to-many or one-to-one relationship between `Library` and `Book`. This means that for a given `Library`, we may also fetch one or many `Book` entities. It also means that the column `library.book` will be an integer type that references `book.id`.
Given the above schema, two entities will be created: a `Book` entity, and a `Library` entity. As you can see, we add the `Book` entity as an attribute on the `Library` entity, thus conveying that we want a one-to-many or one-to-one relationship between `Library` and `Book`. This means that for a given `Book`, we may also fetch the associated `Library` entity. It also means that the field `Book.library` will be an `ID` scalar type that references `Library.id`.

### Explicit foreign keys

```graphql
type Book @entity {
type Library @entity {
id: ID!
name: Bytes8! @unique
name: Charfield! @unique
}

type Library @entity {
type Book @entity {
id: ID!
book: Book! @join(on:name)
library: Library! join(on:name)
}
```

#### Explicit foreign key breakdown

For the most part, this works the same way as implicit foreign key usage. However, as you can see, instead of implicitly using `book.id` as the reference column for our `Book` object, we're instead explicitly specifying that we want `book.name` to serve as our foreign key. Also, please note that since we're using `book.name` in our foreign key constraint, that column is required to be unique (via the `@unique` directive).
For the most part, this works the same way as implicit foreign key usage. However, as you can see, instead of implicitly using `Library.id` as the reference column for our `Library` field type on the `Book` object, we're _explicitly_ specifying that we want `Library.name` to serve as our foreign key for the `Book.library` field. Also, please note that since we're using `Library.name` in our foreign key constraint, that column is required to be unique (via the `@unique` directive).
36 changes: 36 additions & 0 deletions docs/src/designing-a-schema/scalars.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Scalars

The Fuel indexer has a collection of GraphQL scalars that cover virtually any value type in use on the Fuel network. The following list contains each GraphQL scalar type along with its equivalent Rust type.

| GraphQL Scalar | Rust Type | Notes |
--- | --- | ---
| Address | `u8[32]` |
| AssetId | `u8[32]` |
| Blob | `Vec<u8>` | Byte blob of arbitary size |
| BlockId | `u8[32]` | 32-byte block ID |
| Boolean | `bool` |
| Bytes4 | `u8[4]` |
| Bytes8 | `u8[8]` |
| Bytes32 | `u8[32]` |
| Bytes64 | `u8[64]` |
| Charfield | `String` | String of arbitrary size |
| ContractId | `u8[32]` |
| HexString | `Vec<u8>` | Byte blob of arbitrary size |
| ID | `SizedAsciiString<64>` | Alias of `UID`
| Int1 | `i8` |
| Int4 | `i32` |
| Int8 | `i64` |
| Int16 | `i128` |
| Json | `String` | JSON string of arbitary size |
| MessageId | `u8[32]` |
| Nonce | `u8[32]` |
| Salt | `u8[32]` |
| Signature | `u8[64]` | 64-byte signature |
| Tai64Timestamp | `Tai64` | `Tai64` timestamp |
| Timestamp | `u64` |
| UID | `SizedAsciiString<64>` | 32-byte unique ID |
| UInt1 | `u8` |
| UInt4 | `u32` |
| UInt8 | `u64` |
| UInt16 | `u128` |
| Virtual | `String` | Used to store types tagged with `@virtual` directive |
Loading