Search Operations

Search operations are an extremely powerful feature for locating content; they work on the metadata of the objects within the storage cluster. Searches use metadata matching constraints provided in the client request and return a list of objects that match those constraints.

Searches can take place across all objects within the domain or searches can be constrained to the context of a particular bucket. When full metadata search is enabled, you can use any custom metadata field value as a search constraint.

Best practice

Never apply a context filter redundantly in cases where Swarm filters by default, such as when searching for named objects in a bucket, buckets in a domain, or unnamed objects in a domain.

Performance Impact

Consider performance when designing searches spanning entire domains. context (domain and bucket) names are looked up from the contextid, so these domain-wide searches incur an additional performance penalty:

Retrieving the context field
Sorting on the context field
Filtering on the context field

Tip

Check the performance impact whenever sorting and filtering across an entire domain.

Search Examples

Unless otherwise noted, all matching operations are string-based comparisons:

Searching within a domain

GET /?format=json&domain=myDomain
	&content-type=application/pdf

Searching within a bucket

GET /myBucket?format=json&domain=myDomain
	&content-type=application/pdf

Searching by multiple field matching

GET /?format=json&domain=myDomain
	&x-color-meta=red
	&content-type=image/png

Using fields= to return specific field names

GET /myBucket?format=json&domain=myDomain
	&fields=name,content-length

Enabling case-insensitive search (name.lower)

You control case-sensitivity in your Elasticsearch queries by using the correct form of the name field:

name field: ES searches are case-sensitive, so searching FOO matches only FOO
name.lower field: ES searches are case-insensitive (as if all values were lowercase), so searching FOO matches FOO, Foo, foo

The Swarm search setting, search.caseInsensitive, is specific to SCSP queries, versus querying ES directly. When this is enabled, case-insensitive SCSP search queries are performed by default. (v9.0)

Swarm Setting	Effect
`search.caseInsensitive = 1`	All name-based searches use the name.lower field, so SCSP named searches are always case-insensitive.
`search.caseInsensitive = 0`	All name-based searches use the name field, and will therefore be case-sensitive.

Important

Custom metadata values are always indexed to be only case-sensitive or case-insensitive, depending on the value of search.caseInsensitive. If an index is built with the wrong setting, you must change the setting and build a new index.

Using content-length

The content-length field for objects is recognized as a numeric field and supports equality, less-than-equal-to, and greater-than-equal-to matching operators.

Tip

You can use ">=" or "=>" and "<=" or "=<".

Using content-length

GET /?format=json&domain=myDomain&content-length=1024 
GET /?format=json&domain=myDomain&content-length<=1024 
GET /?format=json&domain=myDomain&content-length>=1024

Important

The Content-MD5 metadata field cannot be used as a search constraint, either alone or with other fields. Use it only in the output fields for a search.