system-index-blocks

Retrieves partition and segment-level metadata for table indexes. The terms, termlimit, blocklimit, and blockoffset options themselves are available in both series. Merged indexes — the merged-segment rows, the posting_offset term field, and the way blocklimit/blockoffset span a partition's regular and merged segments as one combined stream — are available starting with 4.0.2609.0. The 5.0 series (through 5.0.2605.2) has no merged indexes, so this command returns only regular (V3) segment rows there.

Command properties

Syntax

Options

table=TABLE

Name of the table to query. This option is required.

index=INDEX

Name of the index to query. This option is required.

day=DATE

Partition date in yyyyMMdd format. If not specified, all partitions are queried.

sk=HEX

Partition sub-key as a hexadecimal long value. If not specified, the retrieval range is not restricted.

era=LONG

Partition identifier. If not specified, the retrieval range is not restricted.

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 number of term rows returned. Must be used together with terms=t. For a regular (V3) segment, this limit is applied per field; for a merged segment, it is applied per tree kind (string, integer, timestamp, IPv4, IPv6).

blocklimit=LONG

Limits the maximum number of segments (blocks) to retrieve. This is applied to the combined stream of a partition's regular (V3) segments and merged segments (if multiple partitions are queried, this limit is applied separately to each partition).

blockoffset=LONG

Specifies the starting position of segments to retrieve. (Default: 0) This skips from the front of the combined stream of a partition's regular (V3) segments and merged segments, applied separately per partition.

Output fields

Base segment information fields:

Additional fields returned when terms=t is specified:

A term row from a regular (V3) segment returns only seg_id, field_name, field_type, term, and posting_count. A term row from a merged segment returns these plus table, index, partition, sto_class, sto_path, and posting_offset, with one row returned per term-and-field pair (for example, when the same term appears in multiple fields).

Error codes

Parsing errors

Runtime errors

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.

If the queried partition has a merged index (a .merged directory), merged-segment rows are returned together with the regular (V3) segment rows in the same query result. A merged-segment row is not per individual segment; one row is returned per tree kind in the merged index (string, integer, timestamp, IPv4, IPv6), and the seg_id, min_id, min_time, max_time, reserved, and seg_offset fields are not returned for these rows (null).

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 number of term rows and must be used together with terms=t. This limit is applied separately per field for regular (V3) segments, and per tree kind for merged segments.

Use the blocklimit and blockoffset options to restrict the range of segments to retrieve, enabling paginated retrieval of large indexes. Both options are applied to the combined stream of a partition's regular (V3) segments and merged segments — if multiple partitions are queried, the limit is applied separately to each partition, and it does not directly limit the total number of result rows.

Examples

1. Retrieve segments for a specific table index

   system-index-blocks table=SONAR_EVENTS index=default_idx
   

   Retrieves the segment list for the default_idx index of the SONAR_EVENTS table.

2. Retrieve segments for a specific date partition

   system-index-blocks table=SONAR_EVENTS index=default_idx day=20260301
   

   Retrieves segments for the March 1, 2026 partition of the default_idx index in the SONAR_EVENTS table.

3. Retrieve with term data included

   system-index-blocks table=SONAR_EVENTS index=default_idx day=20260301 terms=t termlimit=10
   

   Retrieves segments for the March 1, 2026 partition along with up to 10 term entries per field.

4. Retrieve with a segment count limit

   system-index-blocks table=SONAR_EVENTS index=default_idx blocklimit=100
   

   Retrieves up to 100 segments for the default_idx index of the SONAR_EVENTS table.

5. Retrieve only merged segments (4.0 series, 4.0.2609.0 and later)

   system-index-blocks table=SONAR_EVENTS index=default_idx
   | search ver == 4
   

Change history