lucene-java-3.4.0/lucene/src/java/org/apache/lucene/search/function/FieldScoreQuery.java

   1 package org.apache.lucene.search.function;
   2
   3 /**
   4  * Licensed to the Apache Software Foundation (ASF) under one or more
   5  * contributor license agreements.  See the NOTICE file distributed with
   6  * this work for additional information regarding copyright ownership.
   7  * The ASF licenses this file to You under the Apache License, Version 2.0
   8  * (the "License"); you may not use this file except in compliance with
   9  * the License.  You may obtain a copy of the License at
  10  *
  11  *     http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 /**
  21  * A query that scores each document as the value of the numeric input field.
  22  * <p>
  23  * The query matches all documents, and scores each document according to the numeric
  24  * value of that field.
  25  * <p>
  26  * It is assumed, and expected, that:
  27  * <ul>
  28  *  <li>The field used here is indexed, and has exactly
  29  *      one token in every scored document.</li>
  30  *  <li>Best if this field is un_tokenized.</li>
  31  *  <li>That token is parseable to the selected type.</li>
  32  * </ul>
  33  * <p>
  34  * Combining this query in a FunctionQuery allows much freedom in affecting document scores.
  35  * Note, that with this freedom comes responsibility: it is more than likely that the
  36  * default Lucene scoring is superior in quality to scoring modified as explained here.
  37  * However, in some cases, and certainly for research experiments, this capability may turn useful.
  38  * <p>
  39  * When constructing this query, select the appropriate type. That type should match the data stored in the
  40  * field. So in fact the "right" type should be selected before indexing. Type selection
  41  * has effect on the RAM usage:
  42  * <ul>
  43  *   <li>{@link Type#BYTE} consumes 1 * maxDocs bytes.</li>
  44  *   <li>{@link Type#SHORT} consumes 2 * maxDocs bytes.</li>
  45  *   <li>{@link Type#INT} consumes 4 * maxDocs bytes.</li>
  46  *   <li>{@link Type#FLOAT} consumes 8 * maxDocs bytes.</li>
  47  * </ul>
  48  * <p>
  49  * <b>Caching:</b>
  50  * Values for the numeric field are loaded once and cached in memory for further use with the same IndexReader.
  51  * To take advantage of this, it is extremely important to reuse index-readers or index-searchers,
  52  * otherwise, for instance if for each query a new index reader is opened, large penalties would be
  53  * paid for loading the field values into memory over and over again!
  54  *
  55  * @lucene.experimental
  56  */
  57 public class FieldScoreQuery extends ValueSourceQuery {
  58
  59   /**
  60    * Type of score field, indicating how field values are interpreted/parsed.
  61    * <p>
  62    * The type selected at search search time should match the data stored in the field.
  63    * Different types have different RAM requirements:
  64    * <ul>
  65    *   <li>{@link #BYTE} consumes 1 * maxDocs bytes.</li>
  66    *   <li>{@link #SHORT} consumes 2 * maxDocs bytes.</li>
  67    *   <li>{@link #INT} consumes 4 * maxDocs bytes.</li>
  68    *   <li>{@link #FLOAT} consumes 8 * maxDocs bytes.</li>
  69    * </ul>
  70    */
  71   public static class Type {
  72
  73     /** field values are interpreted as numeric byte values. */
  74     public static final Type BYTE = new Type("byte");
  75
  76     /** field values are interpreted as numeric short values. */
  77     public static final Type SHORT = new Type("short");
  78
  79     /** field values are interpreted as numeric int values. */
  80     public static final Type INT = new Type("int");
  81
  82     /** field values are interpreted as numeric float values. */
  83     public static final Type FLOAT = new Type("float");
  84
  85     private String typeName;
  86     private Type (String name) {
  87       this.typeName = name;
  88     }
  89     /*(non-Javadoc) @see java.lang.Object#toString() */
  90     @Override
  91     public String toString() {
  92       return getClass().getName()+"::"+typeName;
  93     }
  94   }
  95
  96   /**
  97    * Create a FieldScoreQuery - a query that scores each document as the value of the numeric input field.
  98    * <p>
  99    * The <code>type</code> param tells how to parse the field string values into a numeric score value.
 100    * @param field the numeric field to be used.
 101    * @param type the type of the field: either
 102    * {@link Type#BYTE}, {@link Type#SHORT}, {@link Type#INT}, or {@link Type#FLOAT}.
 103    */
 104   public FieldScoreQuery(String field, Type type) {
 105     super(getValueSource(field,type));
 106   }
 107
 108   // create the appropriate (cached) field value source.
 109   private static ValueSource getValueSource(String field, Type type) {
 110     if (type == Type.BYTE) {
 111       return new ByteFieldSource(field);
 112     }
 113     if (type == Type.SHORT) {
 114       return new ShortFieldSource(field);
 115     }
 116     if (type == Type.INT) {
 117       return new IntFieldSource(field);
 118     }
 119     if (type == Type.FLOAT) {
 120       return new FloatFieldSource(field);
 121     }
 122     throw new IllegalArgumentException(type+" is not a known Field Score Query Type!");
 123   }
 124
 125 }