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.
Raises: ValidationError: If: - Snapshot paths are provided (snapshots not currently supported) - Overlapping paths are provided with get_children=True - Requested paths don’t exist (errno.ENOENT)
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})
No Additional Items
Tuple Validation
Parameter 1: data
data
Type: objectNo 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 ItemsEach item of this array must be:
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.
No Additional Items
Each item of this array must be:
Get User Properties
Type: boolean Default: falseRetrieve user properties for zfs resource(s).
Get Source
Type: boolean Default: trueHidden 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: falseReturn 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: falseRetrieve children information for the zfs resource.
Result
Type: array of objectNo Additional Items
Each item of this array must be:
ZFSResourceEntry
Type: objectNo Additional Properties
Createtxg
Type: integerTransaction group when resource was created.
Guid
Type: integerGlobally unique identifier for the resource.
Name
Type: stringThe name of the zfs resource.
Pool
Type: stringThe name of the zpool that the zfs resouce is associated to.
ZFSPropertiesEntry
Type: objectThe zfs properties for the resource.
No Additional PropertiesAclinherit
Type: objectControls how ACEs are inherited for new files/directories.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
SourceValue
Type: objectNo Additional Properties
Type
Type: enum (of string)The source type.
Must be one of:
- "NONE"
- "DEFAULT"
- "TEMPORARY"
- "LOCAL"
- "INHERITED"
- "RECEIVED"
Value
The source value.
Value
The parsed raw value of the property.
Aclmode
Type: objectDetermines how ACLs are modified during chmod operations.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Acltype
Type: objectSpecifies type of ACL to use (off, nfsv4, posix).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Atime
Type: objectControls whether access time is updated on file reads.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Canmount
Type: objectControls whether filesystem can be mounted.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Casesensitivity
Type: objectDetermines filename matching algorithm sensitivity.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Defaultgroupobjquota
Type: objectDefault object quota for new groups.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Defaultgroupquota
Type: objectDefault space quota for new groups.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Defaultprojectobjquota
Type: objectDefault object quota for new projects.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Defaultprojectquota
Type: objectDefault space quota for new projects.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Defaultuserobjquota
Type: objectDefault object quota for new users.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Defaultuserquota
Type: objectDefault space quota for new users.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Devices
Type: objectControls whether device files can be opened.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Direct
Type: objectControls direct I/O behavior (standard or always).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Dnodesize
Type: objectControls dnode size for new objects.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Exec
Type: objectControls whether programs can be executed from filesystem.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Filesystem Count
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Filesystem Limit
Type: objectMaximum number of child filesystems allowed.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Longname
Type: objectControls support for long filenames.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Mounted
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Mountpoint
Type: objectControls mount point used for this filesystem.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Nbmand
Type: objectControls non-blocking mandatory locking behavior.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Normalization
Type: objectUnicode normalization property for filenames.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Overlay
Type: objectControls overlay mount behavior.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Quota
Type: objectLimits space consumed by dataset and descendants.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Recordsize
Type: objectMaximum block size for files in this filesystem.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Refquota
Type: objectLimits space consumed by dataset itself (no descendants).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Refreservation
Type: objectMinimum space reserved for volume itself.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Relatime
Type: objectControls relative access time updates.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Setuid
Type: objectControls setuid/setgid bit respect on executable files.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Snapdir
Type: objectControls snapshot directory visibility (hidden or visible).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Special Small Blocks
Type: objectSize threshold for storing blocks on special vdevs.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Utf8Only
Type: objectControls whether only UTF-8 filenames are allowed.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Version
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Volmode
Type: objectControls volume mode (default, geom, dev, none).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Vscan
Type: objectControls virus scanning behavior.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Xattr
Type: objectControls extended attribute behavior (on, off, sa, dir).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Zoned
Type: objectControls whether filesystem is managed from a zone.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Available
Type: objectAmount of space available to dataset and its children.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Checksum
Type: objectControls checksum algorithm used to verify data integrity.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Compression
Type: objectControls compression algorithm used for this dataset.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Compressratio
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Context
Type: objectSELinux security context for the dataset.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Copies
Type: objectControls number of copies of data stored (1, 2, or 3).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Createtxg
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Creation
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Dedup
Type: objectControls data deduplication for the dataset.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Defcontext
Type: objectSELinux default security context for new files.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Encryption
Type: objectControls encryption cipher suite for the dataset.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Encryptionroot
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Fscontext
Type: objectSELinux filesystem security context.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Guid
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Keyformat
Type: objectEncryption key format (raw, hex, or passphrase).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Keylocation
Type: objectLocation where encryption key is stored.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Keystatus
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Logbias
Type: objectControls ZIL write behavior (latency or throughput).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Logicalreferenced
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Logicalused
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Mlslabel
Type: objectMulti-level security label for the dataset.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Objsetid
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Origin
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Pbkdf2Iters
Type: objectNumber of PBKDF2 iterations for key derivation.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Prefetch
Type: objectControls prefetch behavior (all, metadata, or none).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Primarycache
Type: objectControls primary cache usage (all, metadata, or none).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Readonly
Type: objectControls whether dataset can be modified.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Receive Resume Token
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Redact Snaps
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Redundant Metadata
Type: objectControls redundant metadata storage (all or most).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Refcompressratio
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Referenced
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Reservation
Type: objectMinimum space reserved for dataset and descendants.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Rootcontext
Type: objectSELinux root directory security context.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Secondarycache
Type: objectControls secondary cache usage (all, metadata, or none).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Snapdev
Type: objectControls snapshot device visibility (hidden or visible).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Snapshot Count
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Snapshot Limit
Type: objectMaximum number of snapshots allowed.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Snapshots Changed
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Sync
Type: objectControls synchronous write behavior (standard, always, disabled).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Type
PropertyValue
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Used
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Usedbychildren
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Usedbydataset
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Usedbyrefreservation
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Usedbysnapshots
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Written
Type: objectNo Additional Properties
Raw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Volblocksize
Type: objectBlock size for volume (typically 8K or 16K).
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Volsize
Type: objectLogical size of the volume.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
Volthreading
Type: objectControls volume threading behavior.
No Additional PropertiesRaw
Type: stringThe raw value of the property.
The source from where this property received its value.
Value
The parsed raw value of the property.
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).
Each additional property must conform to the following schema
Type: stringChildren
Type: arrayThe children of this zfs resource.
No Additional ItemsEach item of this array must be:
Required roles: ZFS_RESOURCE_READ