1 package org.apache.lucene.search.function;
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
21 * A query that scores each document as the value of the numeric input field.
23 * The query matches all documents, and scores each document according to the numeric
24 * value of that field.
26 * It is assumed, and expected, that:
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>
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.
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:
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>
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!
55 * @lucene.experimental
57 public class FieldScoreQuery extends ValueSourceQuery {
60 * Type of score field, indicating how field values are interpreted/parsed.
62 * The type selected at search search time should match the data stored in the field.
63 * Different types have different RAM requirements:
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>
71 public static class Type {
73 /** field values are interpreted as numeric byte values. */
74 public static final Type BYTE = new Type("byte");
76 /** field values are interpreted as numeric short values. */
77 public static final Type SHORT = new Type("short");
79 /** field values are interpreted as numeric int values. */
80 public static final Type INT = new Type("int");
82 /** field values are interpreted as numeric float values. */
83 public static final Type FLOAT = new Type("float");
85 private String typeName;
86 private Type (String name) {
89 /*(non-Javadoc) @see java.lang.Object#toString() */
91 public String toString() {
92 return getClass().getName()+"::"+typeName;
97 * Create a FieldScoreQuery - a query that scores each document as the value of the numeric input field.
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}.
104 public FieldScoreQuery(String field, Type type) {
105 super(getValueSource(field,type));
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);
113 if (type == Type.SHORT) {
114 return new ShortFieldSource(field);
116 if (type == Type.INT) {
117 return new IntFieldSource(field);
119 if (type == Type.FLOAT) {
120 return new FloatFieldSource(field);
122 throw new IllegalArgumentException(type+" is not a known Field Score Query Type!");