pool.dataset.query

Query Pool Datasets with query-filters and query-options.

We provide two ways to retrieve datasets. The first is a flat structure (default), where all datasets in the system are returned as separate objects which contain all data there is for their children. This retrieval type is slightly slower because of duplicates in each object. The second type is hierarchical, where only top level datasets are returned in the list. They contain all the children in the children key. This retrieval type is slightly faster. These options are controlled by the query-options.extra.flat attribute (default true).

In some cases it might be desirable to only retrieve details of a dataset itself and not it’s children, in this case query-options.extra.retrieve_children should be explicitly specified and set to false which will result in children not being retrieved.

In case only some properties are desired to be retrieved for datasets, consumer should specify query-options.extra.properties which when null ( which is the default ) will retrieve all properties and otherwise a list can be specified like [“type”, “used”, “available”] to retrieve selective properties. If no properties are desired, in that case an empty list should be sent. It should be noted that specifying empty list will still retrieve user properties. If user properties are not desired, in that case query-options.extra.retrieve_user_props should be set to false.

query-options.extra.snapshots can be set to retrieve snapshot(s) of dataset in question.

query-options.extra.snapshots_recursive can be set to retrieve snapshot(s) recursively of dataset in question. If query-options.extra.snapshots_recursive and query-options.extra.snapshots are set, snapshot(s) will be retrieved recursively.

query-options.extra.snapshots_properties can be specified to list out properties which should be retrieved for snapshot(s) related to each dataset. By default only name of the snapshot would be retrieved, however if null is specified all properties of the snapshot would be retrieved in this case.

Type: object

Call parameters

Type: array
No Additional Items

Tuple Validation

Parameter 1: filters

filters

Type: array Default: []

List of filters for query results. See API documentation for "Query Methods" for more guidance.

No Additional Items

Each item of this array must be:

Type: object

Examples:

[
    [
        "name",
        "=",
        "bob"
    ]
]

[
    [
        "OR",
        [
            [
                [
                    "name",
                    "=",
                    "bob"
                ]
            ],
            [
                [
                    "name",
                    "=",
                    "larry"
                ]
            ]
        ]
    ]
]

Parameter 2: options

options

Type: object

Default:

{ "relationships": true, "extend": null, "extend_fk": [], "extend_context": null, "prefix": null, "extra": {}, "order_by": [], "select": [], "count": false, "get": false, "offset": 0, "limit": 0, "force_sql_filters": false }

Query options customize the results returned by a query method. More complete documentation with examples
are covered in the "Query methods" section of the TrueNAS API documentation.

No Additional Properties

relationships

Relationships

Type: boolean Default: true

extend

Extend

Default: null

Any of

• Option 1
• Option 2

Type: string

Type: null

extend_fk

Extend Fk

Type: array of string Default: []
No Additional Items

Each item of this array must be:

Type: string

extend_context

Extend Context

Default: null

Any of

• Option 1
• Option 2

Type: string

Type: null

prefix

Prefix

Default: null

Any of

• Option 1
• Option 2

Type: string

Type: null

extra

Extra

Type: object Default: {}

Extra options are defined on a per-endpoint basis and are described in the documentation for the associated
query method.

order_by

Order By

Type: array of string Default: []

An array of field names describing the manner in which query results should be ordered. The field names may
also have one of more of the following special prefixes: - (reverse sort direction), nulls_first: (place
any null values at the head of the results list), nulls_last: (place any null values at the tail of the
results list).

No Additional Items

Each item of this array must be:

Type: string

Example:

[
    "size",
    "-devname",
    "nulls_first:-expiretime"
]

select

Select

Type: array Default: []

An array of field names specifying the exact fields to include in the query return. The dot character .
may be used to explicitly select only subkeys of the query result.

No Additional Items

Each item of this array must be:

Any of

• Option 1
• Option 2

Type: string

Type: array
No Additional Items

Each item of this array must be:

Type: object

Example:

[
    "username",
    "Authentication.status"
]

count

Count

Type: boolean Default: false

Return a numeric value representing the number of items that match the specified query-filters.

get

Get

Type: boolean Default: false

Return the JSON object of the first result matching the specified query-filters. The query fails
if there specified query-filters return no results.

offset

Offset

Type: integer Default: 0

