> ## Documentation Index
> Fetch the complete documentation index at: https://developers.stellar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Contract Data Snapshot

> Reference documentation for the Contract Data Snapshot table in Hubble's Silver data dictionary.

## Table Metadata

| Property | Configuration |
| - | - |
| Natural Key(s) | contract\_id, ledger\_key\_hash, valid\_from |
| Partition Field(s) | valid\_to (MONTH partition) |
| Clustered Field(s) | contract\_id, ledger\_key\_hash |
| Documentation | [dbt docs](http://www.stellar-dbt-docs.com/#!/model/model.stellar_dbt_public.contract_data_snapshot) |

## Column Details

| Name | Description | Data Type | Domain Values | Required? | Notes |
| - | - | - | - | - | - |
| contract\_id | Soroban contract id. | STRING | | Yes | |
| contract\_key\_type | Contract key type which is an ScVal. | STRING | ScValTypeScvContractInstance, ScValTypeScvLedgerKeyContractInstance, ScValTypeScvLedgerKeyNonce | No | |
| contract\_durability | Contract can either be temporary or persistent. | STRING | | No | |
| asset\_code | The 4 or 12 character code representation of the asset on the network. | STRING | | No | Asset codes have no guarantees of uniqueness. The combination of asset code, issuer and type represents a distinct asset. |
| asset\_issuer | The account address of the original asset issuer that created the asset. | STRING | | No | |
| asset\_type | The identifier for type of asset code, can be alphanumeric (4 or 12 characters) or the native asset to the network, XLM. | STRING | native, alphanum4, alphanum12 | No | XLM is the native asset. XLM has no asset code or issuer and is displayed with asset type = 'native'. |
| balance\_holder | The address/account that holds the balance of the asset in contract data. | STRING | | No | |
| balance | The number of units of XLM held by the account. | STRING | | No | The `accounts` table only reports balances for XLM. Any other asset class is reported in `trust_lines`. |
| last\_modified\_ledger | The ledger sequence number when the ledger entry was last modified. | INTEGER | | Yes | Natural Key. Cluster Field. Deletion does not count as modification. |
| ledger\_entry\_change | Code describing the ledger entry change type applied. | INTEGER | <ul><li>0 - Ledger Entry Created</li><li>1 - Ledger Entry Updated</li><li>2 - Ledger Entry Deleted</li><li>3 - Ledger Entry State (value of the entry)</li></ul> | Yes | Not every entry can be updated. Updates not valid for claimable balances. |
| ledger\_sequence | | INTEGER | | Yes | |
| ledger\_key\_hash | | STRING | | Yes | |
| key | The encoded key used to identify a specific piece of contract data. Has two components: type and value. | JSON | | No | |
| key\_decoded | The human-readable/decoded version of the key. | JSON | | No | |
| val | The encoded value associated with the key in the contract data. Has two components: type and value. | JSON | | No | |
| val\_decoded | The human-readable/decoded version of the value. | JSON | | No | |
| contract\_data\_xdr | The XDR (External Data Representation) encoding of the contract data. | STRING | | No | XDR ensures interoperability across systems. |
| closed\_at | Timestamp in UTC when this ledger closed and committed. | TIMESTAMP | | Yes | Ledgers close \~every 5 seconds. |
| deleted | Indicates whether the ledger entry has been deleted. | BOOLEAN | | Yes | Once deleted, cannot be recovered. History is maintained. |
| batch\_id | String representation of the run id for a given DAG in Airflow. Takes the form of `scheduled__<batch_end_date>-<dag_alias>`. Batch ids are unique to the batch and help with monitoring and rerun capabilities | string | | Yes | |
| batch\_run\_date | The start date for the batch interval. | DATETIME | | Yes | Proxy for closed\_at for a ledger. |
| batch\_insert\_ts | The timestamp in UTC when a batch of records was inserted. | TIMESTAMP | | Yes | For data engineering purposes, not ad hoc analysis. |
| airflow\_start\_ts | The timestamp when the airflow job starts. | STRING | | No | Used to detect backfill jobs. |
| valid\_from | The timestamp when this snapshot row was first inserted and became effective. | TIMESTAMP | | Yes | Tracks changes over time. |
| valid\_to | The timestamp when this row is no longer valid. | TIMESTAMP | | No | If null, the setting is currently active. |

## Example Business Questions

1. Point-in-time query (balance/value as of a given date)

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT contract_id, ledger_key_hash, val_decoded
FROM `crypto-stellar.snapshots.contract_data_snapshot`
WHERE contract_id = 'C123'
  AND ledger_key_hash = 'abc123'
  DATE('2025-02-10') BETWEEN DATE(valid_from) AND COALESCE(DATE(valid_to), '9999-12-31')
LIMIT 100
```

2. All active contracts (latest state only)

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT contract_id, ledger_key_hash, val_decoded, balance, contract_durability
FROM `crypto-stellar.snapshots.contract_data_snapshot`
WHERE valid_to IS NULL
LIMIT 100
```

3. Recent updates

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT contract_id, ledger_key_hash, closed_at, ledger_entry_change
FROM `crypto-stellar.snapshots.contract_data_snapshot`
WHERE closed_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 2 DAY)
LIMIT 100
```