# 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.

## Any of

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).

## Any of

Type: object

##

Each additional property must conform to the following schema

Type: string
Type: null

##

#### Children

The children of this zfs resource.

## Any of

Type: array
No Additional Items

##### Each item of this array must be:

Type: object
Type: null

Required roles: ZFS_RESOURCE_READ