Package io.fluxcapacitor.javaclient.persisting.search

Interface Search

All Known Implementing Classes:

DefaultDocumentStore.DefaultSearch

public interface Search

Fluent interface for building and executing document search queries in Flux Capacitor.

A Search instance is typically obtained via FluxCapacitor.search("collectionName") and can be configured using a combination of time-based constraints, field constraints, sorting rules, pagination, and content selection.

The search is only executed when a terminal operation like fetch(...) or stream() is invoked.

Supported operations include:

• Time-based filtering (e.g. since(Instant), inLast(Duration))
• Content-based filtering (e.g. match(Object, String...), query(String, String...))
• Sorting and pagination (e.g. sortByTimestamp(), skip(Integer))
• Aggregation and facets (e.g. aggregate(String...), facetStats())
• Streaming and fetching results (e.g. stream(), fetch(int))

Example usage:

 List<MyDocument> results = FluxCapacitor.search("myCollection")
     .inLast(Duration.ofDays(30))
     .match("searchTerm", "title", "description")
     .sortByTimestamp(true)
     .fetch(50);
 

See Also:

• FluxCapacitor.search(java.lang.Object)

Field Summary

Fields

Modifier and Type	Field	Description
static final int	defaultFetchSize	The default number of records to fetch in a single batch during search operations.

Method Summary

Modifier and Type	Method	Description
default Map<String,DocumentStats.FieldStats>	aggregate(String... fields)	Returns field statistics for one or more fields.
default Search	all(Constraint... constraints)	Combines multiple constraints using a logical AND.
default Search	any(Constraint... constraints)	Combines multiple constraints using a logical OR.
default Search	anyExist(String... paths)	Constrains the search to documents that have any of the given paths.
default Search	atLeast(Number min, String path)	Adds a lower-bound constraint for a field.
default Search	before(Instant endExclusive)	Filters documents with timestamps strictly before the given end time.
Search	before(Instant end, boolean inclusive)	Filters documents with timestamps before the given time.
default Search	beforeLast(Duration period)	Filters out documents older than the given duration.
default Search	below(Number max, String path)	Adds an upper-bound constraint for a field.
default Search	between(Number min, Number maxExclusive, String path)	Adds a numeric range constraint.
Search	constraint(Constraint... constraints)	Adds one or more custom constraints to the search using a logical AND.
default Long	count()	Returns the number of matching documents.
CompletableFuture<Void>	delete()	Deletes all matching documents in the current search.
Search	exclude(String... paths)	Excludes specific fields from the returned documents.
List<FacetStats>	facetStats()	Returns facet statistics for the current search.
<T> List<T>	fetch(int maxSize)	Fetches up to the given number of matching documents and deserializes them to the stored type.
<T> List<T>	fetch(int maxSize, Class<T> type)	Fetches up to the given number of documents and deserializes them to the specified type.
default <T> List<T>	fetchAll()	Fetches all matching documents and deserializes each to its stored type.
default <T> List<T>	fetchAll(Class<T> type)	Fetches all matching documents and deserializes them to the specified type.
default <T> Optional<T>	fetchFirst()	Fetches the first matching document if available and deserializes it to the stored type.
default <T> Optional<T>	fetchFirst(Class<T> type)	Fetches the first matching document if available and deserializes it as an optional value of the specified type.
default <T> T	fetchFirstOrNull()	Fetches the first matching document if available and deserializes it to the stored type.
default <T> T	fetchFirstOrNull(Class<T> type)	Fetches the first matching document if available and deserializes it to the specified type.
SearchHistogram	fetchHistogram(int resolution, int maxSize)	Computes a histogram for the timestamp distribution of matching documents.
GroupSearch	groupBy(String... paths)	Groups search results by field(s) and supports aggregations.
Search	includeOnly(String... paths)	Includes only the specified fields in the returned documents.
default Search	inLast(Duration period)	Filters documents within the last given duration (e.g., last 7 days).
Search	inPeriod(Instant start, boolean startInclusive, Instant end, boolean endInclusive)	Filters documents within a specified time range.
default Search	inPeriod(Instant start, Instant endExclusive)	Filters documents within the given time range.
default Search	lookAhead(String phrase, String... paths)	Adds a full-text lookahead constraint using the specified phrase.
default Search	match(Object constraint, boolean strict, String... paths)	Adds a match constraint, optionally enforcing strict equality.
default Search	match(Object constraint, String... paths)	Adds an equality match constraint for the given value across one or more paths.
default Search	matchFacet(String name, Object value)	Matches the value of a named facet.
default Search	matchMetadata(String key, Object value)	Matches a metadata key to a value.
default Search	not(Constraint constraint)	Negates a constraint using a logical NOT.
default Search	query(String phrase, String... paths)	Adds a full-text search constraint for the given phrase.
default Search	since(Instant start)	Filters documents with timestamps since the given start time (inclusive).
Search	since(Instant start, boolean inclusive)	Filters documents with timestamps since the given start time.
Search	skip(Integer n)	Skips the first N results.
default Search	sortBy(String path)	Sorts results by a specific document field.
Search	sortBy(String path, boolean descending)	Sorts results by a field, with control over the sort direction.
Search	sortByScore()	Sorts results by full-text relevance score.
default Search	sortByTimestamp()	Sorts results by timestamp in ascending order.
Search	sortByTimestamp(boolean descending)	Sorts results by timestamp.
default <T> Stream<T>	stream()	Streams matching values, deserializing each to the stored type.
default <T> Stream<T>	stream(int fetchSize)	Streams matching values, deserializing each to the stored type.
default <T> Stream<T>	stream(Class<T> type)	Streams matching values, deserializing each to the specified type.
default <T> Stream<T>	stream(Class<T> type, int fetchSize)	Streams matching values, deserializing each to the specified type.
<T> Stream<SearchHit<T>>	streamHits()	Streams raw search hits (document + metadata).
<T> Stream<SearchHit<T>>	streamHits(int fetchSize)	Streams raw search hits (document + metadata).
<T> Stream<SearchHit<T>>	streamHits(Class<T> type)	Streams raw search hits (document + metadata).
<T> Stream<SearchHit<T>>	streamHits(Class<T> type, int fetchSize)	Streams raw search hits (document + metadata).

