Merge pull request #664 from subquery/feedback-2025-08

Clarify documentation based on feedback

Author: stwiname

docs/indexer/build/mapping/cache.md

@@ -6,6 +6,10 @@ This cache is globally accessible and is introduced alongside `logger` and `stor
 
 The cache provides two primary methods for interacting with the cache: `set()` and `get()`. These methods allow you to store data in the cache and retrieve it, respectively.
 
+::: warning Important
+The cache isn't aware of reindexing because of block forks when indexing unfinalized blocks. Make sure the data you store in the cache takes this into consideration.
+:::
+
 Following is a summary of the `Store` interface:
 
 ```ts

docs/indexer/build/mapping/store.md

@@ -1,10 +1,9 @@
 # Advanced Access to the SubQuery Store
 
+The SubQuery SDK will generate classes for your entities with the codegen step. These classes provide a simpler, better typed interface for interacting with the store. However there are times where you may need to access the store directly such as performing bulk operations.
+
 The SubQuery store is an injected class that allows users to interact with records in the database from within mapping functions. This will come handy when user demands using multiple entity records as the parameters in the mapping function, or create/update multiple records in a single place.
 
-::: tip Note
-Note that there are additional methods autogenerated with your entities that also interact with the store. Most users will find those methods sufficient for their projects.
-:::
 
 Following is a summary of the `Store` interface:
 
@@ -63,8 +62,12 @@ This allows you to get a record of the entity with its `id`.
 const id = block.block.header.hash.toString();
 await store.get(`TransactionEntity`, id);
 ```
+## Filtering Records
 
-## Get Records by Fields
+To filter records by fields other than the ID, you NEED to set an [@index](../graphql#indexing) on the field in your GraphQl schema otherwise there will be a runtime error when querying the data.
+Once the index has been added, you can run codegen and it will create convenience methods on your entity classes to filter by fields.
+
+### Get Records by Fields
 
 ```ts
 export type GetOptions<T> = {
@@ -96,15 +99,15 @@ The store has a cache layer in order to increase performance, because of this th
 
 Only fields with an index can be filtered on and an error will be thrown if the fields are not indexed. To add an index the projects graphql schema will need to be updated to include [@index](/build/graphql.html#indexing) decorators.
 
-### Ordering
+#### Ordering
 
 ::: info Note
 Ordering is only available in SDK versions >= 4.0.0
 :::
 
 By default ordering is done by `id` in ascending order.
 
-### Examples
+#### Examples
 
 Using the store directly:
 
@@ -142,7 +145,7 @@ await TransactionEntity.getByFields([["ChainID", "in", [50, 51]]], {
 });
 ```
 
-## Get Records by a Single Field
+### Get Records by a Single Field
 
 ```ts
 export type GetOptions<T> = {
@@ -180,7 +183,7 @@ await store.getByField("TransactionEntity", "ChainID", [50, 100, 150], {
 });
 ```
 
-## Get First Record by Field
+### Get First Record by Field
 
 `getOneByField(entity: string, field: string, value: any): Promise<Entity | undefined>;`
 
@@ -202,7 +205,21 @@ const id = block.block.header.hash.toString();
 await store.set(`TransactionEntity`,id, {ChainID: 50, ...})
 ```
 
-## Bulk Create Records
+## Remove Record
+
+`remove(entity: string, id: string): Promise<void>;`
+
+This allows to remove a single record of the entity with its `id`.
+
+```ts
+const id = block.block.header.hash.toString();
+await store.remove(`TransactionEntity`, id);
+```
+
+## Bulk Operations
+These methods don't offer much in the way for performance improvements by being bulk operations, but they may provide some convenience.
+
+### Bulk Create Records
 
 `bulkCreate(entity: string, data: Entity[]): Promise<void>;`
 
@@ -216,7 +233,7 @@ await store.bulkCreate(`TransactionEntity`,[
 ])
 ```
 
-## Bulk Upsert (Create and Update) Records
+### Bulk Upsert (Create and Update) Records
 
 `bulkUpdate(entity: string, data: Entity[], fields?: string[]): Promise<void>;`
 
@@ -244,18 +261,8 @@ await store.bulkUpdate(`TransactionEntity`,[
 
 Please note, this fields feature is not working currently with any automated historical indexing. It will overwrite all attributes. To disable automated historical indexing, please enable `--disable-historical=true` parameter on `subql-node`.
 
-## Remove Record
-
-`remove(entity: string, id: string): Promise<void>;`
-
-This allows to remove a single record of the entity with its `id`.
-
-```ts
-const id = block.block.header.hash.toString();
-await store.remove(`TransactionEntity`, id);
-```
 
-## Bulk Remove Record
+### Bulk Remove Record
 
 `bulkRemove(entity: string, ids: string[]): Promise<void>;`
 

docs/indexer/miscellaneous/ipfs.md

@@ -43,15 +43,6 @@ Your project should now be ready to deploy via IPFS to the SubQuery network.
 
 ## Publish to IPFS
 
-### Prepare your SUBQL_ACCESS_TOKEN
-
-- Step 1: Go to [OnFinality Indexer Service](https://indexing.onfinality.io/) and log in.
-- Step 2: Click on your profile at the top right of the navigation menu, then click on **_Refresh Token_**.
-- Step 3: Copy the generated token.
-- Step 4: To use this token:
-  - Option 1: Add SUBQL_ACCESS_TOKEN in your environment variables. `EXPORT SUBQL_ACCESS_TOKEN=<token>` (Windows) or `export SUBQL_ACCESS_TOKEN=<token>` (Mac/Linux)
-  - Option 2: Coming soon, `subql/cli` will support storing your SUBQL_ACCESS_TOKEN locally.
-
 ### How to publish a project
 
 Run the following command, which will read the project's default manifest `project.ts` for the required information.