GET
/v1/namespaces/{namespace}/tables/{table}Load a table
Returns the table's metadata: its columns, how it is partitioned, and its snapshots. A query engine reads the current snapshot's manifest list (an Avro file in the table's metadata/ folder), which lists the Parquet data files, then reads those files from S3. The metadata is refreshed from the Delta Lake table about once a minute.
Parameters
| Name | In | Description |
|---|---|---|
| namespace * | path | A network: its name is also the S3 bucket that holds the data (eth, base, bsc). |
| table * | path | A dataset of the network, such as blocks, transactions, logs or calls. |
| snapshots | query | refs returns only the snapshots that branches and tags point to (the current one); all returns every retained snapshot. refs keeps the response small (about 15 KB instead of 100 KB). One of refs, all. |
Try itLive against the public catalog · read-only, no key needed
GET https://iceberg.riv-dev1.pinax.io/v1/namespaces/eth/tables/blocks?snapshots=refsResponse
200 with the table metadata; 404 (NoSuchTableException) when the table doesn't exist.
| Field | Type | Description |
|---|---|---|
| metadata.format-version | number | Iceberg table format version (2). |
| metadata.table-uuid | string | The table's unique id. |
| metadata.location | string | The table's root, s3://<network>/<table>: the Parquet files and the metadata/ folder are below it. |
| metadata.last-updated-ms | number | When the metadata last changed (Unix milliseconds). |
| metadata.schemas[] | object[] | Every schema the table has had; current-schema-id picks the current one. Each field has an id, name, type (long, string, decimal(20, 0), timestamptz, date, …) and required. |
| metadata.partition-specs[] | object[] | How rows are split into folders; default-spec-id picks the current spec. The Pinax tables are partitioned by date (identity transform). |
| metadata.current-snapshot-id | number | The snapshot a query reads by default. |
| metadata.snapshots[] | object[] | Committed versions of the table. Each has a timestamp-ms, its manifest-list and a summary with totals (total-records, total-data-files, total-files-size). |
| metadata.refs | object | Branches and tags: main points at the current snapshot. |
| metadata.properties | object | Table properties, such as write.data.path and write.parquet.compression-codec (zstd). |
| metadata.snapshot-log[] / metadata-log[] | object[] | The history of current snapshots and of previous metadata files. |
Example responseTrimmed: 6 of the 31 columns, one snapshot and the last log entries. Try it for the full response.
{
"metadata": {
"format-version": 2,
"table-uuid": "58322cf7-de3b-4b6a-8e8f-eab487c9bea7",
"location": "s3://eth/blocks",
"last-sequence-number": 115,
"last-updated-ms": 1790714360676,
"last-column-id": 31,
"current-schema-id": 1,
"schemas": [
{
"type": "struct",
"schema-id": 1,
"fields": [
{
"id": 1,
"name": "block_num",
"required": true,
"type": "long"
},
{
"id": 2,
"name": "block_id",
"required": true,
"type": "string"
},
{
"id": 3,
"name": "parent_num",
"required": true,
"type": "long"
},
{
"id": 4,
"name": "parent_id",
"required": true,
"type": "string"
},
{
"id": 6,
"name": "timestamp",
"required": true,
"type": "timestamptz"
},
{
"id": 31,
"name": "date",
"required": true,
"type": "date"
}
]
}
],
"default-spec-id": 1,
"partition-specs": [
{
"spec-id": 1,
"fields": [
{
"name": "date",
"transform": "identity",
"source-id": 31,
"field-id": 1000
}
]
}
],
"last-partition-id": 1000,
"default-sort-order-id": 0,
"sort-orders": [
{
"order-id": 0,
"fields": []
}
],
"properties": {
"write.data.path": "s3://eth/blocks",
"write.metadata.previous-versions-max": "10",
"write.parquet.compression-codec": "zstd"
},
"current-snapshot-id": 8962148807290442000,
"refs": {
"main": {
"snapshot-id": 8962148807290442000,
"type": "branch"
}
},
"snapshots": [
{
"sequence-number": 115,
"snapshot-id": 8962148807290442000,
"parent-snapshot-id": 631410125796494000,
"timestamp-ms": 1790714356093,
"manifest-list": "s3://eth/blocks/metadata/snap-8962148807290441696-1-5515a500-7fae-42c9-9b80-2069d6aa9275.avro",
"schema-id": 1,
"summary": {
"operation": "append",
"added-data-files": "1",
"added-records": "32",
"added-files-size": "35569",
"changed-partition-count": "1",
"total-records": "34723",
"total-files-size": "23986576",
"total-data-files": "60",
"total-delete-files": "0",
"total-position-deletes": "0",
"total-equality-deletes": "0",
"iceberg-version": "Apache Iceberg 1.9.2 (commit 071d5606bc6199a0be9b3f274ec7fbf111d88821)"
}
}
],
"statistics": [],
"partition-statistics": [],
"snapshot-log": [
{
"timestamp-ms": 1790714356093,
"snapshot-id": 8962148807290442000
}
],
"metadata-log": [
{
"timestamp-ms": 1790714356149,
"metadata-file": "s3://eth/blocks/metadata/00116-f44c4858-af23-4cd7-afa0-e560926aea2a.metadata.json"
}
]
}
}Errors
Errors are JSON with a message, the exception type and the HTTP code, like this 404 for a table that doesn't exist:
{
"error": {
"message": "Table does not exist: eth.nope",
"type": "NoSuchTableException",
"code": 404
}
}