Navigation

compound (Operator)

On this page

Definition

compound

The compound operator combines two or more operators into a single query. Each element of a compound query is called a clause, and each clause consists of one or more sub-queries.

Documents in the result set are returned with a match score, which is calculated by summing the score that each document received for each individual clause which generated a match. The result set is ordered by score, highest to lowest.

compound has the following syntax:

{
  $searchBeta: {
    "index": <index name>, // optional, defaults to "default"
    "compound": {
      <must | mustNot | should | filter>: { <clauses> }
    }
  }
}

compound uses the following terms to construct a query:

must
Clauses which must match to produce results.
mustNot
Clauses which must not match for a document to be included in the results.
should

Clauses which cause documents in the result set to be scored higher if they match.

minimumShouldMatch is an option of should. If you use more than one should clause, you can use the minimumShouldMatch option to specify a minimum number of should clauses which must be satisfied for a document to be included in the result set. See an example.

filter
Clauses which must all match all for a document to be included in the results. filter clauses do not contribute to a returned document’s score. See an example.

Any of the above clauses may contain query criteria using any top-level operator, such as term, search, or span.

Examples

The following examples use a collection called fruit which contains the following documents:

{
  "_id" : 1,
  "type" : "apple",
  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp."
},
{
  "_id" : 2,
  "type" : "banana",
  "description" : "Bananas are usually sold in bunches of five or six."
},
{
  "_id" : 3,
  "type" : "pear",
  "description" : "Bosc and Bartlett are the most common varieties of pears."
}

The fruit collection has a Full Text Search index on the description field which uses the standard analyzer. The standard analyzer lower-cases all words and disregards common stop words ("the", "a", "and", etc).

must and mustNot Example

The following example uses a combination of must and mustNot clauses to contruct a query. The must clause performs a search operation for the term varieties in the description field. For a document to match, it must fulfill the must clause. The mustNot clause performs a search operation for the term apples in the description field. For a document to match, it must not fulfill the mustNot clause.

db.fruit.aggregate([
  {
    $searchBeta: {
      "compound": {
        "must": {
          "search": {
            "query": "varieties",
            "path": "description"
          }
        },
        "mustNot": {
          "search": {
            "query": "apples",
            "path": "description"
          }
        }
      }
    }
  }
])

The above query returns the document with _id: 3 because its description field contains the word varities and does not contain apples.

must and should Example

The following query uses must to specify search conditions which must be met and should to specify preference for documents containing the word Fuji. The $project pipeline stage excludes all document fields except _id and adds a score field, which displays the document’s relevance score.

db.fruit.aggregate([
  {
    $searchBeta: {
      "compound": {
        "must": {
          "search": {
            "query": "varieties",
            "path": "description"
          }
        },
        "should": {
          "search": {
            "query": "Fuji",
            "path": "description"
          }
        }
      }
    }
  },
  {
    $project: {
      "score": { "$meta": "searchScore" }
    }
  }
])

The above query returns the following results:

{ "_id" : 1, "score" : 0.9701932668685913 }
{ "_id" : 3, "score" : 0.3912709355354309 }

The document with _id: 1 has a higher score because its description field contains the word Fuji, satisfying the should clause.

minimumShouldMatch Example

In a query with multiple should clauses, you can use the miniumumShouldMatch option to specify a minimum number of clauses which must match to return a result.

The following query has one must clause and two should clauses, with a minimumShouldMatch value of 1. A document must include the term varieties in the description field and must include either Fuji or Golden Delicious in the description field to be included in the result set.

db.fruit.aggregate([
  {
    $searchBeta: {
      "compound": {
        "must": {
          "search": {
             "query": "varieties",
             "path": "description"
          }
        },
        "should": [
          {
            "search": {
              "query": "Fuji",
              "path": "description"
            }
          },
          {
            "search": {
              "query": "Golden Delicious",
              "path": "description"
            }
          }],
          "minimumShouldMatch": 1
        }
      }
    }
])

The above query returns the following result:

{
  "_id" : 1,
  "type" : "apple",
  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp."
}

The document with _id: 1 matches the must clause and the first of the two should clauses.

filter Example

filter behaves the same as must, except that the filter clause is not considered in a returned document’s score, and therefore does not affect the order of the returned documents.

db.fruit.aggregate([
  {
    $searchBeta: {
      "compound": {
        "must": {
          "search": {
            "query": "varieties",
            "path": "description"
          }
        },
        "should": {
          "search": {
            "query": "banana",
            "path": "description"
          }
        },
        "filter": {
          "term": {
            "query": "granny",
            "path": "description"
          }
        }
      }
    }
  }
])

The above query returns the following result:

{
  "_id" : 1,
  "type" : "apple",
  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp."
}

The above document fulfills all the requirements for inclusion:

  • Both the must clause and the filter clause match.
  • The minimumShouldMatch value is not specified, so it defaults to 0, which allows the should clause to fail and still return a document.