zpool.query

Query ZFS pools with flexible options for properties, topology, scan, and features.

Returns information about both imported and non-imported pools. By default, only minimal data is returned (name, guid, status, health); additional sections like topology, scan, properties, etc. must be opted into via their respective flags. Pools that exist in the database but are not currently imported are returned with an OFFLINE status.

The boot pool can be queried by explicitly passing its name in pool_names. It is excluded from results when pool_names is null (query-all mode).

Examples:

# Query all pools (minimal info: name, guid, status, health) {}

# Query specific pools with properties {
    "pool_names": ["tank", "boot-pool"], "properties": ["size", "capacity"] }

# Query with full topology and scan information {
    "pool_names": ["tank"], "topology": true, "scan": true }

# Query everything {
    "topology": true, "scan": true, "expand": true, "features": true, "properties": ["size", "capacity", "health"] }

Type: object

Call parameters

Type: array
No Additional Items

Tuple Validation

Parameter 1: data

data

Type: object

Default:

{ "pool_names": null, "properties": null, "topology": false, "scan": false, "expand": false, "features": false }

Query parameters.

No Additional Properties

pool_names

Pool Names

Default: null

Pool names to query. None queries all imported pools.

Any of

• Option 1
• Option 2

Type: array of string
No Additional Items

Each item of this array must be:

Type: string

Type: null

properties

Properties

Default: null

Property names to retrieve. None returns no properties.

Any of

• Option 1
• Option 2

Type: array of string
No Additional Items

Each item of this array must be:

Type: string

Type: null

topology

Topology

Type: boolean Default: false

Include vdev topology.

scan

Scan

Type: boolean Default: false

Include scan/scrub information.

expand

Expand

Type: boolean Default: false

Include expansion information.

features

Features

Type: boolean Default: false

Include feature flags.

Return value

Result

Type: array of object
No Additional Items

Each item of this array must be:

ZPoolEntry

Type: object
No Additional Properties

name Required

Name

Type: string

Name of the zpool.

guid Required

Guid

Type: integer

Globally unique identifier for the pool.

status Required

Status

Type: string

Current pool status (ONLINE, DEGRADED, FAULTED, OFFLINE, etc.).

healthy Required

Healthy

Type: boolean

Whether the pool is in a healthy state.

warning Required

Warning

Type: boolean

Whether the pool has warning conditions.

status_code Required

Status Code

Detailed status code (e.g., OK, ERRATA, FEATDISABLED, LOCKEDSED_DISKS).

Any of

• Option 1
• Option 2

Type: string

Type: null

status_detail Required

Status Detail

Human-readable status description.

Any of

• Option 1
• Option 2

Type: string

Type: null

properties

Properties

Default: null

Pool properties, keyed by property name.

Any of

• Option 1
• Option 2

Type: object

Additional Properties

Each additional property must conform to the following schema

ZPoolPropertyValue

Type: object
No Additional Properties

raw Required

Raw

Type: string

The raw string representation of the property.

source Required

Source

The source from where this property received its value (DEFAULT, LOCAL, NONE, etc.).

Any of

• Option 1
• Option 2

Type: string

Type: null

value Required

Value

The native Python value of the property.

Any of

• Option 1
• Option 2
• Option 3
• Option 4
• Option 5

Type: integer

Type: number

Type: string

Type: boolean

Type: null

Type: null

topology

Default: null

Pool vdev topology.

Any of

• ZPoolTopology
• Option 2

ZPoolTopology

Type: object
No Additional Properties

data Required

Data

Type: array of object

Array of data vdev configurations.

No Additional Items

Each item of this array must be:

ZPoolVdev

Type: object
No Additional Properties

name Required

Name

Type: string

Vdev name (e.g., 'mirror-0', '/dev/sda1').

vdev_type Required

Vdev Type

Type: string

Vdev type (e.g., 'mirror', 'raidz1', 'disk').

guid Required

Guid

Type: integer

Globally unique identifier for this vdev.

state Required

State

Type: string

Current state (ONLINE, DEGRADED, FAULTED, OFFLINE, UNAVAIL, etc.).

