system index-blocks

Retrieves partition and segment-level metadata for table indexes.

Command properties

Property	Description
Command type	Driver query
Required permission	None (table read permission required)
License usage	Not counted
Parallel execution	Not supported
Distributed execution	Not supported

Syntax

system index-blocks [terms={t|f}] [termlimit=LONG] [blocklimit=LONG] [blockoffset=LONG] TABLE INDEX [DAY [SK [ERA]]]

Options

terms={t|f}: Retrieves term data for each index field. (Default: f)

t: Include term data in the results
f: Do not retrieve term data

termlimit=LONG: When terms=t, limits the maximum number of terms to retrieve per field. Must be used together with terms=t.
blocklimit=LONG: Limits the maximum number of segments (blocks) to retrieve.
blockoffset=LONG: Specifies the starting position of segments to retrieve. (Default: 0)

Targets

TABLE: Name of the table to query. Required.
INDEX: Name of the index to query. Required.
[DAY]: Partition date in yyyyMMdd format. If not specified, all partitions are queried.
[SK]: Partition sub-key as a hexadecimal long value. If not specified, the retrieval range is not restricted.
[ERA]: Partition identifier. If not specified, the retrieval range is not restricted.

Output fields

Base segment information fields:

Field	Type	Description
table	string	Table name
index	string	Index name
partition	string	Partition identifier string
sto_class	integer	Storage class number. `0`–`9,999`: Hot tier, `10,000`–`19,999`: Warm tier, `20,000`–`29,999`: Cold tier
sto_path	string	Absolute path of the directory where segment files are stored
seg_id	long	Segment ID
min_id	long	Minimum record ID in the segment. Not returned when `reserved` is `true`.
max_id	long	Maximum record ID in the segment. Not returned when `reserved` is `true`.
min_time	timestamp	Minimum timestamp in the segment
max_time	timestamp	Maximum timestamp in the segment
ver	long	Segment version. Not returned when `reserved` is `true`.
reserved	boolean	Whether the segment is reserved
field_cnt	integer	Number of fields in the segment
seg_offset	long	Start offset of the segment data
fields	string	List of fields. Displayed per line in `fieldname:type:termblocksize` format.

Additional fields returned when terms=t is specified:

Field	Type	Description
field_name	string	Name of the field the term belongs to
field_type	string	Field type (`STRING` or `LONG`)
term	string or long	Term value
posting_count	long	Number of records containing the term

Error codes

Parsing errors

Error code	Message	Description
95061	missing-table-option	Table name was not specified
95062	missing-index-option	Index name was not specified
95063	invalid-table-name	Table name is invalid
95064	no-table-read-permission	The user does not have read permission for the table
95113	invalid-day-option	The `DAY` value is not in `yyyyMMdd` format
95114	invalid-subkey-option	The `SK` value is not a valid hexadecimal `long`
95115	invalid-era-option	The `ERA` value is invalid
95117	invalid-long-value	The `termlimit`, `blocklimit`, or `blockoffset` value is invalid
95118	termlimit-option-given-without-terms	`termlimit` was specified without `terms=t`
95132	missing-args	Required arguments are missing

Runtime errors

Error code	Message	Description	Post-processing
95064	no-table-read-permission	The user does not have read permission for the table	Query aborted
92003	table-not-found	The specified table does not exist	Query aborted
92005	index-not-found	The specified index does not exist	Query aborted

Description

The system index-blocks command retrieves segment-level metadata for table indexes. You can view each segment's ID, timestamp range, storage class, storage path, and field information.

When the terms=t option is specified, term data for each field is also returned in addition to the segment records. The termlimit option limits the maximum number of terms per field and must be used together with terms=t.

Use the blocklimit and blockoffset options to restrict the range of segments to retrieve, enabling paginated retrieval of large indexes.

Examples

Retrieve segments for a specific table index
```
system index-blocks SONAR_EVENTS default_idx
```
Retrieves the segment list for the default_idx index of the SONAR_EVENTS table.
Retrieve segments for a specific date partition
```
system index-blocks SONAR_EVENTS default_idx 20260301
```
Retrieves segments for the March 1, 2026 partition of the default_idx index in the SONAR_EVENTS table.
Retrieve with term data included
```
system index-blocks terms=t termlimit=10 SONAR_EVENTS default_idx 20260301
```
Retrieves segments for the March 1, 2026 partition along with up to 10 term entries per field.
Retrieve with a segment count limit
```
system index-blocks blocklimit=100 SONAR_EVENTS default_idx
```
Retrieves up to 100 segments for the default_idx index of the SONAR_EVENTS table.