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.

NOTE: To query snapshots, use zfs.resource.snapshot.query.

Raises: ValidationError: If: - Snapshot paths are provided (use zfs.resource.snapshot.query) - Overlapping paths are provided with get_children=True

Examples: # Query all resources with default properties query()

# Query specific resources with all properties query({“paths”: [“tank/documents”, “tank/media”]})

# Query with specific properties and children query({ “paths”: [“tank”], “properties”: [“mounted”, “compression”, “used”], “get_children”: True })

# Get hierarchical view of resources query({“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": false, "nest_results": false, "get_children": false, "max_depth": 0, "exclude_internal_paths": true, "get_tier": 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: false

Retrieve source information for a zfs property.

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.

Max Depth

Type: integer Default: 0

Maximum depth to recurse when retrieving children. A value of 0 means unlimited recursion (default behavior). A value greater than 0 limits the recursion to that many levels deep.

When maxdepth > 0, getchildren is automatically enabled if not already set.

Examples:
maxdepth=0: Retrieve all descendants (unlimited depth).
maxdepth=1: Retrieve only immediate children.
maxdepth=2: Retrieve children and grandchildren.
maxdepth=3: Retrieve up to great-grandchildren.

Note: When maxdepth > 0 is specified, it takes priority over getchildren. The depth is measured from the specified path(s), not from the pool root.

Get Tier

Type: boolean Default: false

Retrieve tier classification (REGULAR/PERFORMANCE) for FILESYSTEM resources. Requires an active Enterprise license with ZFS tiering enabled.

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.


The zfs properties for the resource.

Type: object
Type: null

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

Default: null

Tier classification for FILESYSTEM resources. None if not requested or not applicable.

TierInfo

Type: object
No Additional Properties

Tier Type

Type: enum (of string)

Storage performance tier for this share.

Must be one of:
  • "REGULAR"
  • "PERFORMANCE"

Default: null

Most recent rewrite job for this share's dataset, or null if no job history exists.

ZfsTierRewriteJobEntry

Type: object
No Additional Properties

Tier Job Id

Type: string

Rewrite job identifier in dataset_name@job_uuid format.

Must be at least 1 characters long

Dataset Name

Type: string

ZFS dataset this job is operating on.

Must be at least 1 characters long

Job Uuid

Type: string

Unique identifier for this rewrite job.

Must be at least 1 characters long

Status

Type: enum (of string)

Current lifecycle state of the job.

  • COMPLETE - All files in the dataset have been processed.
  • RUNNING - Job is actively processing files.
  • QUEUED - Job is waiting for a free execution slot (see max_concurrent_jobs).
  • CANCELLED - Job was stopped via zfs_tier_job.cancel. Not resumable.
  • STOPPED - Job was RUNNING but its process is no longer active (e.g. daemon restart). This state is computed on read and is never written to persistent storage.
  • ERROR - Job halted due to an unrecoverable error. Use zfs_tier_job.recover to retry failed files.
Must be one of:
  • "COMPLETE"
  • "RUNNING"
  • "QUEUED"
  • "CANCELLED"
  • "STOPPED"
  • "ERROR"
Type: null
Type: null


Required roles: ZFS_RESOURCE_READ