Reading State

Please note that this guide is for reading raw state data. It is preferable to use read-only actions to read data so that it can be returned in a structured way that is useful for your application.

See Read-only Actions for more information.

Prerequisites

To follow this guide, you will need:

GlobalForce Tables

GlobalForce stores data in tables, which are similar to database tables. Each table has a name and a set of fields. Tables are organized into scopes, which are defined by the smart contract that created the table.

To retrieve data from a table, you need to know its name, scope, and the name of the smart contract that created it. You can also specify a lower and upper bound to limit the amount of data returned.

Methods to Retrieve Data from GlobalForce Tables

Use get_table_rows Function

The get_table_rows function retrieves rows from a table. It takes the following parameters in JSON format:

Below is an example that retrieves rows from abihash table, owned by the eosio account and having as scope the eosio name.

curl --request POST \
--url https://history.globalforce.io/v1/chain/get_table_rows \
--header 'content-type: application/json' \
--data '{
"json": true,
"code": "eosio",
"scope": "eosio",
"table": "abihash",
"lower_bound": "eosio",
"limit": 3,
"reverse": false
}'

In the example above:

The get_table_rows Result

The JSON returned by the get_table_rows has the following structure:

{
  "rows": [
    { },
    ...
    { }
  ],
  "more": true,
  "next_key": ""
}

The "rows" field is an array of table row objects in JSON representation. The "more" field indicates that there are additional rows beyond the ones returned. The "next_key" field contains the key to be used as the lower bound in the next request to retrieve the next set of rows.

For example, the result from the previous section command contains three rows, and looks similar to the one below:

{
  "rows": [
    {
      "owner": "eosio",
      "hash": "00e166885b16bcce50fea9ea48b6bd79434cb845e8bc93cf356ff787e445088c"
    },
    {
      "owner": "eosio.assert",
      "hash": "aad0ac9f3f3d8f71841d82c52080f99479e869cbde5794208c9cd08e94b7eb0f"
    },
    {
      "owner": "eosio.evm",
      "hash": "9f238b42f5a4be3b7f97861f90d00bbfdae03e707e5209a4c22d70dfbe3bcef7"
    }
  ],
  "more": true,
  "next_key": "6138663584080503808"
}

The get_table_rows Pagination

Note that the previous command has the "more" field set to true. That means there's more rows in the table, which match the filter used, that were not returned with the first issued command.

The "next_key", "lower_bound" and "upper_bound" fields, can be used to implement pagination or iterative retrieval of data from any table in the GlobalForce blockchain.

To fetch the next set of rows, you can issue another get_table_rows request, modifying the lower bound to be the value of the "next_key" field:

curl --request POST \
--url https://history.globalforce.io/v1/chain/get_table_rows \
--header 'content-type: application/json' \
--data '{
"json": true,
"code": "eosio",
"scope": "eosio",
"table": "abihash",
"lower_bound": "6138663584080503808",
"limit": 3,
"reverse": false
}'

The above command returns the subsequent 3 rows from the abihash table with the producer name value greater than "6138663584080503808". By iterating this process, you can retrieve all the rows in the table.

If the response from the second request includes "more": false, it means that you have fetched all the available rows, which match the filter, and there is no need for further requests.

Use get_table_by_scope Function

The purpose of get_table_by_scope is to scan the table names under a given code account, using scope as the primary key. If you already know the table name, e.g. mytable, it is not necessary to use get_table_by_scope unless you want to find out what are the scopes that have defined the mytable table.

These are the input parameters supported by get_table_by_scope:

Below is an example JSON payload for the get_table_by_scope function:

{
  "code": "accountname1",
  "table": "tablename",
  "lower_bound": "accountname2",
  "limit": 10,
  "reverse": false,
}

In the example above:

The get_table_by_scope Result

The get_table_by_scope returns a JSON object containing information about the tables within the specified scope. The return JSON has the following fields:

Each table row is represented by a JSON object that contains the following fields:

Empty Result

It is possible that the returned JSON looks like the one below:

{
    "rows":[],
    "more": "accountname"
}

The above result means your request did not finish its execution due to the transaction time limit imposed by the blockchain configuration. The result tells you it did not find any table (rows field is empty) from the specified lower_bound to the "accountname" bound. In this case you must execute the request again with lower_bound set to the value provided by the "more" field, in this case accountname.

Real Example

For a real example, you can list the first three tables named accounts owned by the eosio.token account starting with the lower bound scope abc:

curl --request POST \
--url https://history.globalforce.io/v1/chain/get_table_by_scope \
--header 'content-type: application/json' \
--data '{
"json": true,
"code": "eosio.token",
"table": "accounts",
"lower_bound": "abc",
"upper_bound": "",
"reverse": false,
"limit": "3"
}'

The result looks similar to the one below:

{
  "rows": [
    {
      "code": "eosio.token",
      "scope": "abc",
      "table": "accounts",
      "payer": "abc.com",
      "count": 1
    },
    {
      "code": "eosio.token",
      "scope": "abc.bank",
      "table": "accounts",
      "payer": "alibaba.com",
      "count": 1
    },
    {
      "code": "eosio.token",
      "scope": "abc.com",
      "table": "accounts",
      "payer": "vuniyuoxoeub",
      "count": 1
    }
  ],
  "more": "abc.gm"
}

Reading State

Please note that this guide is for reading raw state data. It is preferable to use `read-only` actions to read data so that it can be returned in a structured

Loading...