This specifies the beginning offset of the results array. When combined with the limit query-option
it may be used to implement pagination of large results arrays. WARNING: some query methods provide
volatile results and the onus is on the developer to understand whether pagination is appropriate
for a particular query API method.

limit

Limit

Type: integer Default: 0

This specifies the maximum number of results matching the specified query-filters to return. When
combined wtih the offset query-option it may be used to implement pagination of large results arrays.
WARNING: some query methods provide volatile results and the onus is on the developer to understand whether
pagination is appropriate for a particular query API method.

force_sql_filters

Force Sql Filters

Type: boolean Default: false

Return value

Result

Any of

• Option 1
• PoolDatasetQueryResultItem
• Option 3

Type: array of object
No Additional Items

Each item of this array must be:

PoolDatasetQueryResultItem

Type: object
No Additional Properties

id

Id

Type: string

type

Type

Type: string

name

Name

Type: string

pool

Pool

Type: string

encrypted

Encrypted

Type: boolean

encryption_root

Encryption Root

Any of

• Option 1
• Option 2

Type: string

Type: null

key_loaded

Key Loaded

Any of

• Option 1
• Option 2

Type: boolean

Type: null

children

Children

Type: array
No Additional Items

Each item of this array must be:

Type: object

user_properties

User Properties

Type: object

locked

Locked

Type: boolean

comments

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

quota_warning

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

quota_critical

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

refquota_warning

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

refquota_critical

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

managedby

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

deduplication

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

aclmode

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

acltype

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

xattr

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

atime

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

casesensitivity

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

checksum

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

exec

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

sync

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

compression

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

compressratio

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

origin

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

quota

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

refquota

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

reservation

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

refreservation

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

copies

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

snapdir

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

readonly

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

recordsize

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

sparse

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

volsize

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

volblocksize

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

key_format

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

encryption_algorithm

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

used

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

usedbychildren

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

usedbydataset

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

usedbyrefreservation

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

usedbysnapshots

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

available

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

special_small_block_size

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

pbkdf2iters

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

creation

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

snapdev

PoolDatasetEntryProperty

Type: object
No Additional Properties

parsed

Parsed

Type: object

rawvalue

Rawvalue

Any of

• Option 1
• Option 2

Type: string

Type: null

value

Value

Any of

• Option 1
• Option 2

Type: string

Type: null

source

Source

Any of

• Option 1
• Option 2

Type: string

Type: null

source_info

Source Info

Type: object

mountpoint

Mountpoint

Any of

• Option 1
• Option 2

Type: string

Type: null

PoolDatasetQueryResultItem

Type: object
No Additional Properties

id

Id

Type: string

type

Type

Type: string

name

Name

Type: string

pool

Pool

Type: string

encrypted

Encrypted

Type: boolean

encryption_root

Encryption Root

Any of

• Option 1
• Option 2

Type: string

Type: null

key_loaded

Key Loaded

Any of

• Option 1
• Option 2

Type: boolean

Type: null

children

Children

Type: array
No Additional Items

Each item of this array must be:

Type: object

user_properties

User Properties

Type: object

locked

Locked

Type: boolean

comments

Type: object

quota_warning

Type: object

quota_critical

Type: object

refquota_warning

Type: object

refquota_critical

Type: object

managedby

Type: object

deduplication

Type: object

aclmode

Type: object

acltype

Type: object

xattr

Type: object

atime

Type: object

casesensitivity

Type: object

checksum

Type: object

exec

Type: object

sync

Type: object

compression

Type: object

compressratio

Type: object

origin

Type: object

quota

Type: object

refquota

Type: object

reservation

Type: object

refreservation

Type: object

copies

Type: object

snapdir

Type: object

readonly

Type: object

recordsize

Type: object

sparse

Type: object

volsize

Type: object

volblocksize

Type: object

key_format

Type: object

encryption_algorithm

Type: object

used

Type: object

usedbychildren

Type: object

usedbydataset

Type: object

usedbyrefreservation

Type: object

usedbysnapshots

Type: object

available

Type: object

special_small_block_size

Type: object

pbkdf2iters

Type: object

creation

Type: object

snapdev

Type: object

mountpoint

Mountpoint

Any of

• Option 1
• Option 2

Type: string

Type: null

Type: integer

Required roles: DATASET_READ