Apache
/
lucene
mirror of https://github.com/apache/lucene.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

LUCENE-7076: Improve MIGRATE.txt/Point javadocs

This commit is contained in:
Robert Muir 2016-03-08 06:20:25 -05:00
parent 406a1635c1
commit 5bb072d4b9
13 changed files with 79 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
lucene/MIGRATE.txt
View File

@ -74,10 +74,12 @@ would be equivalent to the following code with the old setBoost API:
float boost = ...;
q.setBoost(q.getBoost() * boost);
## DimensionalValues replaces NumericField (LUCENE-6917)
# PointValues replaces NumericField (LUCENE-6917)
DimensionalValues provides faster indexing and searching, a smaller
index size, and less heap used at search time. The numeric fields
(IntField, FloatField, LongField, DoubleField) and NumericRangeQuery
have been moved to the backward-codecs module and prefixed with
Legacy.
PointValues provides faster indexing and searching, a smaller
index size, and less heap used at search time. See org.apache.lucene.index.PointValues
for an introduction.
Legacy numeric encodings from previous versions of Lucene are
deprecated as LegacyIntField, LegacyFloatField, LegacyLongField, and LegacyDoubleField,
and can be searched with LegacyNumericRangeQuery.

2
lucene/core/src/java/org/apache/lucene/document/BinaryPoint.java
View File