Field Details

defaultFetchSize

static final int defaultFetchSize

The default number of records to fetch in a single batch during search operations. Primarily used in streaming and batch-fetching methods to control the size of each data retrieval operation.

A higher value increases the data fetch per operation, potentially reducing the number of retrievals but consuming more memory. A lower value minimizes memory usage but may require more network or database calls for large datasets.

See Also:

• Constant Field Values

Method Details

since

default Search since(Instant start)

Filters documents with timestamps since the given start time (inclusive).

since

Search since(Instant start,
 boolean inclusive)

Filters documents with timestamps since the given start time.

Parameters:

inclusive - whether the start boundary is inclusive

before

default Search before(Instant endExclusive)

Filters documents with timestamps strictly before the given end time.

before

Search before(Instant end,
 boolean inclusive)

Filters documents with timestamps before the given time.

Parameters:

inclusive - whether the end boundary is inclusive

beforeLast

default Search beforeLast(Duration period)

Filters out documents older than the given duration.

inLast

default Search inLast(Duration period)

Filters documents within the last given duration (e.g., last 7 days).

inPeriod

default Search inPeriod(Instant start,
 Instant endExclusive)

Filters documents within the given time range.

inPeriod

Search inPeriod(Instant start,
 boolean startInclusive,
 Instant end,
 boolean endInclusive)

Filters documents within a specified time range.

lookAhead

default Search lookAhead(String phrase,
 String... paths)

Adds a full-text lookahead constraint using the specified phrase.

query

default Search query(String phrase,
 String... paths)

Adds a full-text search constraint for the given phrase.

match

default Search match(Object constraint,
 String... paths)

Adds an equality match constraint for the given value across one or more paths.

match

default Search match(Object constraint,
 boolean strict,
 String... paths)

Adds a match constraint, optionally enforcing strict equality.

matchFacet

default Search matchFacet(String name,
 Object value)

Matches the value of a named facet.

matchMetadata

default Search matchMetadata(String key,
 Object value)

Matches a metadata key to a value.

anyExist

default Search anyExist(String... paths)

Constrains the search to documents that have any of the given paths.

atLeast

default Search atLeast(Number min,
 String path)

Adds a lower-bound constraint for a field.

below

default Search below(Number max,
 String path)

Adds an upper-bound constraint for a field.

between

default Search between(Number min,
 Number maxExclusive,
 String path)

Adds a numeric range constraint.

all

default Search all(Constraint... constraints)

Combines multiple constraints using a logical AND.

any

default Search any(Constraint... constraints)

Combines multiple constraints using a logical OR.

