Implementation:Lance format Lance Java Query

Knowledge Sources	Lance
Domains	Java_SDK, Dataset_Management
Last Updated	2026-02-08 19:33 GMT

Overview

Description

The Query class is an immutable configuration object for vector nearest-neighbor (ANN) search within the Lance Java SDK. It encapsulates all parameters needed for a vector similarity search, including the target column, search vector, number of results (k), probe configuration, HNSW parameters, distance metric, and index usage preferences.

The class is constructed exclusively through its Builder and validates inputs at build time: the column name must be non-null and non-empty, the search key must be non-null, k must be greater than 0, minimum nprobes must be greater than 0, and maximum nprobes (if set) must be greater than or equal to minimum nprobes.

The probe parameters support adaptive search: minimumNprobes partitions are always searched, while additional partitions up to maximumNprobes are searched only if the desired number of results has not been found. The convenience method setNprobes() sets both minimum and maximum to the same value.

Usage

Use Query as part of ScanOptions to perform vector similarity search on a Lance dataset. Pass the query to the scanner's nearest-neighbor option. The query can be combined with SQL filters for filtered vector search.

Code Reference

Source Location

java/src/main/java/org/lance/ipc/Query.java

Signature

public class Query {
    public String getColumn();
    public float[] getKey();
    public int getK();
    public int getMinimumNprobes();
    public Optional<Integer> getMaximumNprobes();
    public Optional<Integer> getEf();
    public Optional<Integer> getRefineFactor();
    public Optional<DistanceType> getDistanceType();
    public Optional<String> getDistanceTypeString();
    public boolean isUseIndex();

    public static class Builder {
        public Builder setColumn(String column);
        public Builder setKey(float[] key);
        public Builder setK(int k);
        public Builder setNprobes(int nprobes);
        public Builder setMinimumNprobes(int minimumNprobes);
        public Builder setMaximumNprobes(int maximumNprobes);
        public Builder setEf(int ef);
        public Builder setRefineFactor(int refineFactor);
        public Builder setDistanceType(DistanceType distanceType);
        public Builder setUseIndex(boolean useIndex);
        public Query build();
    }
}

Import

import org.lance.ipc.Query;

I/O Contract

Builder Inputs

Parameter	Type	Required	Default	Description
column	String	Yes	--	Name of the vector column to search
key	float[]	Yes	--	The query vector
k	int	No	10	Number of nearest neighbors to return
minimumNprobes	int	No	1	Minimum number of IVF partitions to search
maximumNprobes	int	No	empty	Maximum partitions; searched only if results are insufficient
ef	int	No	empty	HNSW candidate count (for HNSW-related index types)
refineFactor	int	No	empty	Refine factor for applying a refine step after initial search
distanceType	DistanceType	No	empty	Distance metric (L2, Cosine, Hamming, etc.); defaults to index metric or data type default
useIndex	boolean	No	true	Whether to use an ANN index if available

Query Outputs

Method	Return Type	Description
getColumn()	String	The vector column name
getKey()	float[]	The query vector
getK()	int	Number of results to return
getMinimumNprobes()	int	Minimum partitions to search
getMaximumNprobes()	Optional<Integer>	Maximum partitions to search
getEf()	Optional<Integer>	HNSW candidate count
getRefineFactor()	Optional<Integer>	Refine factor
getDistanceType()	Optional<DistanceType>	Distance metric
isUseIndex()	boolean	Whether to use the ANN index

Usage Examples

// Basic vector search: find 5 nearest neighbors
Query query = new Query.Builder()
    .setColumn("embedding")
    .setKey(new float[]{0.1f, 0.2f, 0.3f, 0.4f})
    .setK(5)
    .build();

// Advanced vector search with HNSW parameters and custom distance
Query advancedQuery = new Query.Builder()
    .setColumn("embedding")
    .setKey(queryVector)
    .setK(20)
    .setMinimumNprobes(5)
    .setMaximumNprobes(20)
    .setEf(100)
    .setRefineFactor(10)
    .setDistanceType(DistanceType.Cosine)
    .build();

// Brute-force search (no index)
Query bruteForceQuery = new Query.Builder()
    .setColumn("embedding")
    .setKey(queryVector)
    .setK(10)
    .setUseIndex(false)
    .build();

Related Pages

• Lance_format_Lance_Java_LanceScanner -- Scanner that accepts Query as a nearest-neighbor search parameter
• Lance_format_Lance_Java_CreateIndexOp -- Creates vector indices used by Query