@ -19,6 +19,7 @@ package org.apache.lucene.document;
import java.util.Arrays;
import java.util.Comparator;
import org.apache.lucene.index.PointValues;
import org.apache.lucene.search.MatchNoDocsQuery;
import org.apache.lucene.search.PointInSetQuery;
import org.apache.lucene.search.PointRangeQuery;
@ -40,6 +41,7 @@ import org.apache.lucene.util.StringHelper;
* <li>{@link #newRangeQuery(String, byte[], byte[])} for matching a 1D range.
* <li>{@link #newRangeQuery(String, byte[][], byte[][])} for matching points/ranges in n-dimensional space.
* </ul>
* @see PointValues
*/
public final class BinaryPoint extends Field {

2
lucene/core/src/java/org/apache/lucene/document/DoublePoint.java
View File

@ -18,6 +18,7 @@ package org.apache.lucene.document;
import java.util.Arrays;
import org.apache.lucene.index.PointValues;
import org.apache.lucene.search.PointInSetQuery;
import org.apache.lucene.search.PointRangeQuery;
import org.apache.lucene.search.Query;
@ -38,6 +39,7 @@ import org.apache.lucene.util.NumericUtils;
* <li>{@link #newRangeQuery(String, double, double)} for matching a 1D range.
* <li>{@link #newRangeQuery(String, double[], double[])} for matching points/ranges in n-dimensional space.
* </ul>
* @see PointValues
*/
public final class DoublePoint extends Field {

2
lucene/core/src/java/org/apache/lucene/document/FloatPoint.java
View File

@ -18,6 +18,7 @@ package org.apache.lucene.document;
import java.util.Arrays;
import org.apache.lucene.index.PointValues;
import org.apache.lucene.search.PointInSetQuery;
import org.apache.lucene.search.PointRangeQuery;
import org.apache.lucene.search.Query;
@ -38,6 +39,7 @@ import org.apache.lucene.util.NumericUtils;
* <li>{@link #newRangeQuery(String, float, float)} for matching a 1D range.
* <li>{@link #newRangeQuery(String, float[], float[])} for matching points/ranges in n-dimensional space.
* </ul>
* @see PointValues
*/
public final class FloatPoint extends Field {

2
lucene/core/src/java/org/apache/lucene/document/IntPoint.java
View File

@ -18,6 +18,7 @@ package org.apache.lucene.document;
import java.util.Arrays;
import org.apache.lucene.index.PointValues;
import org.apache.lucene.search.PointInSetQuery;
import org.apache.lucene.search.PointRangeQuery;
import org.apache.lucene.search.Query;
@ -38,6 +39,7 @@ import org.apache.lucene.util.NumericUtils;
* <li>{@link #newRangeQuery(String, int, int)} for matching a 1D range.
* <li>{@link #newRangeQuery(String, int[], int[])} for matching points/ranges in n-dimensional space.
* </ul>
* @see PointValues
*/
public final class IntPoint extends Field {

2
lucene/core/src/java/org/apache/lucene/document/LongPoint.java
View File

@ -18,6 +18,7 @@ package org.apache.lucene.document;
import java.util.Arrays;
import org.apache.lucene.index.PointValues;
import org.apache.lucene.search.PointInSetQuery;
import org.apache.lucene.search.PointRangeQuery;
import org.apache.lucene.search.Query;
@ -38,6 +39,7 @@ import org.apache.lucene.util.NumericUtils;
* <li>{@link #newRangeQuery(String, long, long)} for matching a 1D range.
* <li>{@link #newRangeQuery(String, long[], long[])} for matching points/ranges in n-dimensional space.
* </ul>
* @see PointValues
*/
public final class LongPoint extends Field {

54
lucene/core/src/java/org/apache/lucene/index/PointValues.java
View File

@ -17,17 +17,65 @@
package org.apache.lucene.index;
import java.io.IOException;
import java.math.BigInteger;
import java.net.InetAddress;
import org.apache.lucene.document.BinaryPoint;
import org.apache.lucene.document.DoublePoint;
import org.apache.lucene.document.Field;
import org.apache.lucene.document.FieldType;
import org.apache.lucene.document.FloatPoint;
import org.apache.lucene.document.IntPoint;
import org.apache.lucene.document.LongPoint;
import org.apache.lucene.util.bkd.BKDWriter;
/** Allows recursively visiting point values indexed with {@link IntPoint},
* {@link FloatPoint}, {@link LongPoint}, {@link DoublePoint}
* or {@link BinaryPoint}.
/**
* Access to indexed numeric values.
* <p>
* Points represent numeric values and are indexed differently than ordinary text. Instead of an inverted index,
* points are indexed with datastructures such as <a href="https://en.wikipedia.org/wiki/K-d_tree">KD-trees</a>.
* These structures are optimized for operations such as <i>range</i>, <i>distance</i>, <i>nearest-neighbor</i>,
* and <i>point-in-polygon</i> queries.
* <h1>Basic Point Types</h1>
* <table summary="Basic point types in Java and Lucene">
* <tr><th>Java type</th><th>Lucene class</th></tr>
* <tr><td>{@code int}</td><td>{@link IntPoint}</td></tr>
* <tr><td>{@code long}</td><td>{@link LongPoint}</td></tr>
* <tr><td>{@code float}</td><td>{@link FloatPoint}</td></tr>
* <tr><td>{@code double}</td><td>{@link DoublePoint}</td></tr>
* <tr><td>{@code byte[]}</td><td>{@link BinaryPoint}</td></tr>
* <tr><td>{@link BigInteger}</td><td><a href="{@docRoot}/../sandbox/org/apache/lucene/document/BigIntegerPoint.html">BigIntegerPoint</a>*</td></tr>
* <tr><td>{@link InetAddress}</td><td><a href="{@docRoot}/../sandbox/org/apache/lucene/document/InetAddressPoint.html">InetAddressPoint</a>*</td></tr>
* </table>
* * in the <i>lucene-sandbox</i> jar<br>
* <p>
* Basic Lucene point types behave like their java peers: for example {@link IntPoint} represents a signed 32-bit
* {@link Integer}, supporting values ranging from {@link Integer#MIN_VALUE} to {@link Integer#MAX_VALUE}, ordered
* consistent with {@link Integer#compareTo(Integer)}. In addition to indexing support, point classes also contain
* static methods (such as {@link IntPoint#newRangeQuery(String, int, int)}) for creating common queries. For example:
* <pre class="prettyprint">
* // add year 1970 to document
* document.add(new IntPoint("year", 1970));
* // index document
* writer.addDocument(document);
* ...
* // issue range query of 1960-1980
* Query query = IntPoint.newRangeQuery("year", 1960, 1980);
* TopDocs docs = searcher.search(query, ...);
* </pre>
* <h1>Geospatial Point Types</h1>
* Although basic point types such as {@link DoublePoint} support points in multi-dimensional space too, Lucene has
* specialized classes for location data. These classes are optimized for location data: they are more space-efficient and
* support special operations such as <i>distance</i> and <i>polygon</i> queries. There are currently two implementations:
* <br>
* <ol>
* <li><a href="{@docRoot}/../sandbox/org/apache/lucene/document/LatLonPoint.html">LatLonPoint</a> in <i>lucene-sandbox</i>: indexes {@code (latitude,longitude)} as {@code (x,y)} in two-dimensional space.
* <li><a href="{@docRoot}/../spatial3d/org/apache/lucene/spatial3d/Geo3DPoint.html">Geo3DPoint</a>* in <i>lucene-spatial3d</i>: indexes {@code (latitude,longitude)} as {@code (x,y,z)} in three-dimensional space.
* </ol>
* * does <b>not</b> support altitude, 3D here means "uses three dimensions under-the-hood"<br>
* <h1>Advanced usage</h1>
* Custom structures can be created on top of single- or multi- dimensional basic types, on top of
* {@link BinaryPoint} for more flexibility, or via custom {@link Field} subclasses.
*
* @lucene.experimental */
public abstract class PointValues {

13
lucene/core/src/java/org/apache/lucene/search/PointInSetQuery.java
View File

@ -16,15 +16,10 @@
*/
package org.apache.lucene.search;
import java.io.IOException;
import java.util.Arrays;
import org.apache.lucene.document.BinaryPoint;
import org.apache.lucene.document.DoublePoint;
import org.apache.lucene.document.FloatPoint;
import org.apache.lucene.document.IntPoint;
import org.apache.lucene.document.LongPoint;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.LeafReader;
import org.apache.lucene.index.LeafReaderContext;
@ -48,13 +43,7 @@ import org.apache.lucene.util.StringHelper;
* create range queries for lucene's standard {@code Point} types, refer to factory
* methods on those classes, e.g. {@link IntPoint#newSetQuery IntPoint.newSetQuery()} for
* fields indexed with {@link IntPoint}.
* @see IntPoint
* @see LongPoint
* @see FloatPoint
* @see DoublePoint
* @see BinaryPoint
*
* @see PointValues
* @lucene.experimental */
public abstract class PointInSetQuery extends Query {

11
lucene/core/src/java/org/apache/lucene/search/PointRangeQuery.java
View File

@ -23,11 +23,7 @@ import java.util.Objects;
import org.apache.lucene.index.PointValues;
import org.apache.lucene.index.PointValues.IntersectVisitor;
import org.apache.lucene.index.PointValues.Relation;
import org.apache.lucene.document.BinaryPoint; // javadocs
import org.apache.lucene.document.DoublePoint; // javadocs
import org.apache.lucene.document.FloatPoint; // javadocs
import org.apache.lucene.document.IntPoint; // javadocs
import org.apache.lucene.document.LongPoint; // javadocs
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.LeafReader;
import org.apache.lucene.index.LeafReaderContext;
@ -44,12 +40,7 @@ import org.apache.lucene.util.StringHelper;
* fields indexed with {@link IntPoint}.
* <p>
* For a single-dimensional field this query is a simple range query; in a multi-dimensional field it's a box shape.
* @see IntPoint
* @see LongPoint
* @see FloatPoint
* @see DoublePoint
* @see BinaryPoint
*
* @see PointValues
* @lucene.experimental
*/
public abstract class PointRangeQuery extends Query {

2
lucene/sandbox/src/java/org/apache/lucene/document/BigIntegerPoint.java
View File

@ -19,6 +19,7 @@ package org.apache.lucene.document;
import java.math.BigInteger;
import java.util.Arrays;
import org.apache.lucene.index.PointValues;
import org.apache.lucene.search.PointInSetQuery;
import org.apache.lucene.search.PointRangeQuery;
import org.apache.lucene.search.Query;
@ -39,6 +40,7 @@ import org.apache.lucene.util.NumericUtils;
* <li>{@link #newRangeQuery(String, BigInteger, BigInteger)} for matching a 1D range.
* <li>{@link #newRangeQuery(String, BigInteger[], BigInteger[])} for matching points/ranges in n-dimensional space.
* </ul>
* @see PointValues
*/
public class BigIntegerPoint extends Field {

2
lucene/sandbox/src/java/org/apache/lucene/document/InetAddressPoint.java
View File

@ -20,6 +20,7 @@ import java.net.InetAddress;
import java.net.UnknownHostException;
import java.util.Arrays;
import org.apache.lucene.index.PointValues;
import org.apache.lucene.search.PointInSetQuery;
import org.apache.lucene.search.PointRangeQuery;
import org.apache.lucene.search.Query;
@ -43,6 +44,7 @@ import org.apache.lucene.util.BytesRef;
* This field supports both IPv4 and IPv6 addresses: IPv4 addresses are converted
* to <a href="https://tools.ietf.org/html/rfc4291#section-2.5.5">IPv4-Mapped IPv6 Addresses</a>:
* indexing {@code 1.2.3.4} is the same as indexing {@code ::FFFF:1.2.3.4}.
* @see PointValues
*/
public class InetAddressPoint extends Field {

2
lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java
View File

@ -20,6 +20,7 @@ import org.apache.lucene.util.BytesRef;
import org.apache.lucene.util.NumericUtils;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.PointValues;
import org.apache.lucene.search.BooleanClause;
import org.apache.lucene.search.BooleanQuery;
import org.apache.lucene.search.ConstantScoreQuery;
@ -43,6 +44,7 @@ import org.apache.lucene.spatial.util.GeoUtils;
* <p>
* <b>WARNING</b>: Values are indexed with some loss of precision, incurring up to 1E-7 error from the
* original {@code double} values.
* @see PointValues
*/
// TODO ^^^ that is very sandy and hurts the API, usage, and tests tremendously, because what the user passes
// to the field is not actually what gets indexed. Float would be 1E-5 error vs 1E-7, but it might be

3
lucene/spatial3d/src/java/org/apache/lucene/spatial3d/Geo3DPoint.java
View File

@ -18,6 +18,7 @@ package org.apache.lucene.spatial3d;
import org.apache.lucene.document.Field;
import org.apache.lucene.document.FieldType;
import org.apache.lucene.index.PointValues;
import org.apache.lucene.spatial3d.geom.GeoPoint;
import org.apache.lucene.spatial3d.geom.GeoShape;
import org.apache.lucene.spatial3d.geom.PlanetModel;
@ -34,7 +35,7 @@ import org.apache.lucene.util.NumericUtils;
* <ul>
* <li>{@link #newShapeQuery newShapeQuery()} for matching all points inside a specified shape
* </ul>
*
* @see PointValues
* @lucene.experimental */
public final class Geo3DPoint extends Field {