Advanced search#
Advanced search accepts all available search parameters as a JSON structure, on the form:
{
"singleParameter" : "value",
"booleanParameter" : true,
"singleNumericParameter" : 1,
"multiParameter" : ["value1","value2"],
"multiNumericParameter" : [1,2,3]
}
The general logic of such a search criteria object is that all search parameters are ANDed together. This means that resulting objects should comply with ALL these parameters.
Parameters which accept multiple values generally means that resulting objects must have any of these values.
The example above could be expressed in SQL as:
... WHERE singleParameter=value AND booleanParameter=true AND singleNumericParameter=1
AND multiParameter IN (value1, value2) AND multiNumericParameter IN (1,2,3)
Include/exclude flags#
A general concept in many entities are flags. Flags are a set of boolean markers on each entity, generally output on the form:
{
"flags" : [ "FIRST_FLAG" , "SECOND_FLAG" ],
...
}
meaning that these two flags are set on this entity.
Advanced search criteria for entities with flags allow two parameters:
{
"includeFlags" : [ "FIRST_FLAG" ],
"excludeFlags" : [ "SECOND_FLAG" ],
...
}
Meaning that this criteria should only match entities which have FIRST_FLAG
set, and
exclude all entities which have SECOND_FLAG
set.
This can be combined with multiple include- and exclude-flags in each criteria.
Deleted objects#
Deleted objects are filtered out by default, and are generally not accessible to users without special privileges.
To also search for deleted objects (provided the user has access to this), use the
includeDeleted
option (default false), if supported by the endpoint.
Keyword search#
Keyword search is a common concept for many endpoints.
A keyword is a substring present in one of the supported keyword fields in the entity. A keyword search lets the client provide a list of keywords to search for, along with search strategies to determine how to search.
An endpoint using keyword search will accept a keyword field strategy, indicating which fields to search for this keyword. The strategy may be a list of fields (to search multiple fields), or the value “all” to search all supported fields.
The endpoint also contains a keyword match strategy, which determines if multiple keywords should be handled as an anyor an all search, i.e. if results may have any of the given keywords, or if each result must have all of them.
If the match strategy is
any
, then eachof the keywords in the list must be present in any one of the fields specified in the field strategy.If the match strategy is
all
, then every of the keywords in the list must be present in any one of the fields specified in the field strategy.The different keywords may be in different (or multiple) fields, as long as the field is in the field strategy list.
This example will search for the words firstword
and secondword
, returning any
entity which contains either word in the fields name
or description
:
{
"keywords" : ["firstword","secondword"],
"keywordMatchStrategy" : "any",
"keywordFieldStrategy" : ["name","description"]
}
The example above could be expressed in SQL as:
... WHERE
(
( name MATCHES "firstword" OR description MATCHES "firstword")
OR
( name MATCHES "secondword" OR description MATCHES "secondword")
)
Changing keywordMatchStrategy to all
:
{
"keywords" : ["firstword","secondword"],
"keywordMatchStrategy" : "all",
"keywordFieldStrategy" : ["name","description"]
}
This would change the “SQL” to
... WHERE
(
( name MATCHES "firstword" OR description MATCHES "firstword")
AND
( name MATCHES "secondword" OR description MATCHES "secondword")
)
Time search#
See Using Argus Search APIs - Time fields for details on how to search based on time.
User search#
Most search endpoints for objects with user fields time will have a user
parameter,
along with a userFieldStrategy
parameter, allowing to specify which user fields to
search in.
This example will search for all objects where createdByUser
OR lastUpdatedByUser
contains one of the users “bob
, alice
”, eric
{
"user": ["bob","alice","eric"]
"userFieldStrategy" : ["createdByUser","lastUpdatedByUser"]
}
Subcriteria#
Many advanced search endpoints support subcriteria. This allows constructing advanced queries with inclusions and exclusions.
Subcriteria have the same structure as the main criteria, allowing a nested structure:
{
"customerID": [1],
"subCriteria": [
{"status" : ["closed"], "startTimestamp" : 1470000000000},
{"status" : ["pendingCustomer"]},
{"keyword" : ["interesting"], "endTimestamp" : 1490000000000}
]
}
The example above could be expressed in SQL as:
... WHERE customerID IN (1) AND
(
(status IN (closed) AND timestamp >= 1470000000000)
OR
(status IN (pendingCustomer)
OR
(keyword MATCHES (interesting) AND timestamp <= 1490000000000)
)
In this example, the three subcriteria are OR’ed together, while parameters inside the criteria are AND’ed together. The criterion set in the root criteria applies to both subcriteria.
To change the logic of the subcriteria, use exclude:true
or required:true
.
Excluding subcriteria#
In the example above, replacing the last subcriteria with:
{"keyword" : ["interesting"], "endTimestamp" : 1490000000000, "exclude" : true}
would change the search logic to:
... WHERE customerID IN (1) AND
(
(
(status IN (closed) AND timestamp >= 1470000000000)
OR
(status IN (pendingCustomer)
)
AND NOT
(keyword MATCHES (interesting) AND timestamp <= 1490000000000)
)
Required subcriteria#
In the example above, replacing the last subcriteria with:
{"keyword" : ["interesting"], "endTimestamp" : 1490000000000, "required" : true}
would change the search logic to:
... WHERE customerID IN (1) AND
(
(
(status IN (closed) AND timestamp >= 1470000000000)
OR
(status IN (pendingCustomer)
)
AND
(keyword MATCHES (interesting) AND timestamp <= 1490000000000)
)