zfs.resource.query

Query ZFS resources (datasets and volumes) with flexible filtering options.

This method provides a high-performance interface for retrieving information about ZFS resources, including their properties, hierarchical relationships, and metadata. The query can be customized to retrieve specific resources, properties, and control the output format.

To query snapshots, use zfs.resource.snapshot.query instead.

Invalid input is returned to the client as a JSON-RPC error response (code -32602, Invalid params); each failing condition appears in the error’s data.extra array with its own errno. A validation error is raised when:

  • a snapshot path is supplied (use zfs.resource.snapshot.query)

  • overlapping paths are supplied with get_children enabled

  • a requested path does not exist (ENOENT)

Examples:

Query all resources with default properties:

{}

Query specific resources:

{"paths": ["tank/documents", "tank/media"]}

Query specific properties with children:

{"paths": ["tank"], "properties": ["mounted", "compression", "used"], "get_children": true}

Get a hierarchical view of resources:

{"paths": ["tank"], "nest_results": true, "get_children": true}
Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: data

data

Type: object
Default:
{ "paths": [], "properties": [], "get_user_properties": false, "get_source": true, "nest_results": false, "get_children": false }

Query parameters for retrieving ZFS resource information.

 No Additional Properties

Paths

Type: array of string Default: []

A list of zfs filesystem or volume paths to be queried. In almost all scenarios, you should provide a path of what you want to query. By providing path(s) here, it allows the API to apply optimizations so that the requested information is retrieved as efficiently and quickly as possible.

Example 1:
{"paths": ["tank/foo"]} will query the relevant information for this resource only.
Example 2:
{"paths": ["tank/foo", "dozer/test"]} will query the relevant information for these resources only.

NOTE:
paths must be non-overlapping if get_children is True.
(i.e. this won't work and will raise a validation error)
{
"paths": ["tank/foo1", "tank/foo1/foo2"],
"get_children": True
}

All items must be unique

No Additional Items
Each item of this array must be:
Type: string

Properties

Default: []

A list of zfs properties to be retrieved. Defaults to an empty list which will return a default set of zfs properties. Setting this to None will retrieve no zfs properties.

Type: array of string
No Additional Items
Each item of this array must be:
Type: string
Type: null

Get User Properties

Type: boolean Default: false

Retrieve user properties for zfs resource(s).

Get Source

Type: boolean Default: true

Hidden field to retrieve source information for a zfs property.

NOTE: This should only ever be toggled by internal consumers and you should know what you're doing by toggling this to False.

Nest Results

Type: boolean Default: false

Return a nested object that associates all children to their respective parents in the filesystem. By default, each zfs resource is returned as a separate item in the array and is not associated to its parent.

Get Children

Type: boolean Default: false

Retrieve children information for the zfs resource.

Result

Type: array of object
No Additional Items
Each item of this array must be:

ZFSResourceEntry

Type: object
No Additional Properties

Createtxg

Type: integer

Transaction group when resource was created.

Guid

Type: integer

Globally unique identifier for the resource.

Name

Type: string

The name of the zfs resource.

Pool

Type: string

The name of the zpool that the zfs resouce is associated to.

Type: object

The zfs properties for the resource.

Type

Type: enum (of string)

The type of ZFS resource.

Must be one of:
  • "FILESYSTEM"
  • "VOLUME"

User Properties


Custom metadata properties with colon-separated names (max 256 chars).

Type: object

Each additional property must conform to the following schema

Type: string
Type: null

Children


The children of this zfs resource.

Type: array
No Additional Items
Each item of this array must be:
Type: object
Type: null


Required roles: ZFS_RESOURCE_READ