From c113182fbbef72e390371bc40ce3e80b46975b14 Mon Sep 17 00:00:00 2001 From: Tom Clegg Date: Mon, 30 Aug 2021 14:02:03 -0400 Subject: [PATCH] 17995: Rephrase filter expression docs. Arvados-DCO-1.1-Signed-off-by: Tom Clegg --- doc/api/methods.html.textile.liquid | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/doc/api/methods.html.textile.liquid b/doc/api/methods.html.textile.liquid index 09918830ed..914e9779fc 100644 --- a/doc/api/methods.html.textile.liquid +++ b/doc/api/methods.html.textile.liquid @@ -107,16 +107,20 @@ table(table table-bordered table-condensed). |@is_a@|string|Arvados object type|@["head_uuid","is_a","arvados#collection"]@| |@exists@|string|Test if a subproperty is present.|@["properties","exists","my_subproperty"]@| -h4(#filterexpression). Filtering by comparing two attributes +h4(#filterexpression). Filtering using boolean expressions -If @a@ and @b@ are attributes that have numeric values, they can be compared in a filter condition using the form @["(a < b)", "=", true]@. Supported operators are @=@, @<@, @<=@, @>@, and @>=@. Examples: +In place of an attribute, the first element of the three-element filter array can be a boolean expression. The following restrictions apply: +* The expression must contain exactly one operator. +* The operator must be @=@, @<@, @<=@, @>@, or @>=@. +* There must be exactly one pair of parentheses, surrounding the entire expression. +* Each operand must be the name of a numeric attribute like @replication_desired@ (literal values like @3@ and non-numeric attributes like @uuid@ are not accepted). +* The expression must not contain whitespace other than an ASCII space (newline and tab characters are not accepted). +* The second and third elements of the filter array must be @"="@ and @true@ respectively. + +Examples: * @["(replication_desired < replication_confirmed)", "=", true]@ * @["(replication_desired = replication_confirmed)", "=", true]@ -Note that only a very specific subset of boolean expressions is supported. For example: -* @["replication_desired < replication_confirmed", "=", true]@ is not accepted. Outer parentheses are mandatory. -* @["(replication_desired < 1)", "=", true]@ is not accepted. Operands must be attribute names. - h4(#substringsearchfilter). Filtering using substring search Resources can also be filtered by searching for a substring in attributes of type @string@, @array of strings@, @text@, and @hash@, which are indexed in the database specifically for search. To use substring search, the filter must: -- 2.30.2