This version of the OpenSearch documentation is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Significant text aggregations

The significant_text aggregation is similar to the significant_terms aggregation but it’s for raw text fields. Significant text measures the change in popularity measured between the foreground and background sets using statistical analysis. For example, it might suggest Tesla when you look for its stock acronym TSLA.

The significant_text aggregation re-analyzes the source text on the fly, filtering noisy data like duplicate paragraphs, boilerplate headers and footers, and so on, which might otherwise skew the results.

Re-analyzing high-cardinality datasets can be a very CPU-intensive operation. We recommend using the significant_text aggregation inside a sampler aggregation to limit the analysis to a small selection of top-matching documents, for example 200.

You can set the following parameters:

  • min_doc_count - Return results that match more than a configured number of top hits. We recommend not setting min_doc_count to 1 because it tends to return terms that are typos or misspellings. Finding more than one instance of a term helps reinforce that the significance is not the result of a one-off accident. The default value of 3 is used to provide a minimum weight-of-evidence.
  • shard_size - Setting a high value increases stability (and accuracy) at the expense of computational performance.
  • shard_min_doc_count - If your text contains many low frequency words and you’re not interested in these (for example typos), then you can set the shard_min_doc_count parameter to filter out candidate terms at a shard level with a reasonable certainty to not reach the required min_doc_count even after merging the local significant text frequencies. The default value is 1, which has no impact until you explicitly set it. We recommend setting this value much lower than the min_doc_count value.

Assume that you have the complete works of Shakespeare indexed in an OpenSearch cluster. You can find significant texts in relation to the word “breathe” in the text_entry field:

  1. GET shakespeare/_search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "text_entry": "breathe"
  6.     }
  7.   },
  8.   "aggregations": {
  9.     "my_sample": {
  10.       "sampler": {
  11.         "shard_size": 100
  12.       },
  13.       "aggregations": {
  14.         "keywords": {
  15.           "significant_text": {
  16.             "field": "text_entry",
  17.             "min_doc_count": 4
  18.           }
  19.         }
  20.       }
  21.     }
  22.   }
  23. }

copy

Example response

  1. "aggregations" : {
  2.   "my_sample" : {
  3.     "doc_count" : 59,
  4.     "keywords" : {
  5.       "doc_count" : 59,
  6.       "bg_count" : 111396,
  7.       "buckets" : [
  8.         {
  9.           "key" : "breathe",
  10.           "doc_count" : 59,
  11.           "score" : 1887.0677966101694,
  12.           "bg_count" : 59
  13.         },
  14.         {
  15.           "key" : "air",
  16.           "doc_count" : 4,
  17.           "score" : 2.641295376716233,
  18.           "bg_count" : 189
  19.         },
  20.         {
  21.           "key" : "dead",
  22.           "doc_count" : 4,
  23.           "score" : 0.9665839666414213,
  24.           "bg_count" : 495
  25.         },
  26.         {
  27.           "key" : "life",
  28.           "doc_count" : 5,
  29.           "score" : 0.9090787433467572,
  30.           "bg_count" : 805
  31.         }
  32.       ]
  33.     }
  34.   }
  35.  }
  36. }

The most significant texts in relation to breathe are air, dead, and life.

The significant_text aggregation has the following limitations:

  • Doesn’t support child aggregations because child aggregations come at a high memory cost. As a workaround, you can add a follow-up query using a terms aggregation with an include clause and a child aggregation.
  • Doesn’t support nested objects because it works with the document JSON source.
  • The counts of documents might have some (typically small) inaccuracies as it’s based on summing the samples returned from each shard. You can use the shard_size parameter to fine-tune the trade-off between accuracy and performance. By default, the shard_size is set to -1 to automatically estimate the number of shards and the size parameter.

The default source of statistical information for background term frequencies is the entire index. You can narrow this scope with a background filter for more focus:

  1. GET shakespeare/_search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "text_entry": "breathe"
  6.     }
  7.   },
  8.   "aggregations": {
  9.     "my_sample": {
  10.       "sampler": {
  11.         "shard_size": 100
  12.       },
  13.       "aggregations": {
  14.         "keywords": {
  15.           "significant_text": {
  16.             "field": "text_entry",
  17.             "background_filter": {
  18.               "term": {
  19.                 "speaker": "JOHN OF GAUNT"
  20.               }
  21.             }
  22.           }
  23.         }
  24.       }
  25.     }
  26.   }
  27. }