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 PropertiesExtra options are defined on a per-endpoint basis and are described in the documentation for the associated query method.
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).
[
"size",
"-devname",
"nulls_first:-expiretime"
]
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.
[
"username",
"Authentication.status"
]
Return a numeric value representing the number of items that match the specified query-filters.
Return the JSON object of the first result matching the specified query-filters. The query fails if there specified query-filters return no results.
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
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 use of SQL for result filtering to reduce response time. May not work for all methods.
Unique identifier for the bucket.
Bucket name, following the S3 rules. Three to 63 characters of lowercase letters, digits, dots and hyphens, starting and ending with a letter or digit, no adjacent dots, and never an IPv4 address.
Must match regular expression:^[a-z0-9][a-z0-9.-]*[a-z0-9]$
Must be at least 3 characters long
Must be at most 63 characters long
The ZFS dataset the bucket is. Created by sharing.s3.create and owned by it. Objects live in the s3data directory under its mount point, which the S3 service creates on its next start, owned by owner. Under the S3 and MULTIPROTOCOL permissions models every object is written under the account that put it, so a grantee other than the owner can write only where that directory's permissions allow; set an ACL on it as for any share, or choose S3_BUCKET_OWNER_ENFORCED.
Must be at least 1 characters long
Whether the bucket is served. Toggling restarts the S3 service.
Account that owns the bucket and bypasses its grants, owns the s3data directory when the S3 service creates it, and owns every object under the S3_BUCKET_OWNER_ENFORCED permissions model. Given by name, held by uid: the name is resolved when set and again whenever the bucket is read, so a renamed account reads as its new name, a reused name never inherits the bucket, and an account that no longer exists reads as its uid. Changing the owner later moves the grants, not the directory.
Must be at least 1 characters long
The uid that owns the bucket.
Who may access the bucket and how, beyond its owner.
No Additional ItemsWho the grant applies to. A user, a group, or everyone with a valid access key.
The uid of the user or the gid of the group. Required for USER and GROUP, forbidden for EVERYONE.
What the grant allows. READONLY, WRITEONLY and READWRITE allow the matching operations. DENY refuses every operation for the principal and outranks the bucket owner.
Name of the user or group the grant applies to, resolved for display. Empty for EVERYONE.
Whose account the S3 service touches the dataset under. S3 when only the S3 service writes it: the grants alone decide a read, and every object is written under the account that put it. MULTIPROTOCOL when other protocols share the tree: a read is also subject to the file permissions those protocols set. S3_BUCKET_OWNER_ENFORCED when only the S3 service writes it and every object is to be owner's: every read and write runs as the owner, so the grants are the whole of the bucket's access control and a grantee needs no permissions on the s3data directory. A request is still authorized and audited as the account that made it.
Bucket versioning state.
Patterns over the names of the bucket dataset's ZFS snapshots, * and ? the only metacharacters, each matched against a whole name. Every snapshot a pattern selects serves each object's state frozen in it as a read-only version: listed by ListObjectVersions and read by its version id. Empty serves none. Requires versioning to be ENABLED or SUSPENDED.
Must be at least 1 characters long
How many of the newest selected snapshots one ListObjectVersions listing consults. Bounds the listing alone: a selected snapshot beyond it still serves by its version id.
Value must be greater or equal to 1 and lesser or equal to 4294967295
What the ETag of an object assembled from a multipart upload is. COMPOSITE is the S3 construction: each part's ETag is the MD5 of its bytes and the object's is the MD5 of those digests with the part count appended, which costs an MD5 pass over every part. MINTED skips that pass for a part whose upload carried no Content-MD5 and gives the object an opaque token instead. Choose it only where nothing writing the bucket reads its ETags, such as a backup target that declares its own checksums: a client that recomputes the composite to verify or resume an upload sees a value it cannot match.
Whether object lock is enabled. Requires versioning to be ENABLED and a permissions model other than MULTIPROTOCOL: a locked bucket is the S3 service's alone.
Retention mode of the default object lock rule, or null for no default rule.
Retention period of the default object lock rule in days, up to 36500 (a hundred years).
Value must be greater or equal to 1 and lesser or equal to 36500
Actions audited on this bucket, ALL, or an empty list to audit nothing. null inherits the service's default_audit. Requires an Enterprise license.
"ALL"
Overflow behavior for this bucket's audit records, or null to inherit the service's default.
Whether the bucket's dataset is locked. Read only.