This page describes how to use filters when listing resources. This can be used
to reduce the returned set of resources when performing a list operation.
This feature is intended to provide a userful service to clients; it does not
affect the database queries generated for the operation and as such is not
designed to provide greater efficiency.
Starting in Boundary 0.1.8, when running a list action, a filter can be
specified. It uses the standard filter syntax used
elsewhere in Boundary. Unless otherwise specified for a given list endpoint, the
list of items being returned is looped through and the filter is run on the JSON
representation of that item. A good way to see what that data looks like is by
looking at representative JSON output on the command line; for example, the
following is the output of boundary targets list -scope-id p_1234567890 -format json on a dev instance (piped through jq for readability):
[{"id":"ttcp_1234567890","scope_id":"p_1234567890","scope":{"id":"p_1234567890","type":"project","name":"Generated project scope","description":"Provides an initial project scope in Boundary","parent_scope_id":"o_1234567890"},"name":"Generated target","description":"Provides an initial target in Boundary","created_time":"2021-02-24T22:19:50.640476Z","updated_time":"2021-02-24T22:19:50.640476Z","version":1,"type":"tcp","session_max_seconds":28800,"session_connection_limit":-1,"attributes":{"default_port":22},"authorized_actions":["read","update","delete","add-host-sets","set-host-sets","remove-host-sets","authorize-session"]}]
[{"id":"ttcp_1234567890","scope_id":"p_1234567890","scope":{"id":"p_1234567890","type":"project","name":"Generated project scope","description":"Provides an initial project scope in Boundary","parent_scope_id":"o_1234567890"},"name":"Generated target","description":"Provides an initial target in Boundary","created_time":"2021-02-24T22:19:50.640476Z","updated_time":"2021-02-24T22:19:50.640476Z","version":1,"type":"tcp","session_max_seconds":28800,"session_connection_limit":-1,"attributes":{"default_port":22},"authorized_actions":["read","update","delete","add-host-sets","set-host-sets","remove-host-sets","authorize-session"]}]
As the filter tests each entry being returned, it places the data under test
within the filter at /item.
On the CLI a filter can be given via -filter.
Double quotes are part of the filter syntax; when using the CLI, it is likely
easier to surround the filter with single quotes than to deal with escaping
double quotes.
When using the HTTP API, it is a filter query parameter.
Ensure that the query parameter is properly escaped! Most HTTP libraries will
do this for you. If you're having trouble, try using the -output-curl-string
flag with the Boundary CLI:
