Where "condition" is a metadata key name filter in the form:
{selector} {operator}
{argument},
For example:
LastModified > 2018-03-01T11:22:00Z
selector
A searchable key name associated with the bucket.
operator
An operator. One of: ==, >, <, <=, >=
argument
A value that the selector is tested against.
attributes=[fieldname,...]
Specifies any optional object attributes that should be included in the report. Attribute values will be included in the report where that attribute is present on the object. The optional attribute values comprise:
ContentEncoding
ContentType
Retention
Expiration
Expires
In addition, it is possible to return the non-indexed metadata associated with objects that are returned by the search query. The following:
ALL
Lists both system and user metadata associated with the returned objects.
ALL_SMD
Lists the system metadata associated with the returned objects.
ALL_UMD
Lists the user metadata associated with the returned objects.
sorted=[selector]
Specifies one searchable key name associated with the bucket. The key name must be a key that appears in the expression. In the absence of &sorted=keyname, the output will be sorted according to the first key name that appears in the query expression.
NOTE: If "or" operators are used in the expression, the sort order is indeterminate.
include-older-versions=[true|false]
When S3 versioning is enabled on a bucket, setting this to true will return current and older versions of objects that match the expression. Default is false.
max-keys
The maximum number of objects that match the query that should be returned. If there are more objects than the max-keys, a marker will be returned that can be used to retrieve more matches.
marker
The marker that was returned by a previous query and that indicates the point from which query matches should be returned.
Datetime queries
Datetime values in user metadata are specified in ISO-8601 format
yyyy-MM-dd'T'HH:mm:ssZ and are persisted by ECS in that format. Metadata queries also use this format. However, ECS persists datetime values for system metadata as epoch time, the number of milliseconds since the beginning of 1970.
When a query returns results, it returns the datetime format persisted by ECS. An example of the two formats is shown below.
User metadata upload header example:
-H x-amz-meta-Foo:2018-03-06T12:00:00Z
User and System query expression format:
?query=CreateTime>2018-01-01T00:00:00Z and x-amz-meta-Foo==2018-03-06T12:00:00Z
You can specify the maximum number of objects that will be returned by a query using the max-keys query parameter.
The example below specified a maximum number of objects as 3.
?query=CreateTime>2018-01-01T00:00:00Z and x-amz-meta-Foo==2018-03-06T12:00:00Z&max-keys=3
Where a query matches more objects than the max-keys that has been specified, a marker will also be returned that can be used to return the next page objects that match the query but were not returned.
The query below specifies a marker that has been retrieved from a previous query:
?query=CreateTime>2018-01-01T00:00:00Z and x-amz-meta-Foo==2018-03-06T12:00:00Z&max-keys=3&marker=rO0ABXNyAD...
When the returned objects are the final page of objects, the
IsTruncated tag value is returned as
false. Else, the
IsTruncated tag value is returned as
True.
NOTE: Only if the
IsTruncated tag value is returned as
True, the
NextMarker tag appears.
Using special characters in queries
You can use special characters in queries
The use of url-encoding is required to ensure that special characters are received correctly by the ECS REST service and quoting can be required to ensure that when ECS parses the query it does not mis-interpret symbols. For example:
When querying on x-amz-meta values, special characters must be url-encoded. For example: when using "%" (ASCII 25 hex), or "/" ( ASCII 2F), they must be encoded as %25 and 2F, respectively.
When querying on x-amz-meta values that have SQL-reserved characters the reserved characters must be escaped. This is to ensure that the SQL parser used by ECS does not consider them operators. For example: 'ab < cd' (that is, make sure a pair of quotes is passed into the service so that the SQL parser used by ECS does not consider them operators). The SQL-reserved characters include comparison operators (=, <, >, +, -, !, ~) and syntax separators (comma, semicolon).
Different ways of quoting are possible and depend on the client being used. An example for Unix command-line tools like
S3curl.pl, would be:
?query="'ab+cd<ed;ef'"
In this case, the search value is single-quoted and that is wrapped in double quotes.
Prefix capability in metadata search
You can use prefix capability in metadata search
S3 API metadata search supports the prefix and delimiter parameters. It follows the standard S3 definition of these parameters. Prefix capability effectively transforms every single metadata query into a multi query request with AND operation between prefix and the query string. In other words, it is possible to combine the AND and OR predicates in the queries.
S3 API metadata is modified to support prefix and delimiter parameters as described below:
GET /bucketName/?prefix={prefix}&delimiter={delimiter}&query={queryString}
Limitations
A prefix is always applied before the actual query.
Custom sorting is not supported with prefixes. If sorting is specified together with a prefix, the API returns 400 Bad Request.
Objects are returned in lexicographical order.
Using
ObjectName in a query string together with a prefix is not allowed. It creates ambiguity as both filter objects based on name. If both are specified, the API returns 400 Bad Request.
Metadata search example
You can use metadata search example
The example below uses the S3 API to search a bucket for a particular object size and user metadata value match.
NOTE: Some REST clients may require that you encode "spaces" with url code %20.