From 5bc280c93f88e44dcc7d06a9303c70400269a573 Mon Sep 17 00:00:00 2001 From: James Bayly Date: Thu, 14 Sep 2023 20:56:42 +0800 Subject: [PATCH] Update Store Docs --- docs/build/mapping/store.md | 90 +++++++++++++++++++++---------------- 1 file changed, 52 insertions(+), 38 deletions(-) diff --git a/docs/build/mapping/store.md b/docs/build/mapping/store.md index 5b1fe236216..bec9dd5664b 100644 --- a/docs/build/mapping/store.md +++ b/docs/build/mapping/store.md @@ -19,8 +19,12 @@ export interface Store { ): Promise; getByFields( entity: string, - filter: [field: keyof T, operator: '=' | '!=' | 'in' | '!in', value: T[keyof T] | Array][], - options?: {offset?: number; limit?: number} + filter: [ + field: keyof T, + operator: "=" | "!=" | "in" | "!in", + value: T[keyof T] | Array + ][], + options?: { offset?: number; limit?: number } ): Promise; getOneByField( entity: string, @@ -40,7 +44,7 @@ export interface Store { } ``` -## Get Record +## Get Record by ID `get(entity: string, id: string): Promise;` @@ -48,30 +52,31 @@ This allows you to get a record of the entity with its `id`. ```typescript const id = block.block.header.hash.toString(); -await store.get(`StarterEntity`, id); +await store.get(`TransactionEntity`, id); ``` -## Get Records by Field +## Get Records by a Single Field `getByField(entity: string, field: string, value: any, options?: { limit?: number; offset?: number }): Promise;` -This returns matching records for the specific entity that matches a given search. By default it will return the first 100 results. +This returns matching records for the specific entity that matches an equality comparison. By default it will return the first 100 results. The number of results can be changed via the `query-limit` flag for the node or via the options field. If you need more than the number of results provided you can also specify an `offset` and page your results. ```typescript -// Get all records with field1 == 50 -await store.getByField(`StarterEntity`, "field1", 50); +// Get all records with ChainID == 50 +await store.getByField(`TransactionEntity`, "ChainID", 50); ``` Please note, the third parameter also accepts array, you can consider this similar like `bulkGet` with OR search. -To get a list of records with `field1` equal to 50, 100 or 150: +To get a list of records with `ChainID` equal to 50, 100 or 150: ```typescript -// Get all records with field1 == 50 OR field1 == 100 OR field1 == 150 -await store.getByField("StarterEntity", "field1", [50, 100, 150]); +// Get all records with ChainID == 50 OR ChainID == 100 OR ChainID == 150 +await store.getByField("TransactionEntity", "ChainID", [50, 100, 150]); ``` ## Get Records by Field + ```ts getByFields( entity: string, @@ -80,25 +85,34 @@ getByFields( ): Promise; ``` -This returns matching records for the specific entity that matches the given filter. Each entry in the filter is an AND operation. By default it will return the first 100 results. -The number of results can be changed via the `query-limit` flag for the node or via the options field. If you need more than the number of results provided you can also specify an `offset` and page your results. +This returns all matching records for the specific entity that matches the given filter(s). Each entry in the filter is an AND operation. By default it will return the first 100 results. +The number of results can be changed via the `query-limit` flag for the node or via the options field. If you need more than the number of results provided, we recommend you specify an `offset` and paginate through your results. Using the store directly: + ```ts -// Get all records with field1 == 50 AND field2 == '0xSomeAddress' -await store.getByFields(`StarterEntity`, [['field1', '=', 50], ['field2', '=', '0xSomeAddress']]); +// Get all records with ChainID == 50 AND AccountID == '0xSomeAddress' +await store.getByFields(`TransactionEntity`, [ + ["ChainID", "=", 50], + ["AccountID", "=", "0xSomeAddress"], +]); ``` Using an entity, this will provide better type safety: + ```ts -// Get all records with field1 == 50 AND field2 == '0xSomeAddress' -await StarterEntity.getByFields([['field1', '=', 50], ['field2', '=', '0xSomeAddress']]); +// Get all records with ChainID == 50 AND AccountID == '0xSomeAddress' +await TransactionEntity.getByFields([ + ["ChainID", "=", 50], + ["AccountID", "=", "0xSomeAddress"], +]); ``` -It's also possible to match multiple values to a field: +It's also possible to match multiple values to a field (in this case an OR operation is applied): + ```ts -// Get all records with field1 == 50 OR field1 == 51 -await StarterEntity.getByFields([['field1', '=', [50, 51]]]); +// Get all records with ChainID == 50 OR ChainID == 51 +await TransactionEntity.getByFields([["ChainID", "=", [50, 51]]]); ``` ## Get First Record by Field @@ -108,8 +122,8 @@ await StarterEntity.getByFields([['field1', '=', [50, 51]]]); This returns the first matching record for the specific entity that matches a given search. ```typescript -const field1Value = 50; -await store.getOneByField(`StarterEntity`, `field1`, field1Value); +const ChainIDValue = 50; +await store.getOneByField(`TransactionEntity`, `ChainID`, 50); ``` ## Upsert (Create and Update) Record @@ -120,7 +134,7 @@ This allows user to create a single record, if the record already exist this wil ```typescript const id = block.block.header.hash.toString(); -await store.set(`StarterEntity`,id, {field1: 50, ...}) +await store.set(`TransactionEntity`,id, {ChainID: 50, ...}) ``` ## Bulk Create Records @@ -130,10 +144,10 @@ await store.set(`StarterEntity`,id, {field1: 50, ...}) This allows to create multiple records for specified entity, but it will not overwrite existing records. ```typescript -await store.bulkCreate(`StarterEntity`,[ - {id: 1, field1: 50, ...}, - {id: 2, field1: 100, ...}, - {id: 3, field1: 150, ...} +await store.bulkCreate(`TransactionEntity`,[ + {id: 1, ChainID: 50, ...}, + {id: 2, ChainID: 100, ...}, + {id: 3, ChainID: 150, ...} ]) ``` @@ -144,22 +158,22 @@ await store.bulkCreate(`StarterEntity`,[ This allows to update multiple records for specified entity, it will create the records if they are not exist. ```typescript -await store.bulkUpdate(`StarterEntity`,[ - {id: 1, field1: 99, ...}, - {id: 2, field1: 199, ...}, - {id: 3, field1: 299, ...} +await store.bulkUpdate(`TransactionEntity`,[ + {id: 1, ChainID: 99, ...}, + {id: 2, ChainID: 199, ...}, + {id: 3, ChainID: 299, ...} ]) ``` The 3rd parameter is optional, and allows user to provide a list of fields they wish to be updated, and other fields will be ignored. -For example, only `field5` will be updated. +For example, only the `Success` property will be updated. ```typescript -await store.bulkUpdate(`StarterEntity`,[ - {id: 1, field1: 99, field5: true, ...}, - {id: 2, field1: 199, field5: false,...}, - ['field5'] +await store.bulkUpdate(`TransactionEntity`,[ + {id: 1, ChainID: 99, Success: true, ...}, + {id: 2, ChainID: 199, Success: false,...}, + ['Success'] ]) ``` @@ -173,7 +187,7 @@ This allows to remove a single record of the entity with its `id`. ```typescript const id = block.block.header.hash.toString(); -await store.remove(`StarterEntity`, id); +await store.remove(`TransactionEntity`, id); ``` ## Bulk Remove Record @@ -184,5 +198,5 @@ This allows to remove a number of entities with their `ids`. ```typescript const ids = ["1", "2", "3"]; -await store.remove(`StarterEntity`, ids); +await store.remove(`TransactionEntity`, ids); ```