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) 
)