Search Query Arguments

The following table lists all the search query arguments, their values, and usage along with examples:













Requests a search query and specifies the desired output format. This query argument is required to trigger a domain/bucket listing query. This format applies to the body portion of the HTTP/1.1 response and does not affect the format of the response headers. All search operations are available with either format.





Filters the search to certain buckets one of these ways:

  • Greater/less than comparison, for buckets in numbered ranges: 0123, 0124, 0125, ... (context>=0124)

  • Wildcard matches, for buckets matching a prefix: us-tx, us-ky, us-tn, us-ga, ... (context=us-*)

    • Wildcards are supported for matching on prefixes, so use an asterisk at the end of the string.

    • Wildcard matching across many buckets may impact performance.

To restrict search to a bucket, include the bucket in the URL path. Always use with use domain={domain-name}.





Specifies a search filtered to the context identified by the UUID given.




Used in a listing query to find any annotation objects that may exist for a given ETag (or earlier query result “hash”). See and




In a normal SCSP storage request, the required Host header is the assumed domain (or context) for the operation. Most HTTP/1.1 clients and browsers use the host portion of the URL as the value for the Host header in the Swarm request. Supply the domain argument to explicitly override it if the value of the Host request header does not match the domain name. A domain argument always has precedence over the Host header in the HTTP/1.1 request.

Set the value equal to nothing (empty string) to find unnamed objects not tenanted in any domain.




none (ignored)

Used for listing the domains within a cluster. No value is used with this argument.





Dynamically queries the disk usage for a domain or bucket context. With du, use the size=0 query argument (to shorten the output by preventing the return of the request body) and add any filters needed. The computed result value appears in the Castor-System-Bytes-Used[-With-Reps]   response header.

  • withoutreps sizes the content uploaded: it finds the sum of the bytes of the unique objects being stored.

  • withreps sizes the storage impact: it finds the underlying disk space impact of the objects stored in a domain or bucket context, a value weighted by the expected number of replicas in the cluster, which is an approximation of the data footprint of the results.

See Storage in Use for how to query the storage in use for domains and buckets.



any indexed metadata field, such as: 


Filters results to those matching the operations on one or more specified fields. Multiple filters are joined by a logical AND; to specify OR, add the &or argument.

Supports standard comparison operators on specific fields to filter the results returned:

  • a = b, equal to  

  • a <= b, less than or equal to  

  • a >= b, greater than or equal to

This is an overloading of normal query argument processing.

&x-width-meta<=800 &x-height-meta<=600

&content-type=image/bmp&or &content-type=image/png



Comma-separated list of field names, or all