stats Required

ZPoolVdevStats

Type: object

Vdev I/O statistics.

No Additional Properties

timestamp

Timestamp

Type: integer Default: 0

High-resolution timestamp (nanoseconds).

allocated

Allocated

Type: integer Default: 0

Allocated space in bytes.

space

Space

Type: integer Default: 0

Total space in bytes.

dspace

Dspace

Type: integer Default: 0

Deflated (compressed) space.

pspace

Pspace

Type: integer Default: 0

Physical space.

rsize

Rsize

Type: integer Default: 0

Replaceable dev size.

esize

Esize

Type: integer Default: 0

Expandable dev size.

read_errors

Read Errors

Type: integer Default: 0

Number of read errors.

write_errors

Write Errors

Type: integer Default: 0

Number of write errors.

checksum_errors

Checksum Errors

Type: integer Default: 0

Number of checksum errors.

initialize_errors

Initialize Errors

Type: integer Default: 0

Number of initialize errors.

dio_verify_errors

Dio Verify Errors

Type: integer Default: 0

Number of direct I/O verify errors.

slow_ios

Slow Ios

Default: null

Number of slow I/Os.

Any of

• Option 1
• Option 2

Type: integer

Type: null

self_healed_bytes

Self Healed Bytes

Type: integer Default: 0

Self-healed bytes.

fragmentation

Fragmentation

Type: integer Default: 0

Fragmentation percentage.

scan_processed

Scan Processed

Type: integer Default: 0

Bytes processed by scan.

scan_removing

Scan Removing

Type: integer Default: 0

Bytes processed by removal.

rebuild_processed

Rebuild Processed

Type: integer Default: 0

Bytes processed by rebuild.

noalloc

Noalloc

Type: integer Default: 0

Allocations halted.

ops_read

Ops Read

Type: integer Default: 0

Read operations.

ops_write

Ops Write

Type: integer Default: 0

Write operations.

bytes_read

Bytes Read

Type: integer Default: 0

Bytes read.

bytes_write

Bytes Write

Type: integer Default: 0

Bytes written.

configured_ashift

Configured Ashift

Default: null

Configured ashift value.

Any of

• Option 1
• Option 2

Type: integer

Type: null

logical_ashift

Logical Ashift

Default: null

Logical ashift value.

Any of

• Option 1
• Option 2

Type: integer

Type: null

physical_ashift

Physical Ashift

Default: null

Physical ashift value.

Any of

• Option 1
• Option 2

Type: integer

Type: null

children Required

Children

Type: array of object

Child vdevs.

No Additional Items

Each item of this array must be:

ZPoolVdev

Type: object
No Additional Properties

name Required

Name

Type: string

Vdev name (e.g., 'mirror-0', '/dev/sda1').

vdev_type Required

Vdev Type

Type: string

Vdev type (e.g., 'mirror', 'raidz1', 'disk').

guid Required

Guid

Type: integer

Globally unique identifier for this vdev.

state Required

State

Type: string

Current state (ONLINE, DEGRADED, FAULTED, OFFLINE, UNAVAIL, etc.).

stats Required

Type: object

Vdev I/O statistics.

children Required

Children

Type: array

Child vdevs.

No Additional Items

Each item of this array must be:

Type: object

top_guid

Top Guid

Default: null

GUID of the top-level vdev this belongs to.

Any of

• Option 1
• Option 2

Type: integer

Type: null

top_guid

Top Guid

Default: null

GUID of the top-level vdev this belongs to.

Any of

• Option 1
• Option 2

Type: integer

Type: null

log Required

Log

Type: array of object

Array of ZFS Intent Log (ZIL) vdev configurations.

No Additional Items

Each item of this array must be:

ZPoolVdev

Type: object
No Additional Properties

name Required

Name

Type: string

Vdev name (e.g., 'mirror-0', '/dev/sda1').

vdev_type Required

Vdev Type

Type: string

Vdev type (e.g., 'mirror', 'raidz1', 'disk').

guid Required

Guid

Type: integer

Globally unique identifier for this vdev.

