Implementation:Lance format Lance Java FullTextQuery

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

Overview

The FullTextQuery abstract class defines the full-text search query types supported by the Lance scanner, including match, phrase, multi-match, boost, and boolean queries.

Description

FullTextQuery is an abstract base class with static factory methods for constructing different types of full-text search queries. It is used with ScanOptions to perform text search on indexed columns in a Lance dataset. The class defines five query types through nested final classes:

• MatchQuery: Matches individual terms against a single column with optional fuzziness, boosting, operator (AND/OR), and prefix length configuration
• PhraseQuery: Matches an exact phrase against a single column with configurable slop (word distance tolerance)
• MultiMatchQuery: Matches terms across multiple columns with per-column boost weights and operator configuration
• BoostQuery: Combines a positive and negative query, demoting results matching the negative query by a configurable boost factor
• BooleanQuery: Composes multiple queries using boolean clauses with SHOULD, MUST, or MUST_NOT occurrence semantics

The class also defines supporting enums:

• Type: MATCH, MATCH_PHRASE, BOOST, MULTI_MATCH, BOOLEAN
• Operator: AND, OR
• Occur: SHOULD, MUST, MUST_NOT

Usage

Use FullTextQuery when you need to perform text search against Lance datasets that have full-text indices on string columns. Pass the constructed query to ScanOptions.Builder.fullTextQuery() to integrate it into a scan operation.

Code Reference

Source Location

Property	Value
File	java/src/main/java/org/lance/ipc/FullTextQuery.java
Package	org.lance.ipc
Lines	360

Signature

public abstract class FullTextQuery

Import

import org.lance.ipc.FullTextQuery;

I/O Contract

Static Factory Methods

Method	Input	Output	Description
match(String, String)	queryText, column	FullTextQuery	Simple match query with defaults
match(String, String, float, Optional<Integer>, int, Operator, int)	queryText, column, boost, fuzziness, maxExpansions, operator, prefixLength	FullTextQuery	Full match query with all options
phrase(String, String)	queryText, column	FullTextQuery	Phrase query with default slop of 0
phrase(String, String, int)	queryText, column, slop	FullTextQuery	Phrase query with custom slop
multiMatch(String, List<String>)	queryText, columns	FullTextQuery	Multi-column match with defaults
multiMatch(String, List<String>, List<Float>, Operator)	queryText, columns, boosts, operator	FullTextQuery	Multi-column match with boosts and operator
boost(FullTextQuery, FullTextQuery)	positive, negative	FullTextQuery	Boost query with default negative boost of 0.5
boost(FullTextQuery, FullTextQuery, float)	positive, negative, negativeBoost	FullTextQuery	Boost query with custom negative boost
booleanQuery(List<BooleanClause>)	clauses	FullTextQuery	Boolean query from clauses

Instance Methods

Method	Output	Description
getType()	FullTextQuery.Type	Returns the query type enum value

Usage Examples

Simple Match Query

import org.lance.ipc.FullTextQuery;
import org.lance.ipc.ScanOptions;

FullTextQuery query = FullTextQuery.match("machine learning", "description");

ScanOptions options = new ScanOptions.Builder()
    .fullTextQuery(query)
    .build();

Fuzzy Match Query

import org.lance.ipc.FullTextQuery;
import java.util.Optional;

FullTextQuery query = FullTextQuery.match(
    "mashine lerning",      // intentional typos
    "description",
    1.0f,                   // boost
    Optional.of(2),         // fuzziness (edit distance)
    50,                     // max expansions
    FullTextQuery.Operator.AND,
    0                       // prefix length
);

Phrase Query with Slop

import org.lance.ipc.FullTextQuery;

// Match "machine learning" allowing up to 2 words between terms
FullTextQuery query = FullTextQuery.phrase("machine learning", "description", 2);

Multi-Column Match

import org.lance.ipc.FullTextQuery;
import java.util.Arrays;

FullTextQuery query = FullTextQuery.multiMatch(
    "neural network",
    Arrays.asList("title", "description", "abstract"),
    Arrays.asList(2.0f, 1.0f, 0.5f),   // boost per column
    FullTextQuery.Operator.OR
);

Boolean Query

import org.lance.ipc.FullTextQuery;
import org.lance.ipc.FullTextQuery.BooleanClause;
import org.lance.ipc.FullTextQuery.Occur;
import java.util.Arrays;

FullTextQuery query = FullTextQuery.booleanQuery(Arrays.asList(
    new BooleanClause(Occur.MUST, FullTextQuery.match("machine learning", "title")),
    new BooleanClause(Occur.SHOULD, FullTextQuery.match("deep learning", "description")),
    new BooleanClause(Occur.MUST_NOT, FullTextQuery.match("deprecated", "status"))
));

Related Pages

• Lance_format_Lance_Java_ScanOptions - Scan options that accept full-text queries
• Lance_format_Lance_Java_Dataset - Dataset class whose scanner uses these queries