docs/attachments/LUCENE-6415/LUCENE-6415.patch

Index: lucene/queries/src/java/org/apache/lucene/queries/TermsQuery.java
===================================================================
--- lucene/queries/src/java/org/apache/lucene/queries/TermsQuery.java	(revision 1672669)
+++ lucene/queries/src/java/org/apache/lucene/queries/TermsQuery.java	(working copy)
@@ -24,6 +24,7 @@
 import java.util.Collections;
 import java.util.Iterator;
 import java.util.List;
+import java.util.Set;
 
 import org.apache.lucene.index.Fields;
 import org.apache.lucene.index.LeafReader;
@@ -53,9 +54,21 @@
  * Specialization for a disjunction over many terms that behaves like a
  * {@link ConstantScoreQuery} over a {@link BooleanQuery} containing only
  * {@link org.apache.lucene.search.BooleanClause.Occur#SHOULD} clauses.
- * This query creates a bit set and sets bits that matches any of the wrapped
- * terms. While this might help performance when there are many terms, it would
- * be slower than a {@link BooleanQuery} when there are few terms to match.
+ * <p>For instance in the following example, both @{code q1} and {@code q2}
+ * would yield the same scores:
+ * <pre class="prettyprint">
+ * Query q1 = new TermsQuery(new Term("field", "foo"), new Term("field", "bar"));
+ * 
+ * BooleanQuery bq = new BooleanQuery();
+ * bq.add(new TermQuery(new Term("field", "foo")), Occur.SHOULD);
+ * bq.add(new TermQuery(new Term("field", "bar")), Occur.SHOULD);
+ * Query q2 = new ConstantScoreQuery(bq);
+ * </pre>
+ * <p>This query creates a bit set and sets bits that match any of the
+ * wrapped terms. While this might help performance when there are many terms,
+ * it would be slower than a {@link BooleanQuery} when there are few terms to
+ * match.
+ * <p>NOTE: This query produces scores that are equal to its boost
  */
 public class TermsQuery extends Query implements Accountable {
 
@@ -249,6 +262,14 @@
     return Collections.emptyList();
   }
 
+  @Override
+  public void extractTerms(Set<Term> terms) {
+    // no-op
+    // This query is for abuse cases when the number of terms is too high to
+    // run efficiently as a BooleanQuery. So likewise we hide its terms in
+    // order to protect highlighters
+  }
+
   private static final class TermsAndField implements Accountable {
 
     private static final long BASE_RAM_BYTES_USED =