nvmet.namespace.query

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:

{ "extra": {}, "order_by": [], "select": [], "count": false, "get": false, "offset": 0, "limit": 0, "force_sql_filters": false }

Query options including pagination, ordering, and additional parameters.

No Additional Properties

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.

Value must be greater or equal to 0

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.

Value must be greater or equal to 0 and lesser or equal to 10000

force_sql_filters

Force Sql Filters

Type: boolean Default: false

Force use of SQL for result filtering to reduce response time. May not work for all methods.

Return value

Result

Any of

• Option 1
• NVMetNamespaceEntry
• Option 3
• Option 4
• Option 5

Type: array of object
No Additional Items

Each item of this array must be:

NVMetNamespaceEntry

Type: object
No Additional Properties

id Required

Id

Type: integer

Unique identifier for the NVMe-oF namespace.

nsid

Nsid

Default: null

Namespace ID (NSID).

Each namespace within a subsystem has an associated NSID, unique within that subsystem.

If not supplied during namespace creation then the next available NSID will be used.

Any of

• Option 1
• Option 2

Type: integer

Value must be greater or equal to 1 and strictly lesser than 4294967295

Type: null

subsys Required

Type: object

NVMe-oF subsystem that contains this namespace.

device_type Required

Device Type

Type: enum (of string)

Type of device (or file) used to implement the namespace.

Must be one of:

• "ZVOL"
• "FILE"

device_path Required

Device Path

Type: string

Path to the device or file being used to implement the namespace.

When device_type is:

• "ZVOL": device_path is e.g. "zvol/poolname/zvolname"
• "FILE": device_path is e.g. "/mnt/poolmnt/path/to/file". The file will be created if necessary.

Must be at least 1 characters long

dataset Required

Dataset

The ZFS dataset containing the file-based namespace (e.g., 'tank/nvmet'). Returns null for ZVOL-based namespaces or if the FILE path cannot be resolved yet (encrypted dataset not unlocked, etc.). This is a read-only field automatically populated from "device_path".

Any of

• Option 1
• Option 2

Type: string

Type: null

relative_path Required

Relative Path

The path of the file-based namespace relative to the dataset mountpoint (e.g., 'namespaces/ns1.img'). An empty string indicates the file is at the dataset root. Returns null for ZVOL-based namespaces or if the path cannot be resolved yet. This is a read-only field automatically populated from "device_path".

Any of

• Option 1
• Option 2

Type: string

Type: null

filesize

Filesize

Default: null

When device_type is "FILE" then this will be the size of the file in bytes.

Any of

• Option 1
• Option 2

Type: integer

Type: null

device_uuid Required

Device Uuid

Type: string

Unique device identifier for the namespace.

Must be at least 1 characters long

device_nguid Required

Device Nguid

Type: string

Namespace Globally Unique Identifier for the namespace.

Must be at least 1 characters long

enabled

Enabled

Type: boolean Default: true

If enabled is False then the namespace will not be accessible.

Some namespace configuration changes are blocked when that namespace is enabled.

locked Required

Locked

Reflect the locked state of the namespace.

The underlying device_path could be an encrypted ZVOL, or a file on an encrypted dataset. In either case locked will be True if the underlying entity is locked.

Any of

• Option 1
• Option 2

Type: boolean

Type: null

NVMetNamespaceEntry

Type: object
No Additional Properties

id Required

Id

Type: integer

Unique identifier for the NVMe-oF namespace.

nsid

Nsid

Default: null

Namespace ID (NSID).

Each namespace within a subsystem has an associated NSID, unique within that subsystem.

If not supplied during namespace creation then the next available NSID will be used.

Any of

• Option 1
• Option 2

Type: integer

Value must be greater or equal to 1 and strictly lesser than 4294967295

Type: null

subsys Required

Type: object

NVMe-oF subsystem that contains this namespace.

device_type Required

Device Type

Type: enum (of string)

Type of device (or file) used to implement the namespace.

Must be one of:

• "ZVOL"
• "FILE"

device_path Required

Device Path

Type: string

Path to the device or file being used to implement the namespace.

When device_type is:

• "ZVOL": device_path is e.g. "zvol/poolname/zvolname"
• "FILE": device_path is e.g. "/mnt/poolmnt/path/to/file". The file will be created if necessary.

Must be at least 1 characters long

dataset Required

Dataset

The ZFS dataset containing the file-based namespace (e.g., 'tank/nvmet'). Returns null for ZVOL-based namespaces or if the FILE path cannot be resolved yet (encrypted dataset not unlocked, etc.). This is a read-only field automatically populated from "device_path".

Any of

• Option 1
• Option 2

Type: string

Type: null

relative_path Required

Relative Path

The path of the file-based namespace relative to the dataset mountpoint (e.g., 'namespaces/ns1.img'). An empty string indicates the file is at the dataset root. Returns null for ZVOL-based namespaces or if the path cannot be resolved yet. This is a read-only field automatically populated from "device_path".

Any of

• Option 1
• Option 2

Type: string

Type: null

filesize

Filesize

Default: null

When device_type is "FILE" then this will be the size of the file in bytes.

Any of

• Option 1
• Option 2

Type: integer

Type: null

device_uuid Required

Device Uuid

Type: string

Unique device identifier for the namespace.

Must be at least 1 characters long

device_nguid Required

Device Nguid

Type: string

Namespace Globally Unique Identifier for the namespace.

Must be at least 1 characters long

enabled

Enabled

Type: boolean Default: true

If enabled is False then the namespace will not be accessible.

Some namespace configuration changes are blocked when that namespace is enabled.

locked Required

Locked

Reflect the locked state of the namespace.

The underlying device_path could be an encrypted ZVOL, or a file on an encrypted dataset. In either case locked will be True if the underlying entity is locked.

Any of

• Option 1
• Option 2

Type: boolean

Type: null

Type: array of object
No Additional Items

Each item of this array must be:

Type: object

Type: object

Type: integer

Required roles: SHARING_NVME_TARGET_READ