docs: major documentation update (#1312)

* Remove outdated 'M1 Docker not supported' blurb * Remove hello world as it's too complicated * Move Queries section under GraphQL section * Add page for GraphQL scalars * Remove database pages; move foreign key page to GraphQL section * Move data types section to Database section * Redo data types table; clean up type sorting * Add info to 'Starting the Fuel Indexer' * Fix doc tests * rashad: piggy back on deekerno's doc improvements * breakout indexing section * simplify examples * update usage * add types section for gql * breakout gql queries + remove plugins * add comparison chart * Condense receipts section into receipts page to mirror style of specs page * Condense TransactionStatus section into Transactions page * Finish 'Indexing Fuel Types section' adjustments * Flatten sections * Improve Module section * Add GQL stuff that I accidentally removed ._. * Rename infrastructure page * Adjust sections on GraphQL index page * Move api-server.md contents into infrastructure page * Add content explaining how to index custom types * Fix doc tests failures * up until 'designing a schema' * up to 'storing records' section * Flesh out comparison page * Fix doc tests failures * Update docs/src/getting-started/dependencies.md Co-authored-by: Maciej Woś <[email protected]> * Update docs/src/getting-started/indexer-service-infrastructure.md Co-authored-by: Maciej Woś <[email protected]> --------- Co-authored-by: Rashad Alston <[email protected]> Co-authored-by: Maciej Woś <[email protected]>
FuelLabs · Sep 18, 2023 · 145570b · 145570b
1 parent 1b345b0
commit 145570b
Show file tree

Hide file tree

Showing 81 changed files with 1,748 additions and 1,063 deletions.
diff --git a/config.yaml b/config.yaml
@@ -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.
@@ -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"
 
 # ******************************

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -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
 

diff --git a/docs/src/authentication/index.md b/docs/src/authentication/index.md
@@ -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:
@@ -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....
 ```

diff --git a/docs/src/data-types/types.md b/docs/src/data-types/types.md
diff --git a/docs/src/database/ids.md b/docs/src/database/ids.md
diff --git a/docs/src/database/index.md b/docs/src/database/index.md
diff --git a/docs/src/graphql/directives.md → docs/src/designing-a-schema/directives.md b/docs/src/graphql/directives.md → docs/src/designing-a-schema/directives.md
@@ -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`
 
@@ -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.
diff --git a/docs/src/designing-a-schema/index.md b/docs/src/designing-a-schema/index.md
@@ -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| ⛔ | |
diff --git a/docs/src/database/foreign-keys.md → docs/src/designing-a-schema/relationships.md b/docs/src/database/foreign-keys.md → docs/src/designing-a-schema/relationships.md
@@ -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:
 >
@@ -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).
diff --git a/docs/src/designing-a-schema/scalars.md b/docs/src/designing-a-schema/scalars.md
@@ -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 |