Replaces the default fields and specifies, as a comma-separated list, which fields to display in the output (See

Use fields=all on bucket and domain listing requests to return all available fields on each record in the response. (v9.2)




yes/true to activate, no/false to inhibit

On a write (POST, PUT, COPY, APPEND, DELETE) request, forces immediate search indexing of the newly written/deleted object.

Appears on Gateway requests when enabling the  option  EnhancedListingConsistency. (v9.3)



now or wait to activate, no/false to inhibit

On a read (listing query GET) request, forces consistency of results returned on the listing.

  • now performs a refresh on the index in Elasticsearch immediately before preforming the listing query.

  • wait delays execution of the listing query to provide Elasticsearch time to refresh the index.

Appears on Gateway requests when enabling the  option EnhancedListingConsistency. (v9.3)



empty value or a comma-separated list of sorted column key values

Provides a mechanism to use multiple requests to receive a complete result set. Defaults to &sort=name.

Used with the size argument to paginate large result sets. Use an empty key to begin a new search. Use the last sort key value of the results on the next request to continue pagination from that place on the next request.



to activate

Joins them with a logical OR (default is AND) when used with multiple field comparisons. Defaults to false.




Matches the string to the start (prefix) of the object's name or UUID. The names of the objects in the output list share the same prefix string.

  • Named objects are always contained within a bucket, and the first "/" following the bucket name is the delimiter. Any additional slashes following the first slash are part of the object's name. That is, for /photo/Q1/apple.jpg, where photo is the bucket, retrieve the object using prefix=Q1.

  • Unnamed objects require the additional argument stype=unnamed to match on UUIDs.

To find untenanted unnamed objects, include "domain=" (empty string).






Constrains the number of results to be returned by the query. Defaults to 1000. This argument is equivalent in purpose to the "limit" or "max-keys" arguments in other cloud protocols.

The maximum is 50000 but we do not recommend using more than 10000.


This is the size of the result set, not the object size. To work with object size, use the field content-length.


Set size to 0 when no actual listing is needed, such as when using the "du" query argument.



Comma-separated list of field names, with optional modifier :asc|:desc

Sets the sort order of one or more fields, with the first field sorting first. Sorting direction defaults to ascending (:asc); to specify descending (:desc), add the modifier to one or more of the fields.



Comma-separated list of Swarm types

Specifies the type of objects being requested in a search. Defaults to all.

Valid values: domain, bucket, named, alias, immutable, unnamed, all




Allows filtering updateable (named and alias) objects by versioning status, checking whether versioning was enabled in the context at the time they are written. Checks the value of the Castor‑System‑IsVersioned header. (v10.0)





true|(no value)
| previous

name of object

first part of  name

True (or no value) requests a listing of all versions of all objects, including the current.
Previous requests past versions (v10.2).

Requests a listing of all versions of the named object.

Requests a listing of all versions of all objects matching the prefix.

See .




Marker Argument

The marker argument provides a mechanism to retrieve a single result set using multiple HTTP requests. This is useful when a large result set is impractical to receive using one HTTP request. All marker operations work using a sorted result set. The system implicitly uses sort=name if a sort argument is not provided. The size argument is used to control how many items are returned per HTTP request.

On the first request, marker= (without a value) is used to indicate a request at the beginning of the result set. For subsequent requests, the last value(s) from the sort field(s) is used to indicate the last record received from the previous request.

Marker Example

Consider the following set of object names in the bucket dictionary.

applaud appoints arches basically boardwalk buffers carpet defender

Receive the first four items in the result set:

GET /dictionary?format=json& [ { "name": "applaud" }, { "name": "appoints" }, { "name": "arches" }, { "name": "basically" } ]

The last sort field value from the first request is basically, so the next request to continue receiving the result set is as follows:

GET /dictionary?format=json& [ { "name": "boardwalk" }, { "name": "buffers" }, { "name": "carpet" }, { "name": "defender" } ]

Since the result set is now exhausted, a subsequent request yields:

Sort vs Marker Relationship

The marker value is either the last value or values from the sort fields. The marker also contains the last field values in it if using:

Both ascending and descending sort orders are supported for each of the sort order fields.

The sort and marker must be a unique set of fields like tmborn,etag, to provide a total ordering. For example, sort=tmborn,name is not adequate when using a versions listing, since an object may have multiple versions with the same date and some will be missed if they hit a marker page boundary.

DataCore Swarm cannot return more results than specified by ?size and can only return objects after ?marker so the sort needs to be a total ordering.

Determining Completion

The set of objects in the cluster is continually changing so list/search requests are never complete. A criterion exists for considering marker requests complete. The Castor-System-Object-Count response header returns the number of objects remaining to enumerate including the records retrieved by the current request.

A client may consider the iterating request complete when the CastorObject-Count value equals the number of records retrieved by the current request.

Markers Across the Domain

A strategy for using markers to retrieve a result set of a search across the entire domain is to sort based on a unique tuple of metadata fields all objects have. For example,

See .

The name field is a UUID or an application-assigned string depending upon the object type.

Stype Argument

The stype argument allows filtering search results to certain types of objects. The following table lists the stype argument values:








(default) All object types


Bucket objects

Must reside in a domain.

stype=bucket is assumed implicitly when listing a domain, as this is a common operation. 


Content objects with an application-supplied name

Must reside in a bucket.

Search across buckets by specifying a domain and not including a bucket in the URL.


Content objects with a Swarm-assigned UUID

Cannot reside in a bucket. Tenanted in a domain unless cluster.enforceTenancy is disabled.


Immutable unnamed objects

A subset of stype=unnamed


Mutable unnamed objects

A subset of stype=unnamed

Avoid sending invalid requests when using stype, such as specifying stype=unnamed when searching within a bucket (which cannot contain unnamed objects). stype=named in a domain context is valid, even though named objects exist in a bucket because the bucket is contained within the domain context as well.

Use the unnamed, immutable, or alias value of the stype to select the desired set to list the unnamed objects in the domain. Include domain= set to nothing (empty string) to find untenanted unnamed objects. Untenanted unnamed objects return an empty string for the domain field in search and listing results.

© DataCore Software Corporation. · · All rights reserved.