state Required

State

Type: string

Current state (ONLINE, DEGRADED, FAULTED, OFFLINE, UNAVAIL, etc.).

stats Required

Type: object

Vdev I/O statistics.

children Required

Children

Type: array

Child vdevs.

No Additional Items

Each item of this array must be:

Type: object

top_guid

Top Guid

Default: null

GUID of the top-level vdev this belongs to.

Any of

• Option 1
• Option 2

Type: integer

Type: null

cache Required

Cache

Type: array of object

Array of L2ARC cache vdev configurations.

No Additional Items

Each item of this array must be:

ZPoolVdev

Type: object
No Additional Properties

name Required

Name

Type: string

Vdev name (e.g., 'mirror-0', '/dev/sda1').

vdev_type Required

Vdev Type

Type: string

Vdev type (e.g., 'mirror', 'raidz1', 'disk').

guid Required

Guid

Type: integer

Globally unique identifier for this vdev.

state Required

State

Type: string

Current state (ONLINE, DEGRADED, FAULTED, OFFLINE, UNAVAIL, etc.).

stats Required

Type: object

Vdev I/O statistics.

children Required

Children

Type: array

Child vdevs.

No Additional Items

Each item of this array must be:

Type: object

top_guid

Top Guid

Default: null

GUID of the top-level vdev this belongs to.

Any of

• Option 1
• Option 2

Type: integer

Type: null

spares Required

Spares

Type: array of object

Array of spare disk configurations.

No Additional Items

Each item of this array must be:

ZPoolVdev

Type: object
No Additional Properties

name Required

Name

Type: string

Vdev name (e.g., 'mirror-0', '/dev/sda1').

vdev_type Required

Vdev Type

Type: string

Vdev type (e.g., 'mirror', 'raidz1', 'disk').

guid Required

Guid

Type: integer

Globally unique identifier for this vdev.

state Required

State

Type: string

Current state (ONLINE, DEGRADED, FAULTED, OFFLINE, UNAVAIL, etc.).

stats Required

Type: object

Vdev I/O statistics.

children Required

Children

Type: array

Child vdevs.

No Additional Items

Each item of this array must be:

Type: object

top_guid

Top Guid

Default: null

GUID of the top-level vdev this belongs to.

Any of

• Option 1
• Option 2

Type: integer

Type: null

stripe Required

Stripe

Type: array of object

Array of stripe (single-disk) vdev configurations.

No Additional Items

Each item of this array must be:

ZPoolVdev

Type: object
No Additional Properties

name Required

Name

Type: string

Vdev name (e.g., 'mirror-0', '/dev/sda1').

vdev_type Required

Vdev Type

Type: string

Vdev type (e.g., 'mirror', 'raidz1', 'disk').

guid Required

Guid

Type: integer

Globally unique identifier for this vdev.

state Required

State

Type: string

Current state (ONLINE, DEGRADED, FAULTED, OFFLINE, UNAVAIL, etc.).

stats Required

Type: object

Vdev I/O statistics.

children Required

Children

Type: array

Child vdevs.

No Additional Items

Each item of this array must be:

Type: object

top_guid

Top Guid

Default: null

GUID of the top-level vdev this belongs to.

Any of

• Option 1
• Option 2

Type: integer

Type: null

special Required

Special

Type: array of object

Array of special vdev configurations for metadata.

No Additional Items

Each item of this array must be:

ZPoolVdev

Type: object
No Additional Properties

name Required

Name

Type: string

Vdev name (e.g., 'mirror-0', '/dev/sda1').

vdev_type Required

Vdev Type

Type: string

Vdev type (e.g., 'mirror', 'raidz1', 'disk').

guid Required

Guid

Type: integer

Globally unique identifier for this vdev.

state Required

State

Type: string

Current state (ONLINE, DEGRADED, FAULTED, OFFLINE, UNAVAIL, etc.).

stats Required

Type: object

Vdev I/O statistics.

children Required

Children

Type: array

Child vdevs.

No Additional Items

Each item of this array must be:

Type: object

top_guid

Top Guid

Default: null

