Pagination

The current version of SimpleContract implements two different functions to query data from the ledger in batches. Both of them, however, look through the whole world state and return all elements that satisfy a certain condition. This process can take a considerable amount of time and resources, and the result can be huge as well. To limit the number of objects in a response, we can utilize alternative versions of query functions that support pagination.

getStateByRangeWithPagination(startKey: string, endKey: string, pageSize: number, bookmark?: string): Promise<StateQueryResponse<StateQueryIterator>>
getStateByPartialCompositeKeyWithPagination(objectType: string, attributes: string[], pageSize: number, bookmark?: string): Promise<StateQueryResponse<StateQueryIterator>>

They are similar to their siblings, but the main difference is the presence of pageSize and bookmark in the list of input parameters and StateQueryResponse as a return value.

The pageSize is the maximum size of the resulting key set.

The bookmark is a string that specifies the starting place, from which pageSize keys will be fetched. When an empty string is passed as a value to the bookmark argument, the returned iterator can be used to fetch the first pageSize keys. When the bookmark is a non-empty string, the iterator can be used to fetch the first pageSize keys between the bookmark (inclusive) and the last matching key.

🚩Only the bookmark present in a prior page of a query result (the metadata field of a StateQueryResponse object) can be used as a value to the bookmark argument. Otherwise, an empty string must be passed as a bookmark.

StateQueryResponse is a wrapper type containing StateQueryIterator and metadata encapsulated in a QueryResponseMetadata object. QueryResponseMetadata is a type containing information about the next bookmark to use and the number of fetched results.

// StateQueryResponse<StateQueryIterator>
{
    metadata: { // QueryResponseMetadata
        fetchedRecordsCount: number;
        bookmark:            string;
    };
    iterator: StateQueryIterator;
}

The return value of pagination queries can also be treated as an AsyncIterable<KV> object, so the for await...of processing can also be utilized.