> [!WARNING]
>
> **Beta**
>
>
> This feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the
> [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

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

- [keyRings.list](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings/list.md.txt)
- [cryptoKeys.list](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys/list.md.txt)
- [cryptoKeyVersions.list](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys.cryptoKeyVersions/list.md.txt)
- [importJobs.list](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.importJobs/list.md.txt)

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](https://tools.ietf.org/html/rfc3339) format, such as
`2019-06-20T01:30:15Z`.

When accessing a subfield, use dot syntax. For example, the [`CryptoKey`](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys.md.txt)
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](https://docs.cloud.google.com/kms/docs/creating-managing-labels.md.txt), 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](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings/list.md.txt) | [KeyRing fields](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.md.txt#KeyRing.FIELDS) |
| [cryptoKeys.list](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys/list.md.txt) | [CryptoKey fields](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys.md.txt#CryptoKey.FIELDS) |
| [cryptoKeyVersions.list](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys.cryptoKeyVersions/list.md.txt) | [CryptoKeyVersion fields](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys.cryptoKeyVersions.md.txt#CryptoKeyVersion.FIELDS) |
| [importJobs.list](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.importJobs/list.md.txt) | [ImportJob fields](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.importJobs.md.txt#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]
> **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](https://docs.cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys.md.txt#CryptoKey.FIELDS).

> [!NOTE]
> **Note:** If you sort `CryptoKeyVersion` resources by `name`, they are sorted numerically by the version number.