Community articleSearch constraints REST API specification
Added by IBM contributorIBM | Edited by IBM contributorStephan Laertz on May 6, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars3 comments

Parent topic: Search REST API specification

  • 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.
  • 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. 

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




Always equals "field" for this type of constraint


The identifier of the indexed field


An array of field values. Each search result must match at least one of the values




Category Constraint

A category constraint refers to a constraint on a specific category in a FacetsCreate New Article. 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"]}




Always equals "category" for this type of constraint


An array of category IDs. Each search result must match at least one of the categories.


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"}]}




Always equals "range" for this type of constraint


The identifier of the indexed field


"ge" for lower inclusive boundary.

"g" for lower exclusive boundary

"le" for upper inclusive boundary

"l" for upper exclusive boundary

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:


taco riet commented on Jun 20, 2014

Re: Search constraints REST API specification

Is the constraint supposed to work with "strange" characters?

It looks like a constraint sent like this:


is not working, while I am really expecting results (url encoding the ö does not make a difference).

For the query parameter I do not have issues.

Radim Venglor commented on Mar 25, 2014

Re: Search constraints REST API specification

Category constraint usage is not well described

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

RIGTH WAY HOW TO USE CATEGORY CONSTRAINT: constraint={"type":"category","id":"facet_id","values":["label"]} ,, for example constraint={"type":"category","id":"tags","values":["XXX","AAA"]}

Tom Shelley commented on Apr 19, 2013

Re: Search constraints REST API specification

I cannot get this to work. Could you please list some example URLs that show the constraint used in the URL context?

Here's what I'm trying; but failing with:{"type":"authoringtemplate","values":["AT_highlights"]}&query=careers&index=Remote+PSE+service+EJB%3A%3A%2Fusr%2FIBM%2Fcompany%2Fapplication%2Fsearch_collection%2FPublic_WCM

But this URL isn't giving me any results. If I remove the constraint, I'll get the appropriate results. With the constraint specified; I get this error:

PSS0004Internal error: {0}