not

default Search not(Constraint constraint)

Negates a constraint using a logical NOT.

constraint

Search constraint(Constraint... constraints)

Adds one or more custom constraints to the search using a logical AND.

sortByTimestamp

default Search sortByTimestamp()

Sorts results by timestamp in ascending order.

sortByTimestamp

Search sortByTimestamp(boolean descending)

Sorts results by timestamp.

Parameters:

descending - whether to sort in descending order

sortByScore

Search sortByScore()

Sorts results by full-text relevance score.

sortBy

default Search sortBy(String path)

Sorts results by a specific document field.

sortBy

Search sortBy(String path,
 boolean descending)

Sorts results by a field, with control over the sort direction.

exclude

Search exclude(String... paths)

Excludes specific fields from the returned documents.

includeOnly

Search includeOnly(String... paths)

Includes only the specified fields in the returned documents.

skip

Search skip(Integer n)

Skips the first N results.

fetch

<T> List<T> fetch(int maxSize)

Fetches up to the given number of matching documents and deserializes them to the stored type. Returns the deserialized values as instances of type T.

fetch

<T> List<T> fetch(int maxSize,
 Class<T> type)

Fetches up to the given number of documents and deserializes them to the specified type.

fetchAll

default <T> List<T> fetchAll()

Fetches all matching documents and deserializes each to its stored type. Returns the deserialized values as instances of type T.

fetchAll

default <T> List<T> fetchAll(Class<T> type)

Fetches all matching documents and deserializes them to the specified type.

fetchFirst

default <T> Optional<T> fetchFirst()

Fetches the first matching document if available and deserializes it to the stored type. Returns the deserialized value as an optional instance of type T.

fetchFirst

default <T> Optional<T> fetchFirst(Class<T> type)

Fetches the first matching document if available and deserializes it as an optional value of the specified type.

fetchFirstOrNull

default <T> T fetchFirstOrNull()

Fetches the first matching document if available and deserializes it to the stored type. Returns the deserialized value as an instance of type T.

fetchFirstOrNull

default <T> T fetchFirstOrNull(Class<T> type)

Fetches the first matching document if available and deserializes it to the specified type.

stream

default <T> Stream<T> stream()

Streams matching values, deserializing each to the stored type. Documents will typically be fetched in batches from the backing store. For the default implementation, the fetch size is 10,000.

stream

default <T> Stream<T> stream(int fetchSize)

Streams matching values, deserializing each to the stored type. Documents will be fetched in batches of size fetchSize from the backing store.

stream

default <T> Stream<T> stream(Class<T> type)

Streams matching values, deserializing each to the specified type. Documents will typically be fetched in batches from the backing store. For the default implementation, the fetch size is 10,000.

stream

default <T> Stream<T> stream(Class<T> type,
 int fetchSize)

Streams matching values, deserializing each to the specified type. Documents will be fetched in batches of size fetchSize from the backing store.

streamHits

<T> Stream<SearchHit<T>> streamHits()

Streams raw search hits (document + metadata). Documents will typically be fetched in batches from the backing store. For the default implementation, the fetch size is 10,000.

streamHits

<T> Stream<SearchHit<T>> streamHits(int fetchSize)

Streams raw search hits (document + metadata). Documents will be fetched in batches of size fetchSize from the backing store. For the default implementation, the fetch size is 10,000.

streamHits

<T> Stream<SearchHit<T>> streamHits(Class<T> type)

Streams raw search hits (document + metadata). Documents will be fetched in batches of size fetchSize from the backing store. For the default implementation, the fetch size is 10,000.

streamHits

<T> Stream<SearchHit<T>> streamHits(Class<T> type,
 int fetchSize)

Streams raw search hits (document + metadata). Documents will be fetched in batches of size fetchSize from the backing store. For the default implementation, the fetch size is 10,000.

fetchHistogram

SearchHistogram fetchHistogram(int resolution,
 int maxSize)

Computes a histogram for the timestamp distribution of matching documents.

groupBy

GroupSearch groupBy(String... paths)

Groups search results by field(s) and supports aggregations.

count

default Long count()

Returns the number of matching documents.

aggregate

default Map<String,DocumentStats.FieldStats> aggregate(String... fields)

Returns field statistics for one or more fields.

facetStats

List<FacetStats> facetStats()

Returns facet statistics for the current search.

delete

CompletableFuture<Void> delete()

Deletes all matching documents in the current search.