GUID of the top-level vdev this belongs to.

Any of

• Option 1
• Option 2

Type: integer

Type: null

dedup Required

Dedup

Type: array of object

Array of deduplication table vdev configurations.

No Additional Items

Each item of this array must be:

ZPoolVdev

Type: object
No Additional Properties

name Required

Name

Type: string

Vdev name (e.g., 'mirror-0', '/dev/sda1').

vdev_type Required

Vdev Type

Type: string

Vdev type (e.g., 'mirror', 'raidz1', 'disk').

guid Required

Guid

Type: integer

Globally unique identifier for this vdev.

state Required

State

Type: string

Current state (ONLINE, DEGRADED, FAULTED, OFFLINE, UNAVAIL, etc.).

stats Required

Type: object

Vdev I/O statistics.

children Required

Children

Type: array

Child vdevs.

No Additional Items

Each item of this array must be:

Type: object

top_guid

Top Guid

Default: null

GUID of the top-level vdev this belongs to.

Any of

• Option 1
• Option 2

Type: integer

Type: null

Type: null

scan

Default: null

Most recent scrub or resilver information.

Any of

• ZPoolScan
• Option 2

ZPoolScan

Type: object
No Additional Properties

function Required

Function

Type: enum (of string)

Type of ZFS pool scan.

Must be one of:

• "RESILVER"
• "SCRUB"

state Required

State

Type: enum (of string)

Current lifecycle state of the scan.

Must be one of:

• "SCANNING"
• "FINISHED"
• "CANCELED"

start_time Required

Start Time

Type: integer

Scan start time (unix timestamp).

end_time Required

End Time

Scan end time as unix timestamp (null while the scan is still running).

Any of

• Option 1
• Option 2

Type: integer

Type: null

percentage Required

Percentage

Type: number

Scan progress (between 0 and 100%).

bytes_to_process Required

Bytes To Process

Type: integer

Total bytes located by scanner.

bytes_processed Required

Bytes Processed

Type: integer

Total bytes to scan.

bytes_issued Required

Bytes Issued

Type: integer

Issued bytes per scan pass.

pause Required

Pause

Pause time as unix timestamp (null if the scan is not paused).

Any of

• Option 1
• Option 2

Type: integer

Type: null

errors Required

Errors

Type: integer

Number of scan errors.

total_secs_left Required

Total Secs Left

Number of seconds left (null if the scan is not running).

Any of

• Option 1
• Option 2

Type: integer

Type: null

Type: null

expand

Default: null

RAIDZ expansion information.

Any of

• ZPoolExpand
• Option 2

ZPoolExpand

Type: object
No Additional Properties

state Required

State

Type: string

Expansion state (e.g., SCANNING, FINISHED).

expanding_vdev Required

Expanding Vdev

Type: integer

Index of the vdev being expanded.

start_time Required

Start Time

Type: integer

Expansion start time (unix timestamp).

end_time Required

End Time

Expansion end time as unix timestamp (null while expanding).

Any of

• Option 1
• Option 2

Type: integer

Type: null

bytes_to_reflow Required

Bytes To Reflow

Type: integer

Total bytes that need to be reflowed.

bytes_reflowed Required

Bytes Reflowed

Type: integer

Total bytes reflowed so far.

waiting_for_resilver Required

Waiting For Resilver

Type: integer

Non-zero if expansion is waiting for a resilver to complete.

total_secs_left Required

Total Secs Left

Estimated seconds remaining (null if not expanding).

Any of

• Option 1
• Option 2

Type: integer

Type: null

percentage Required

Percentage

Type: number

Expansion progress (between 0 and 100%).

Type: null

features

Features

Default: null

Pool feature flags.

Any of

• Option 1
• Option 2

Type: array of object
No Additional Items

Each item of this array must be:

ZPoolFeature

Type: object
No Additional Properties

name Required

Name

Type: string

Feature name.

guid Required

Guid

Type: string

Feature GUID.

description Required

Description

Type: string

Feature description.

state Required

State

Type: string

Feature state.

Type: null

Required roles: POOL_READ