History VS State Tables
This page describes the differences between History and State tables within Hubble.
What are state tables?
These track ledger entry changes, meaning they store how each ledger entry evolved over time instead of just the final state of the ledger entry. This means that state tables are a full history log of ledger entry states that are changed based on actions (operations) from the Stellar network.
- Each row represents a single change to a ledger entry
- You will see multiple rows of the same ledger entry hash if it has been modified multiple times in different ledger sequences
- This is not a snapshot/SCD type 2 table. There is no valid to/from dates in these tables
Note that this is a different behavior when compared to the Horizon endpoints. Horizon endpoints return the current value of a given ledger entry (a single result) whereas the Hubble state tables will return all the changes over time for a given ledger entry (multiple results). To get similar behavior as Horizon you can filter and return the lastest entry from the Hubble state tables or you can use the _current version of the state tables listed in the crypto-stellar.crypto_stellar_dbt dataset.
Example contents of a state table
Let's say we only want the ledger entries for the balance of DUMMYACCOUNT. The account state table would return the following:
| account_id | ledger_sequence | balance |
|---|---|---|
| DUMMYACCOUNT | 1 | 10 |
| DUMMYACCOUNT | 2 | 15 |
| DUMMYACCOUNT | 3 | 5 |
As seen in the table, each row shows the balance of DUMMYACCOUNT at a sepecific ledger_sequence. Note that this is different than what the Horizon endpoint would return as seen below
{
"balance": "5.0",
"asset_type": "native"
}
List of state tables
What are history tables?
These tables are a full history log of actions on the network.
- Each row represents some action on the network (ledger closing, transactions, operations, etc...)
- Encompasses the complete chronological history of activity on the network
Example contents of a history table
Let's say we operations for a specific transaction. The history_operations table would return the following:
| transaction_hash | id | ledger_sequence | type | details_json |
|---|---|---|---|---|
| TXHASH1 | 1 | 1 | 13 | {"some": "operation details"} |
| TXHASH1 | 2 | 1 | 2 | {"some": "operation details"} |
| TXHASH1 | 3 | 1 | 13 | {"some": "operation details"} |
As seen in the table, each row shows the distinct operation with its unique id.