+++ /dev/null
-<HTML>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-<HEAD>
- <TITLE>org.apache.lucene.search.function</TITLE>
-</HEAD>
-<BODY>
-<DIV>
- Programmatic control over documents scores.
-</DIV>
-<DIV>
- The <code>function</code> package provides tight control over documents scores.
-</DIV>
-<DIV>
-@lucene.experimental
-</DIV>
-<DIV>
- Two types of queries are available in this package:
-</DIV>
-<DIV>
- <ol>
- <li>
- <b>Custom Score queries</b> - allowing to set the score
- of a matching document as a mathematical expression over scores
- of that document by contained (sub) queries.
- </li>
- <li>
- <b>Field score queries</b> - allowing to base the score of a
- document on <b>numeric values</b> of <b>indexed fields</b>.
- </li>
- </ol>
-</DIV>
-<DIV> </DIV>
-<DIV>
- <b>Some possible uses of these queries:</b>
-</DIV>
-<DIV>
- <ol>
- <li>
- Normalizing the document scores by values indexed in a special field -
- for instance, experimenting with a different doc length normalization.
- </li>
- <li>
- Introducing some static scoring element, to the score of a document, -
- for instance using some topological attribute of the links to/from a document.
- </li>
- <li>
- Computing the score of a matching document as an arbitrary odd function of
- its score by a certain query.
- </li>
- </ol>
-</DIV>
-<DIV>
- <b>Performance and Quality Considerations:</b>
-</DIV>
-<DIV>
- <ol>
- <li>
- When scoring by values of indexed fields,
- these values are loaded into memory.
- Unlike the regular scoring, where the required information is read from
- disk as necessary, here field values are loaded once and cached by Lucene in memory
- for further use, anticipating reuse by further queries. While all this is carefully
- cached with performance in mind, it is recommended to
- use these features only when the default Lucene scoring does
- not match your "special" application needs.
- </li>
- <li>
- Use only with carefully selected fields, because in most cases,
- search quality with regular Lucene scoring
- would outperform that of scoring by field values.
- </li>
- <li>
- Values of fields used for scoring should match.
- Do not apply on a field containing arbitrary (long) text.
- Do not mix values in the same field if that field is used for scoring.
- </li>
- <li>
- Smaller (shorter) field tokens means less RAM (something always desired).
- When using <a href=FieldScoreQuery.html>FieldScoreQuery</a>,
- select the shortest <a href=FieldScoreQuery.html#Type>FieldScoreQuery.Type</a>
- that is sufficient for the used field values.
- </li>
- <li>
- Reusing IndexReaders/IndexSearchers is essential, because the caching of field tokens
- is based on an IndexReader. Whenever a new IndexReader is used, values currently in the cache
- cannot be used and new values must be loaded from disk. So replace/refresh readers/searchers in
- a controlled manner.
- </li>
- </ol>
-</DIV>
-<DIV>
- <b>History and Credits:</b>
- <ul>
- <li>
- A large part of the code of this package was originated from Yonik's FunctionQuery code that was
- imported from <a href="http://lucene.apache.org/solr">Solr</a>
- (see <a href="http://issues.apache.org/jira/browse/LUCENE-446">LUCENE-446</a>).
- </li>
- <li>
- The idea behind CustomScoreQurey is borrowed from
- the "Easily create queries that transform sub-query scores arbitrarily" contribution by Mike Klaas
- (see <a href="http://issues.apache.org/jira/browse/LUCENE-850">LUCENE-850</a>)
- though the implementation and API here are different.
- </li>
- </ul>
-</DIV>
-<DIV>
- <b>Code sample:</b>
- <P>
- Note: code snippets here should work, but they were never really compiled... so,
- tests sources under TestCustomScoreQuery, TestFieldScoreQuery and TestOrdValues
- may also be useful.
- <ol>
- <li>
- Using field (byte) values to as scores:
- <p>
- Indexing:
- <pre class="prettyprint">
- f = new Field("score", "7", Field.Store.NO, Field.Index.UN_TOKENIZED);
- f.setOmitNorms(true);
- d1.add(f);
- </pre>
- <p>
- Search:
- <pre class="prettyprint">
- Query q = new FieldScoreQuery("score", FieldScoreQuery.Type.BYTE);
- </pre>
- Document d1 above would get a score of 7.
- </li>
- <p>
- <li>
- Manipulating scores
- <p>
- Dividing the original score of each document by a square root of its docid
- (just to demonstrate what it takes to manipulate scores this way)
- <pre class="prettyprint">
- Query q = queryParser.parse("my query text");
- CustomScoreQuery customQ = new CustomScoreQuery(q) {
- public float customScore(int doc, float subQueryScore, float valSrcScore) {
- return subQueryScore / Math.sqrt(docid);
- }
- };
- </pre>
- <p>
- For more informative debug info on the custom query, also override the name() method:
- <pre class="prettyprint">
- CustomScoreQuery customQ = new CustomScoreQuery(q) {
- public float customScore(int doc, float subQueryScore, float valSrcScore) {
- return subQueryScore / Math.sqrt(docid);
- }
- public String name() {
- return "1/sqrt(docid)";
- }
- };
- </pre>
- <p>
- Taking the square root of the original score and multiplying it by a "short field driven score", ie, the
- short value that was indexed for the scored doc in a certain field:
- <pre class="prettyprint">
- Query q = queryParser.parse("my query text");
- FieldScoreQuery qf = new FieldScoreQuery("shortScore", FieldScoreQuery.Type.SHORT);
- CustomScoreQuery customQ = new CustomScoreQuery(q,qf) {
- public float customScore(int doc, float subQueryScore, float valSrcScore) {
- return Math.sqrt(subQueryScore) * valSrcScore;
- }
- public String name() {
- return "shortVal*sqrt(score)";
- }
- };
- </pre>
-
- </li>
- </ol>
-</DIV>
-</BODY>
-</HTML>
\ No newline at end of file
fnp / pylucene.git / blobdiff