VOLUME.ADMIN DESCRIBE

Returns metadata and segment-level statistics for a named volume.

Syntax

VOLUME.ADMIN DESCRIBE <volume-name>

Parameters

Parameter	Type	Description
volume-name	string	Name of the volume to describe, in <kind>-shard-<id> format (e.g. bucket-shard-0)

Return Value

RESP3 map with the following top-level fields:

Field	Type	Description
name	string	Volume name
status	string	Operational status: READWRITE, READONLY, or INOPERABLE
data_dir	string	Filesystem path where segment files are stored
segment_size	integer	Maximum size of each segment file in bytes
segments	map	Per-segment statistics keyed by integer segment ID

Each value in the segments map is a nested map:

Field	Type	Description
size	integer	Total segment file size in bytes
free_bytes	integer	Unallocated space remaining in the segment
used_bytes	integer	Space occupied by live entries
garbage_percentage	double	Percentage of reclaimable space: (size - free_bytes - used_bytes) / size * 100
cardinality	integer	Number of live entries in the segment

Behavior

Reads the volume’s configuration and computes per-segment statistics.

It is available on the management port (default 3320).

Errors

Argument errors:

Error Code	Error message	Cause
ERR	invalid number of parameters	-

Volume errors:

Error Code	Error message	Cause
ERR	Volume: '<name>' is not open	No volume with that name is managed by this member.

Examples

Describe a volume with one segment:

127.0.0.1:3320> VOLUME.ADMIN DESCRIBE bucket-shard-0
1# "name" => "bucket-shard-0"
2# "status" => "READWRITE"
3# "data_dir" => "/tmp/kronotop/data/bucket-shard-0"
4# "segment_size" => (integer) 268435456
5# "segments" =>
   1# (integer) 0 =>
      1# "size" => (integer) 268435456
      2# "free_bytes" => (integer) 268435200
      3# "used_bytes" => (integer) 256
      4# "garbage_percentage" => (double) 0.0
      5# "cardinality" => (integer) 1

Volume not found:

127.0.0.1:3320> VOLUME.ADMIN DESCRIBE non-existent-volume
(error) ERR Volume: 'non-existent-volume' is not open