Sorting and filtering list results

Beta

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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

• keyRings.list
• cryptoKeys.list
• cryptoKeyVersions.list
• importJobs.list

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.

Note: To find the primary key version, do not attempt to sort for the version with the newest creation date. There is no guarantee that the primary version is the newest version or that the newest version is the primary version. Instead, query using the primary field.

Note: If you sort CryptoKeyVersion resources by name, they are sorted numerically by the version number.