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.

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

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

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

    • 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