mirror of https://github.com/apache/lucene.git
Remove deprecated float vector classes and methods (#12107)
Follow-up of #12105 to remove the deprecated classes for the next major version. Removes KnnVectorField, KnnVectorQuery, VectorValues and LeafReader#getVectorValues.
This commit is contained in:
Luca Cavanna
GitHub
parent
ce8eaf138c
commit
95e2cfcc1e
|
|
@ -44,6 +44,9 @@ API Changes
|
|||
|
||||
* GITHUB#11814: Support deletions in IndexRearranger. (Stefan Vodita)
|
||||
|
||||
* GITHUB#12107: Remove deprecated KnnVectorField, KnnVectorQuery, VectorValues and
|
||||
LeafReader#getVectorValues. (Luca Cavanna)
|
||||
|
||||
New Features
|
||||
---------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -60,7 +60,7 @@ public final class Lucene90HnswGraphBuilder {
|
|||
private final RandomAccessVectorValues<float[]> buildVectors;
|
||||
|
||||
/**
|
||||
* Reads all the vectors from a VectorValues, builds a graph connecting them by their dense
|
||||
* Reads all the vectors from vector values, builds a graph connecting them by their dense
|
||||
* ordinals, using the given hyperparameter settings, and returns the resulting graph.
|
||||
*
|
||||
* @param vectors the vectors whose relations are represented by the graph - must provide a
|
||||
|
|
@ -96,8 +96,8 @@ public final class Lucene90HnswGraphBuilder {
|
|||
}
|
||||
|
||||
/**
|
||||
* Reads all the vectors from two copies of a random access VectorValues. Providing two copies
|
||||
* enables efficient retrieval without extra data copying, while avoiding collision of the
|
||||
* Reads all the vectors from two copies of a {@link RandomAccessVectorValues}. Providing two
|
||||
* copies enables efficient retrieval without extra data copying, while avoiding collision of the
|
||||
* returned values.
|
||||
*
|
||||
* @param vectors the vectors for which to build a nearest neighbors graph. Must be an independet
|
||||
|
|
|
|||
|
|
@ -67,7 +67,7 @@ public final class Lucene91HnswGraphBuilder {
|
|||
private RandomAccessVectorValues<float[]> buildVectors;
|
||||
|
||||
/**
|
||||
* Reads all the vectors from a VectorValues, builds a graph connecting them by their dense
|
||||
* Reads all the vectors from vector values, builds a graph connecting them by their dense
|
||||
* ordinals, using the given hyperparameter settings, and returns the resulting graph.
|
||||
*
|
||||
* @param vectors the vectors whose relations are represented by the graph - must provide a
|
||||
|
|
@ -112,8 +112,8 @@ public final class Lucene91HnswGraphBuilder {
|
|||
}
|
||||
|
||||
/**
|
||||
* Reads all the vectors from two copies of a random access VectorValues. Providing two copies
|
||||
* enables efficient retrieval without extra data copying, while avoiding collision of the
|
||||
* Reads all the vectors from two copies of a {@link RandomAccessVectorValues}. Providing two
|
||||
* copies enables efficient retrieval without extra data copying, while avoiding collision of the
|
||||
* returned values.
|
||||
*
|
||||
* @param vectors the vectors for which to build a nearest neighbors graph. Must be an independet
|
||||
|
|
|
|||
|
|
@ -105,7 +105,7 @@ public abstract class BufferingKnnVectorsWriter extends KnnVectorsWriter {
|
|||
}
|
||||
}
|
||||
|
||||
/** Sorting VectorValues that iterate over documents in the order of the provided sortMap */
|
||||
/** Sorting FloatVectorValues that iterate over documents in the order of the provided sortMap */
|
||||
private static class SortingVectorValues extends FloatVectorValues {
|
||||
private final BufferedVectorValues randomAccess;
|
||||
private final int[] docIdOffsets;
|
||||
|
|
|
|||
|
|
@ -84,7 +84,7 @@ public abstract class KnnVectorsFormat implements NamedSPILoader.NamedSPI {
|
|||
new KnnVectorsFormat("EMPTY") {
|
||||
@Override
|
||||
public KnnVectorsWriter fieldsWriter(SegmentWriteState state) {
|
||||
throw new UnsupportedOperationException("Attempt to write EMPTY VectorValues");
|
||||
throw new UnsupportedOperationException("Attempt to write EMPTY vector values");
|
||||
}
|
||||
|
||||
@Override
|
||||
|
|
|
|||
|
|
@ -138,7 +138,7 @@ public abstract class KnnVectorsWriter implements Accountable, Closeable {
|
|||
}
|
||||
}
|
||||
|
||||
/** View over multiple VectorValues supporting iterator-style access via DocIdMerger. */
|
||||
/** View over multiple vector values supporting iterator-style access via DocIdMerger. */
|
||||
protected static final class MergedVectorValues {
|
||||
private MergedVectorValues() {}
|
||||
|
||||
|
|
|
|||
|
|
@ -380,7 +380,7 @@ public class FieldType implements IndexableFieldType {
|
|||
}
|
||||
if (numDimensions > FloatVectorValues.MAX_DIMENSIONS) {
|
||||
throw new IllegalArgumentException(
|
||||
"vector numDimensions must be <= VectorValues.MAX_DIMENSIONS (="
|
||||
"vector numDimensions must be <= FloatVectorValues.MAX_DIMENSIONS (="
|
||||
+ FloatVectorValues.MAX_DIMENSIONS
|
||||
+ "); got "
|
||||
+ numDimensions);
|
||||
|
|
|
|||
|
|
@ -30,9 +30,9 @@ import org.apache.lucene.util.VectorUtil;
|
|||
* an array (of type float[]) whose length is the vector dimension. Values can be retrieved using
|
||||
* {@link FloatVectorValues}, which is a forward-only docID-based iterator and also offers
|
||||
* random-access by dense ordinal (not docId). {@link VectorSimilarityFunction} may be used to
|
||||
* compare vectors at query time (for example as part of result ranking). A KnnVectorField may be
|
||||
* associated with a search similarity function defining the metric used for nearest-neighbor search
|
||||
* among vectors of that field.
|
||||
* compare vectors at query time (for example as part of result ranking). A {@link
|
||||
* KnnFloatVectorField} may be associated with a search similarity function defining the metric used
|
||||
* for nearest-neighbor search among vectors of that field.
|
||||
*
|
||||
* @lucene.experimental
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,81 +0,0 @@
|
|||
/*
|
||||
* 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.
|
||||
*/
|
||||
package org.apache.lucene.document;
|
||||
|
||||
import org.apache.lucene.index.FloatVectorValues;
|
||||
import org.apache.lucene.index.VectorSimilarityFunction;
|
||||
import org.apache.lucene.util.VectorUtil;
|
||||
|
||||
/**
|
||||
* A field that contains a single floating-point numeric vector (or none) for each document. Vectors
|
||||
* are dense - that is, every dimension of a vector contains an explicit value, stored packed into
|
||||
* an array (of type float[]) whose length is the vector dimension. Values can be retrieved using
|
||||
* {@link FloatVectorValues}, which is a forward-only docID-based iterator and also offers
|
||||
* random-access by dense ordinal (not docId). {@link VectorSimilarityFunction} may be used to
|
||||
* compare vectors at query time (for example as part of result ranking). A KnnVectorField may be
|
||||
* associated with a search similarity function defining the metric used for nearest-neighbor search
|
||||
* among vectors of that field.
|
||||
*
|
||||
* @deprecated use {@link KnnFloatVectorField} instead
|
||||
*/
|
||||
@Deprecated
|
||||
public class KnnVectorField extends KnnFloatVectorField {
|
||||
|
||||
/**
|
||||
* Creates a numeric vector field. Fields are single-valued: each document has either one value or
|
||||
* no value. Vectors of a single field share the same dimension and similarity function. Note that
|
||||
* some vector similarities (like {@link VectorSimilarityFunction#DOT_PRODUCT}) require values to
|
||||
* be unit-length, which can be enforced using {@link VectorUtil#l2normalize(float[])}.
|
||||
*
|
||||
* @param name field name
|
||||
* @param vector value
|
||||
* @param similarityFunction a function defining vector proximity.
|
||||
* @throws IllegalArgumentException if any parameter is null, or the vector is empty or has
|
||||
* dimension > 1024.
|
||||
*/
|
||||
public KnnVectorField(String name, float[] vector, VectorSimilarityFunction similarityFunction) {
|
||||
super(name, vector, similarityFunction);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a numeric vector field with the default EUCLIDEAN_HNSW (L2) similarity. Fields are
|
||||
* single-valued: each document has either one value or no value. Vectors of a single field share
|
||||
* the same dimension and similarity function.
|
||||
*
|
||||
* @param name field name
|
||||
* @param vector value
|
||||
* @throws IllegalArgumentException if any parameter is null, or the vector is empty or has
|
||||
* dimension > 1024.
|
||||
*/
|
||||
public KnnVectorField(String name, float[] vector) {
|
||||
super(name, vector);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a numeric vector field. Fields are single-valued: each document has either one value or
|
||||
* no value. Vectors of a single field share the same dimension and similarity function.
|
||||
*
|
||||
* @param name field name
|
||||
* @param vector value
|
||||
* @param fieldType field type
|
||||
* @throws IllegalArgumentException if any parameter is null, or the vector is empty or has
|
||||
* dimension > 1024.
|
||||
*/
|
||||
public KnnVectorField(String name, float[] vector, FieldType fieldType) {
|
||||
super(name, vector, fieldType);
|
||||
}
|
||||
}
|
||||
|
|
@ -377,7 +377,7 @@ public final class CheckIndex implements Closeable {
|
|||
public Throwable error;
|
||||
}
|
||||
|
||||
/** Status from testing VectorValues */
|
||||
/** Status from testing vector values */
|
||||
public static final class VectorValuesStatus {
|
||||
|
||||
VectorValuesStatus() {}
|
||||
|
|
@ -1015,7 +1015,7 @@ public final class CheckIndex implements Closeable {
|
|||
// Test PointValues
|
||||
segInfoStat.pointsStatus = testPoints(reader, infoStream, failFast);
|
||||
|
||||
// Test VectorValues
|
||||
// Test FloatVectorValues and ByteVectorValues
|
||||
segInfoStat.vectorValuesStatus = testVectors(reader, infoStream, failFast);
|
||||
|
||||
// Test Index Sort
|
||||
|
|
|
|||
|
|
@ -454,11 +454,11 @@ public class ExitableDirectoryReader extends FilterDirectoryReader {
|
|||
throw new ExitingReaderException(
|
||||
"The request took too long to iterate over vector values. Timeout: "
|
||||
+ queryTimeout.toString()
|
||||
+ ", VectorValues="
|
||||
+ ", FloatVectorValues="
|
||||
+ in);
|
||||
} else if (Thread.interrupted()) {
|
||||
throw new ExitingReaderException(
|
||||
"Interrupted while iterating over vector values. VectorValues=" + in);
|
||||
"Interrupted while iterating over vector values. FloatVectorValues=" + in);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -521,11 +521,11 @@ public class ExitableDirectoryReader extends FilterDirectoryReader {
|
|||
throw new ExitingReaderException(
|
||||
"The request took too long to iterate over vector values. Timeout: "
|
||||
+ queryTimeout.toString()
|
||||
+ ", VectorValues="
|
||||
+ ", ByteVectorValues="
|
||||
+ in);
|
||||
} else if (Thread.interrupted()) {
|
||||
throw new ExitingReaderException(
|
||||
"Interrupted while iterating over vector values. VectorValues=" + in);
|
||||
"Interrupted while iterating over vector values. ByteVectorValues=" + in);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -244,7 +244,7 @@ public class FieldInfos implements Iterable<FieldInfo> {
|
|||
return hasPointValues;
|
||||
}
|
||||
|
||||
/** Returns true if any fields have VectorValues */
|
||||
/** Returns true if any fields have vector values */
|
||||
public boolean hasVectorValues() {
|
||||
return hasVectorValues;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,64 +0,0 @@
|
|||
/*
|
||||
* 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.
|
||||
*/
|
||||
|
||||
package org.apache.lucene.index;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.util.Objects;
|
||||
|
||||
/** Delegates all methods to a wrapped {@link FloatVectorValues}. */
|
||||
public abstract class FilterVectorValues extends VectorValues {
|
||||
|
||||
/** Wrapped values */
|
||||
protected final FloatVectorValues in;
|
||||
|
||||
/** Sole constructor */
|
||||
protected FilterVectorValues(FloatVectorValues in) {
|
||||
Objects.requireNonNull(in);
|
||||
this.in = in;
|
||||
}
|
||||
|
||||
@Override
|
||||
public int docID() {
|
||||
return in.docID();
|
||||
}
|
||||
|
||||
@Override
|
||||
public int nextDoc() throws IOException {
|
||||
return in.nextDoc();
|
||||
}
|
||||
|
||||
@Override
|
||||
public int advance(int target) throws IOException {
|
||||
return in.advance(target);
|
||||
}
|
||||
|
||||
@Override
|
||||
public int dimension() {
|
||||
return in.dimension();
|
||||
}
|
||||
|
||||
@Override
|
||||
public int size() {
|
||||
return in.size();
|
||||
}
|
||||
|
||||
@Override
|
||||
public float[] vectorValue() throws IOException {
|
||||
return in.vectorValue();
|
||||
}
|
||||
}
|
||||
|
|
@ -199,17 +199,6 @@ public abstract class LeafReader extends IndexReader {
|
|||
*/
|
||||
public abstract NumericDocValues getNormValues(String field) throws IOException;
|
||||
|
||||
/**
|
||||
* Returns {@link VectorValues} for this field, or null if no {@link VectorValues} were indexed.
|
||||
* The returned instance should only be used by a single thread.
|
||||
*
|
||||
* @deprecated use {@link #getFloatVectorValues(String)} instead
|
||||
*/
|
||||
@Deprecated
|
||||
public VectorValues getVectorValues(String field) throws IOException {
|
||||
return new FilterVectorValues(getFloatVectorValues(field)) {};
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns {@link FloatVectorValues} for this field, or null if no {@link FloatVectorValues} were
|
||||
* indexed. The returned instance should only be used by a single thread.
|
||||
|
|
|
|||
|
|
@ -212,7 +212,7 @@ public final class SortingCodecReader extends FilterCodecReader {
|
|||
}
|
||||
}
|
||||
|
||||
/** Sorting VectorValues that iterate over documents in the order of the provided sortMap */
|
||||
/** Sorting FloatVectorValues that iterate over documents in the order of the provided sortMap */
|
||||
private static class SortingFloatVectorValues extends FloatVectorValues {
|
||||
final int size;
|
||||
final int dimension;
|
||||
|
|
|
|||
|
|
@ -1,32 +0,0 @@
|
|||
/*
|
||||
* 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.
|
||||
*/
|
||||
package org.apache.lucene.index;
|
||||
|
||||
import org.apache.lucene.document.KnnFloatVectorField;
|
||||
|
||||
/**
|
||||
* This class provides access to per-document floating point vector values indexed as {@link
|
||||
* KnnFloatVectorField}.
|
||||
*
|
||||
* @deprecated use {@link FloatVectorValues} instead
|
||||
*/
|
||||
@Deprecated
|
||||
public abstract class VectorValues extends FloatVectorValues {
|
||||
|
||||
/** Creates an instance to hold floating point vector values for a single document */
|
||||
VectorValues() {}
|
||||
}
|
||||
|
|
@ -239,7 +239,7 @@ abstract class AbstractKnnVectorQuery extends Query {
|
|||
}
|
||||
|
||||
/**
|
||||
* @return the KnnVectorField where the KnnVector search happens.
|
||||
* @return the knn vector field where the knn vector search happens.
|
||||
*/
|
||||
public String getField() {
|
||||
return field;
|
||||
|
|
|
|||
|
|
@ -1,47 +0,0 @@
|
|||
/*
|
||||
* 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.
|
||||
*/
|
||||
package org.apache.lucene.search;
|
||||
|
||||
import org.apache.lucene.codecs.KnnVectorsReader;
|
||||
import org.apache.lucene.util.Bits;
|
||||
|
||||
/**
|
||||
* Uses {@link KnnVectorsReader#search(String, float[], int, Bits, int)} to perform nearest
|
||||
* neighbour search.
|
||||
*
|
||||
* <p>This query also allows for performing a kNN search subject to a filter. In this case, it first
|
||||
* executes the filter for each leaf, then chooses a strategy dynamically:
|
||||
*
|
||||
* <ul>
|
||||
* <li>If the filter cost is less than k, just execute an exact search
|
||||
* <li>Otherwise run a kNN search subject to the filter
|
||||
* <li>If the kNN search visits too many vectors without completing, stop and run an exact search
|
||||
* </ul>
|
||||
*
|
||||
* @deprecated use {@link KnnFloatVectorQuery} instead
|
||||
*/
|
||||
@Deprecated
|
||||
public class KnnVectorQuery extends KnnFloatVectorQuery {
|
||||
|
||||
public KnnVectorQuery(String field, float[] target, int k) {
|
||||
super(field, target, k);
|
||||
}
|
||||
|
||||
public KnnVectorQuery(String field, float[] target, int k, Query filter) {
|
||||
super(field, target, k, filter);
|
||||
}
|
||||
}
|
||||
|
|
@ -76,7 +76,7 @@ public final class HnswGraphBuilder<T> {
|
|||
}
|
||||
|
||||
/**
|
||||
* Reads all the vectors from a VectorValues, builds a graph connecting them by their dense
|
||||
* Reads all the vectors from vector values, builds a graph connecting them by their dense
|
||||
* ordinals, using the given hyperparameter settings, and returns the resulting graph.
|
||||
*
|
||||
* @param vectors the vectors whose relations are represented by the graph - must provide a
|
||||
|
|
@ -123,8 +123,8 @@ public final class HnswGraphBuilder<T> {
|
|||
}
|
||||
|
||||
/**
|
||||
* Reads all the vectors from two copies of a random access VectorValues. Providing two copies
|
||||
* enables efficient retrieval without extra data copying, while avoiding collision of the
|
||||
* Reads all the vectors from two copies of a {@link RandomAccessVectorValues}. Providing two
|
||||
* copies enables efficient retrieval without extra data copying, while avoiding collision of the
|
||||
* returned values.
|
||||
*
|
||||
* @param vectorsToAdd the vectors for which to build a nearest neighbors graph. Must be an
|
||||
|
|
|
|||
|
|
@ -342,7 +342,7 @@ public class TestKnnGraph extends LuceneTestCase {
|
|||
* approximate KNN search algorithm
|
||||
*/
|
||||
assertGraphSearch(new int[] {0, 15, 3, 18, 5}, new float[] {0f, 0.1f}, dr);
|
||||
// Tiebreaking by docid must be done after VectorValues.search.
|
||||
// Tiebreaking by docid must be done after search.
|
||||
// assertGraphSearch(new int[]{11, 1, 8, 14, 21}, new float[]{2, 2}, dr);
|
||||
assertGraphSearch(new int[] {15, 18, 0, 3, 5}, new float[] {0.3f, 0.8f}, dr);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ import org.apache.lucene.util.BitSetIterator;
|
|||
import org.apache.lucene.util.Bits;
|
||||
import org.apache.lucene.util.FixedBitSet;
|
||||
|
||||
/** Test cases for KnnVectorQuery objects. */
|
||||
/** Test cases for AbstractKnnVectorQuery objects. */
|
||||
abstract class BaseKnnVectorQueryTestCase extends LuceneTestCase {
|
||||
|
||||
abstract AbstractKnnVectorQuery getKnnVectorQuery(
|
||||
|
|
|
|||
|
|
@ -56,9 +56,8 @@ class MockVectorValues extends AbstractMockVectorValues<float[]> {
|
|||
return values[pos];
|
||||
} else {
|
||||
// Sometimes use the same scratch array repeatedly, mimicing what the codec will do.
|
||||
// This should help us catch cases of aliasing where the same VectorValues source is used
|
||||
// twice in a
|
||||
// single computation.
|
||||
// This should help us catch cases of aliasing where the same vector values source is used
|
||||
// twice in a single computation.
|
||||
System.arraycopy(values[pos], 0, scratch, 0, dimension);
|
||||
return scratch;
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue