Description
A
filter is a special type of parameter that reduces the volume of
the response. When you see
filter-definition
in a request
URL syntax, substitute a filter definition.
To create a filter
definition, start with the keyword
filter
, add
an modifier (if desired), then a field name (if allowed), and then
a value, using this syntax:
filter-modifier-field=value
The
modifiers you can add are listed in the following table.
Filter
|
Description
|
|
Returns all items for which the data in
field
exactly
matches
value
.
|
|
Returns all items with the string
value
within
field
,
even if
field
is not an exact match.
|
|
Filters out or excludes any items with
value
in
field
.
|
|
Limits the results to the number of rows
specified in
value
.
|
|
Starts the results at the index number specified
in
value
.
|
filter-gt-datefield=value
|
Selects all items with a date after
value
.
Works only with date fields. The value must be a date in
ISO
8601
format.
|
filter-lt-datefield=value
|
Selects all items with a date earlier than
value
.
Works only with date fields. The value must be a date in
ISO
8601
format.
|
filter-gte-datefield=value
|
Selects all items with a value in
field
greater
than or equal to
value
. Works only with date
fields. The value must be a
date
in
ISO
8601
format.
|
filter-lte-datefield=value
|
Selects all items with a value in
field
less
than or equal to
value
. Works only with dates.
The date uses
ISO 8601
format.
|
|
Selects all principals that are members
of a group, specified in a separate parameter. Takes a Boolean value
of
true
or
false
.
|
The
value
is case insensitive.
For example, either of these filters matches a meeting with the
name
August All Hands Meeting
:
&filter-name=August All Hands Meeting
&filter-name=august all hands meeting
Some modifiers
require a field name on which to filter results, for example,
name
. Other
filters do not take a field name. For those filters that accept
field names, the allowed fields vary for different actions. Check
a specific action in
Action reference
to
learn which field names you can use in filters.
Match and exclude items
filter-like-name=Goals&filter-out-status=active
Matches
any item with
Goals
(or any mixed case pattern of the same
string) in the name that is no longer active.
Match a start date
filter-gt-date-begin=2005-05-01&sort-name=asc
Matches
any item with a start date of May 1, 2005, sorting the items in
ascending order by name.
Match a date range
filter-gt-date-begin=2005-05-01&filter-lt-date-begin=2005-05-31
Returns
all items with a start date after May 1, 2005 and before May 31,
2005.