Community articleConstraints
Added by IBM contributorIBM | Edited by IBM contributordeveloperWorks Lotus Team on July 1, 2014
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

No abstract provided.
  • Constraints are part of the Search API. They provide a structured method for performing advanced search over document metadata. They limit search results to ones matching specific metadata values.
  • It is an alternative for client-side applications which include filters/advanced search options. Instead of concatenating values into the query parameter using specific query syntax, an application can pass these as separate parameters, regardless of query syntax.
  • The constraint parameter can be passed multiple times in a Search API request to indicate multiple constraints.
  • The constraint parameter is optional in the Search API.
  • Constraints are mandatory: each search results must match all the constraints provided on the request. If a query parameter is provided, all search results must match the query as well as the constraints.
  • We differentiate between 3 basic types of constraints: field, category, and range constraints. Each constraint can apply to single or multiple values.
  • As well as the constraint parameter, the Search API supports a notconstraint parameter. A field, category or range constraint passed in a notconstraint parameter will ensure that each search result does not match that constraint.
  • The value of the constraint parameter is a JSON string. The details of the syntax for the various types of constraints is outlined below.


Field Constraint

A field constraint allows only results matching specific field values. Constraint values are assumed, unless otherwise specified through the exactMatch attribute, to be an exact match and are not analyzed.

Syntax: constraint={"type": "field", "id": "field_id", "values": ["fieldValue1", "fieldValue2"], "exactMatch":true}

Parameters:

type
Always equals "field" for this type of constraint
id
The identifier of the indexed field
values
An array of field values. Each search result must match at least one of the values
exactMatch
Default is true. If set to false, the values will be parsed and analyzed rather than being treated as an exact match and not analyzed as is otherwise the case.

Example:
constraint={"type":"field","id":"title","values":["test"],"exactMatch":false}

Category Constraint

A category constraint refers to a constraint on a specific category in a facet. A category constraint is similar to a field constraint in its syntax. However, since categories are indexed differently than regular fields, it is declared as a special type of constraint, to allow better handling of the request. Category constraints are always exact match.

Syntax: constraint={"type": "category", "values": ["root/a/x", "root/a/y"]}

Parameters:

type
Always equals "category" for this type of constraint
values
An array of category IDs. Each search result must match at least one of the categories.

Examples:
constraint={"type": "category", "values":["Tag/tag1"]}
constraint={"type": "category", "values":["Tag/tag1","Tag/tag2"]}
constraint={"type": "category", "values":["Source/forums","Source/profiles","Source/wikis","Source/status_updates"]}
constraint={"type": "category", "values":["Tag/tag1"]}&constraint={"type": "category", "values":["Tag/tag2"]}

Range Constraint

A range constraint allows only results in a specific range of field values. Values can be strings or numbers.

Numeric Syntax: constraint={"type": "range", "id": "field_id", "values": [{"ge": 0.1, "le": 0.5}, {"g": 3.6}, {"l": -5}]}

String Syntax: constraint={"type": "range", "id": "field_id", "values": [{"ge": "cat", "le": "dog"}, {"g": "horse" }, {"l": "animal"}]}

Parameters:

type
Always equals "range" for this type of constraint
id
The identifier of the indexed field
values
An array of range values. Each value is comprised of lower and upper boundaries. Each boundary can be inclusive or exclusive. One or more boundaries can be specified for each value. The allowed attributes are:

"ge" for lower inclusive boundary.

"g" for lower exclusive boundary

"le" for upper inclusive boundary

"l" for upper exclusive boundary

NOT Constraint

A NOT constraint allows only results not matching a constraint of the format given for the Field, Category or Range Constraints above.

Field Syntax: notconstraint={"type": "field", "id": "field_id", "values": ["fieldValue1", "fieldValue2"]}

Category Syntax: notconstraint={"type": "category", "id": "taxonomy_id", "values": ["root/a/x", "root/a/y"]}

Numeric Range Syntax: notconstraint={"type": "range", "id": "field_id", "values": [{"ge": 0.1, "le": 0.5}, {"g": 3.6}, {"l": -5}]}

String Range Syntax: notconstraint={"type": "range", "id": "field_id", "values": [{"ge": "cat", "le": "dog"}, {"g": "horse" }, {"l": "animal"}]}

Parameters:

type
Equals "field", "category" or "range".
id
The identifier of the indexed field or taxonomy
values
Refer to the documentation of the values parameter corresponding to the type of constraint in question.

Examples:
notconstraint={"type":"field","id":"title","values":["test"],"exactMatch":false}
notconstraint={"type": "category", "values":["Tag/tag1"]}
notconstraint={"type": "category", "values":["Tag/tag1","Tag/tag2"]}
notconstraint={"type": "category", "values":["Source/forums","Source/profiles","Source/wikis","Source/status_updates"]}
notconstraint={"type": "category", "values":["Tag/tag1"]}&constraint={"type": "category", "values":["Tag/tag2"]}