Sorting and filtering list results

Cloud Key Management Service supports filtering and sorting results from the following list operations.

Support for sorting and filtering in a list operation is indicated by the presence of filter and orderBy string fields in the list request body. Both fields use a simple language for referring to the fields in the object that is being sorted and/or filtered.

Filter syntax

The filter syntax consists of an expression on one or more fields of the objects being filtered.

You can use the following expression operators.

Operator Description
= Equality.
> Greater than.
< Less than.
=> Greater than or equal to.
<= Less than or equal to.
!=
-
NOT
Inequality.
The following are equivalent:
name != "quickstart"
-name="quickstart"
NOT name = "quickstart"
: Containment. This is a case-insensitive substring match.
As an example, name: "cloud" filters on resources that contain cloud (case-insensitive) in the resource name.
AND Logical AND. A space is equivalent to AND, so the following are equivalent:
name: "cloud" AND name: "kms"
name: "cloud" name: "kms"
OR Logical OR.

AND and OR operators are accepted at the same grouping level. OR takes precedence over AND. You can use parentheses to override default precedence.

When filtering on time values, encode the time as a string in the RFC 3399 format, such as 2019-06-20T01:30:15Z.

When accessing a subfield, use dot syntax. For example, the CryptoKey resource contains the primary field. You can filter CryptoKey results on the subfield primary.algorithm for a specific algorithm:

primary.algorithm=RSA_SIGN_PSS_2048_SHA256

Use the dot syntax for a label, and any other map type:

labels.team=alpha

A quoted string is interpreted as a single value rather than a sequence of values.

Filterable fields

You can filter on any field in the objects being returned.

List method Link to filterable fields
keyRings.list KeyRing fields
cryptoKeys.list CryptoKey fields
cryptoKeyVersions.list CryptoKeyVersion fields
importJobs.list ImportJob fields

Sort-order syntax

You can sort results by the resource's name field on the objects. The following shows the supported sort-order values for the orderBy field.

Value Description
'' (empty string) Results are sorted in the default order.
'name' Results are sorted in ascending order by the resource's name field.
'name desc' Results are sorted in descending order by the resource's name field.