Bool Query

The Hyperspace 'bool' query allows you to construct complex queries by combining multiple sub-queries and conditions. The bool query supports sub-clauses such as must, should, must_not, should_not and filter.

'must' Clause

In Hyperspace, the 'must' clause specifies conditions that must be satisfied for a document to be considered a match. In terms of logical operators, it corresponds to 'and' operator.

'must' Clause Score

Under the 'must' clause, each element is assigned a designated score, and the total score for the 'must' clause is calculated by aggregating these individual scores. Unless specified otherwise, the score is based on the TF-IDF scoring model. .The 'must' clause is used when you want all specified conditions to be satisfied for a document to be considered a match. Since each score represent a different probability, the combined score is a product of the individual scores

Score = score1 * score2 * score3...

Note: This scoring method assumes the 'must' clause are independent of one another

Example -

{
  "query": {
    "bool": {
      "must": [
        { "term": { "Bird": "Asian Koel" } },
        { "range": { "price": { "gte": 10} } },
        { "term": { "In Stock": "true" } }
      ]
    }
  }
}

In the above example, all candidates must satisfy all three conditions -

• exact match over the 'bird' field, with score equals TF-IDF score for { "Bird": "Asian Koel" }

• The 'price' field must be greater than or equal to 10

• match over "In Stock" field, with score equals TF-IDF score for { "In Stock": "true" }

The overall score will be a product of the individual scores.

'must_not' Clause

In Hyperspace, the 'must_not' clause specifies conditions that must not be satisfied for a document to be considered a match. In terms of logical operators, it corresponds to 'not' or 'and not' operators . The must_not clause is used when you want none of the specified conditions to be satisfied for a document to be considered a match.

Example -

{
  "query": {
    "bool": {
     "must": 
        { "term": { "Color": "Black" } },
      "must_not": [
        { "term": { "Bird": "Asian Koel" } },
        { "range": { "price": { "gte": 10} } },
        { "term": { "In Stock": "True" } }
      ]
    }
  }
}

In the above example, all candidates must satisfy the following condition:

• exact match over the 'Color' field

All candidates must also not satisfy any of the three conditions -

• exact match over the 'bird' field

• The 'price' field must be less than 10

• exact match over the "In Stock" field

'should' Clause

In Hyperspace, the should clause within a bool query is used to specify conditions that are optional for a document to be considered a match. Unlike the must clause, which imposes mandatory conditions, the should clause only modifies the document score, and allows for flexibility by indicating that any of the specified conditions can be satisfied for a document to contribute to the search results. The should clause is often used for expressing optional or desirable conditions.

'should' Clause Score

Within the 'should' clause, each condition is associated with a designated score, and the overall score for the 'should' clause is determined by combining these individual scores. If not explicitly specified otherwise, scoring follows the TF-IDF scoring model. The 'should' clause is employed when you desire flexibility, as it allows for documents to be considered a match if they satisfy any of the specified conditions.

The combined score is a sum of the individual scores

Score = score1 + score2 + score3...

Example -

{
  "query": {
    "bool": {
      "must": { "Bird": "Asian Koel" }
      "should": [
        { "term": { "Country": "India" } },
        { "term": { "Color": "Black" } }
      ]
    }
  }
}

In the above example, all candidates must satisfy the condition -

• exact match over the 'bird' field, with score equals TF-IDF score for { "Bird": "Asian Koel" }

In addition, any documents that satisfy the following conditions -

• exact match over the 'Country' field, with score equals TF-IDF score for { "Bird": "Asian Koel" }

• exact match over "Color" field, with score equals TF-IDF score for { "In Stock": "true" }

Will receive higher score. The overall score will be a sum of the individual scores.

'should_not' Clause

the should_not clause within a bool query specifies conditions that are optional for a document to be considered a match, in a similar manner to 'should' clause. The should_not clause decreases the document score. The should clause is often used for expressing optional or desirable conditions.

'should_not' Clause Score

In the 'should_not' clause, each condition is associated with a designated score, and the overall score for the clause is determined by substracting these individual scores. If not explicitly specified otherwise, scoring follows the TF-IDF scoring model. The 'should_not' clause enables documents to be a lesser match if they meet any of the specified conditions.

The combined score is a subtraction of the individual scores

Score = -score1 - score2 - score3...

Example -

{
  "query": {
    "bool": {
      "must": { "Bird": "Asian Koel" }
      "should_not": [
        { "term": { "Country": "India" } },
        { "term": { "Color": "Black" } }
      ]
    }
  }
}

In the above example, all candidates must satisfy the condition -

• exact match over the 'bird' field, with score equals TF-IDF score for { "Bird": "Asian Koel" }

In addition, any documents that satisfy the following conditions -

• exact match over the 'Country' field, with score equals TF-IDF score for { "Bird": "Asian Koel" }

• exact match over "Color" field, with score equals TF-IDF score for { "In Stock": "true" }

Will receive lower score. The overall score will be a sum of the individual scores.

'filter' Clause

the filterclause within a bool query specifies conditions that are mandatory for a document to be considered a match, in a similar manner to 'must' clause. Unlike the must clause, the filter clause does not affect the document score.

Example -

{
  "query": {
    "bool": {
      "must": 
        { "term": { "Bird": "Asian Koel" } }
      ,
      "filter": [
        { "term": { "Country": "India" } },
        { "term": { "Color": "Black" } }
      ]
    }
  }
}

In the above example, all candidates must satisfy the condition -

• exact match over the 'bird' field, with score equals TF-IDF score for { "Bird": "Asian Koel" }

In addition, any matched documents must satisfy the following conditions -

• exact match over the 'Country' field, with score equals TF-IDF score for { "Bird": "Asian Koel" }

• exact match over "Color" field, with score equals TF-IDF score for { "In Stock": "true" }

The overall score will be the rarity score, determined by the "must": { "term": { "Bird": "Asian Koel" } } clause.