system-table-blocks

Retrieves block metadata for table partitions.

Command properties

Property	Description
Command type	Driver query
Required permission	None
License usage	Not counted
Parallel execution	Not supported
Distributed execution	Not supported

Syntax

system-table-blocks table=TABLE [day=DATE] [sk=HEX] [era=LONG]

Options

table=TABLE: Specifies the name of the table whose block information to retrieve. This option is required.
day=DATE: Specifies the date to retrieve block information for, in yyyyMMdd format. If not specified, all dates are retrieved.
sk=HEX: Specifies the partition sub-key to retrieve, in hexadecimal. If not specified, all sub-keys are retrieved.
era=LONG: Specifies the partition identifier to retrieve. If not specified, all partitions are retrieved.

Output fields

Field	Type	Description
table	string	Table name
partition	string	Name of the table partition
block_id	integer	Block number within the table partition
ver	integer	File format version of the data block
min_time	timestamp	Timestamp of the first log in the block
max_time	timestamp	Timestamp of the last log in the block
log_count	long	Number of records in the block
original_size	long	Original size of the block (unit: bytes)
compressed_size	long	Compressed size of the block (unit: bytes)
reserved	boolean	Reserved status of the block
sto_class	integer	Integer value representing the storage partition lifecycle. `0`–`9999`: Hot tier, `10000`–`19999`: Warm tier, `20000`–`29999`: Cold tier
sto_path	string	Path where the table and index files are stored
signature	binary	Block signature data
iv	binary	Block encryption initialization vector

Error codes

Parsing errors

Error code	Message	Description
95121	table option is required.	The `table` option was not specified
95122	Invalid table name: [table]	The `table` option value is not a valid table name
95123	Invalid day value: [day]	The `day` option value cannot be parsed as a date
95124	Invalid sk value: [sk]	The `sk` option value is not a valid hexadecimal
95125	Invalid era value: [era]	The `era` option value is not a valid integer

Runtime errors

N/A

Description

The system-table-blocks command retrieves block-level metadata for table partitions. You can check the record count, original size, compressed size, and timestamp range for each block.

The table option is required and must specify the table name to query. You can combine the day, sk, and era options to retrieve blocks for specific partitions only.

Examples

Retrieve all block metadata for a specific table
```
system-table-blocks table=my_table
```
Retrieves block metadata for all partitions of the my_table table.
Retrieve blocks for a specific date partition
```
system-table-blocks table=my_table day=20260301
```
Retrieves block metadata for the March 1, 2026 partition of the my_table table.

Calculate compression ratio

system-table-blocks table=my_table
| eval ratio = double(compressed_size) / double(original_size) * 100
| fields partition, block_id, log_count, original_size, compressed_size, ratio

Calculates the compression ratio for each block.