Interface Search

All Known Implementing Classes:
DefaultDocumentStore.DefaultSearch
public interface Search
Fluent interface for building and executing document search queries in Fluxzero.

A Search instance is typically obtained via Fluxzero.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:

Example usage: 

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

  • 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:

  • 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

    • since

      default Search since(LocalDate start)
      Initiates a search operation from a specified start date.
      Parameters:
      start - the start date from which the search is to be started.
      Returns:
      a Search object initialized with the converted instant from the specified start date.

    • 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

    • before

      default Search before(LocalDate endInclusive)
      Filters and returns search results that occur before the specified end date, inclusive.
      Parameters:
      endInclusive - the end date to compare with, inclusive
      Returns:
      a Search object containing results that occur before the specified end date

    • 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.

    • inPeriod

      default Search inPeriod(LocalDate start, LocalDate endInclusive)
      Filters the search results to include only those within the specified date 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

    • sortByTimestamp

      default Search sortByTimestamp(boolean descending, Search.NullOrder nullOrder)
      Sorts results by timestamp, with explicit null ordering.

    • 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.

    • sortBy

      default Search sortBy(String path, Search.NullOrder nullOrder)
      Sorts results by a specific document field, with explicit null ordering.

    • sortBy

      default Search sortBy(String path, boolean descending, Search.NullOrder nullOrder)
      Sorts results by a field, with control over both sort direction and null ordering.

    • 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.

    • fetchAsync

      default <T> CompletableFuture<List<T>> fetchAsync(int maxSize)
      Asynchronously fetches up to the given number of matching documents and deserializes them to the stored type.

      This is the asynchronous counterpart of fetch(int). The returned future completes with a materialized list containing at most maxSize results.

      Type Parameters:
      T - the expected result type
      Parameters:
      maxSize - the maximum number of matching documents to fetch
      Returns:
      a future containing the deserialized search results

    • 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.

    • fetchAsync

      <T> CompletableFuture<List<T>> fetchAsync(int maxSize, Class<T> type)
      Asynchronously fetches up to the given number of documents and deserializes them to the specified type.

      This is the asynchronous counterpart of fetch(int, Class). Use this method when handling requests that can return a CompletableFuture; for very large result sets, prefer the streaming methods.

      Type Parameters:
      T - the expected result type
      Parameters:
      maxSize - the maximum number of matching documents to fetch
      type - the type to deserialize each document to
      Returns:
      a future containing the deserialized search results

    • 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.

    • toUtf8InputStream

      default <T> InputStream toUtf8InputStream(Class<T> type, ThrowingFunction<T,String> mapper)
      Streams matching values of the specified type as a lazily populated UTF-8 InputStream.

    • toUtf8InputStream

      default <T> InputStream toUtf8InputStream(Class<T> type, ThrowingFunction<T,String> mapper, int fetchSize)
      Streams matching values of the specified type as a lazily populated UTF-8 InputStream, fetching documents in batches of fetchSize.

    • toInputStream

      default <T> InputStream toInputStream(Class<T> type, ThrowingBiConsumer<T, OutputStream> writer)
      Streams matching values of the specified type as a lazily populated InputStream.

    • toInputStream

      default <T> InputStream toInputStream(Class<T> type, ThrowingBiConsumer<T, OutputStream> writer, int fetchSize)
      Streams matching values of the specified type as a lazily populated InputStream, fetching documents in batches of fetchSize.

    • toNdjsonInputStream

      default InputStream toNdjsonInputStream()
      Streams matching values as NDJSON using the stored document types and the default fetch size.

    • 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.

    • countAsync

      default CompletableFuture<Long> countAsync()
      Asynchronously returns the number of matching documents.

      This is the asynchronous counterpart of count().

      Returns:
      a future containing the matching document count

    • aggregate

      default Map<String, DocumentStats.FieldStats> aggregate(String... fields)
      Returns field statistics for one or more fields.

    • aggregateAsync

      default CompletableFuture<Map<String, DocumentStats.FieldStats>> aggregateAsync(String... fields)
      Asynchronously returns field statistics for one or more fields.

      This is the asynchronous counterpart of aggregate(String...) and returns the statistics for the ungrouped result set.

      Parameters:
      fields - the fields to compute statistics for; omit fields to request the default count statistics
      Returns:
      a future containing field statistics keyed by field name

    • facetStats

      List<FacetStats> facetStats()
      Returns facet statistics for the current search.

    • facetStatsAsync

      CompletableFuture<List<FacetStats>> facetStatsAsync()
      Asynchronously returns facet statistics for the current search.

      This is the asynchronous counterpart of facetStats().

      Returns:
      a future containing facet value counts for the matching documents

    • delete

      CompletableFuture<Void> delete()
      Deletes all matching documents in the current search.

    • move

      CompletableFuture<Void> move(Object targetCollection)
      Moves all matching documents in the current search to the given collection.
      Parameters:
      targetCollection - the collection to move to