Class DocValuesTermsQuery

  • All Implemented Interfaces:
    Accountable

    public class DocValuesTermsQuery
    extends Query
    implements Accountable
    A Query that only accepts documents whose term value in the specified field is contained in the provided set of allowed terms.

    This is the same functionality as TermsQuery (from queries/), but because of drastically different implementations, they also have different performance characteristics, as described below.

    NOTE: be very careful using this query: it is typically much slower than using TermsQuery, but in certain specialized cases may be faster.

    With each search, this query translates the specified set of Terms into a private LongBitSet keyed by term number per unique IndexReader (normally one reader per segment). Then, during matching, the term number for each docID is retrieved from the cache and then checked for inclusion using the LongBitSet. Since all testing is done using RAM resident data structures, performance should be very fast, most likely fast enough to not require further caching of the DocIdSet for each possible combination of terms. However, because docIDs are simply scanned linearly, an index with a great many small documents may find this linear scan too costly.

    In contrast, TermsQuery builds up an FixedBitSet, keyed by docID, every time it's created, by enumerating through all matching docs using PostingsEnum to seek and scan through each term's docID list. While there is no linear scan of all docIDs, besides the allocation of the underlying array in the FixedBitSet, this approach requires a number of "disk seeks" in proportion to the number of terms, which can be exceptionally costly when there are cache misses in the OS's IO cache.

    Generally, this filter will be slower on the first invocation for a given field, but subsequent invocations, even if you change the allowed set of Terms, should be faster than TermsQuery, especially as the number of Terms being matched increases. If you are matching only a very small number of terms, and those terms in turn match a very small number of documents, TermsQuery may perform faster.

    Which query is best is very application dependent.

    • Field Detail

      • BASE_RAM_BYTES

        private static final long BASE_RAM_BYTES
      • field

        private final java.lang.String field
      • termDataHashCode

        private final int termDataHashCode
    • Constructor Detail

      • DocValuesTermsQuery

        public DocValuesTermsQuery​(java.lang.String field,
                                   java.util.Collection<BytesRef> terms)
      • DocValuesTermsQuery

        public DocValuesTermsQuery​(java.lang.String field,
                                   BytesRef... terms)
      • DocValuesTermsQuery

        public DocValuesTermsQuery​(java.lang.String field,
                                   java.lang.String... terms)
    • Method Detail

      • equals

        public boolean equals​(java.lang.Object other)
        Description copied from class: Query
        Override and implement query instance equivalence properly in a subclass. This is required so that QueryCache works properly.

        Typically a query will be equal to another only if it's an instance of the same class and its document-filtering properties are identical that other instance. Utility methods are provided for certain repetitive code.

        Specified by:
        equals in class Query
        See Also:
        Query.sameClassAs(Object), Query.classHash()
      • hashCode

        public int hashCode()
        Description copied from class: Query
        Override and implement query hash code properly in a subclass. This is required so that QueryCache works properly.
        Specified by:
        hashCode in class Query
        See Also:
        Query.equals(Object)
      • toString

        public java.lang.String toString​(java.lang.String defaultField)
        Description copied from class: Query
        Prints a query to a string, with field assumed to be the default field and omitted.
        Specified by:
        toString in class Query
      • getField

        public java.lang.String getField()
        Returns:
        the name of the field searched by this query.
      • getTerms

        public PrefixCodedTerms getTerms()
        Returns:
        the terms looked up by this query, prefix-encoded.
      • ramBytesUsed

        public long ramBytesUsed()
        Description copied from interface: Accountable
        Return the memory usage of this object in bytes. Negative values are illegal.
        Specified by:
        ramBytesUsed in interface Accountable
      • visit

        public void visit​(QueryVisitor visitor)
        Description copied from class: Query
        Recurse through the query tree, visiting any child queries
        Specified by:
        visit in class Query
        Parameters:
        visitor - a QueryVisitor to be called by each query in the tree
      • createWeight

        public Weight createWeight​(IndexSearcher searcher,
                                   ScoreMode scoreMode,
                                   float boost)
                            throws java.io.IOException
        Description copied from class: Query
        Expert: Constructs an appropriate Weight implementation for this query.

        Only implemented by primitive queries, which re-write to themselves.

        Overrides:
        createWeight in class Query
        scoreMode - How the produced scorers will be consumed.
        boost - The boost that is propagated by the parent queries.
        Throws:
        java.io.IOException