Interface SearchClient

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
InMemorySearchStore, WebSocketSearchClient
public interface SearchClient extends AutoCloseable
Low-level interface for interacting with a search and indexing service in Fluxzero.

The SearchClient operates exclusively on serialized forms of documents (see SerializedDocument) and search-related requests. It is the primary interface used by internal components like DocumentStore to execute actual search operations against a backing implementation (e.g., Fluxzero Runtime or an in-memory search engine for testing).

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    CompletableFuture<Void>
    bulkUpdate(Collection<io.fluxzero.common.api.search.DocumentUpdate> updates, io.fluxzero.common.Guarantee guarantee)
    Performs a batch update on a set of documents.
    void
    close()
    Closes any underlying resources.
    CompletableFuture<Void>
    createAuditTrail(io.fluxzero.common.api.search.CreateAuditTrail request)
    Configures Fluxzero to use a search collection as a searchable audit trail.
    CompletableFuture<Void>
    delete(io.fluxzero.common.api.search.SearchQuery query, io.fluxzero.common.Guarantee guarantee)
    Deletes documents matching a given query.
    CompletableFuture<Void>
    delete(String documentId, String collection, io.fluxzero.common.Guarantee guarantee)
    Deletes a document by its unique id and collection name.
    default CompletableFuture<Void>
    deleteCollection(String collection)
    Deletes an entire document collection and all its contents.
    CompletableFuture<Void>
    deleteCollection(String collection, io.fluxzero.common.Guarantee guarantee)
    Deletes an entire document collection and all its contents.
    boolean
    documentExists(io.fluxzero.common.api.search.HasDocument request)
    Checks whether a document with the given criteria exists.
    Optional<io.fluxzero.common.api.search.SerializedDocument>
    fetch(io.fluxzero.common.api.search.GetDocument request)
    Fetches a single serialized document matching the given request.
    Collection<io.fluxzero.common.api.search.SerializedDocument>
    fetch(io.fluxzero.common.api.search.GetDocuments request)
    Fetches a collection of serialized documents that match the given request.
    List<io.fluxzero.common.api.search.FacetStats>
    fetchFacetStats(io.fluxzero.common.api.search.SearchQuery query)
    Retrieves facet statistics (i.e., value counts) for a given query.
    default CompletableFuture<List<io.fluxzero.common.api.search.FacetStats>>
    fetchFacetStatsAsync(io.fluxzero.common.api.search.SearchQuery query)
    Asynchronously retrieves facet statistics for a given query.
    io.fluxzero.common.api.search.SearchHistogram
    fetchHistogram(io.fluxzero.common.api.search.GetSearchHistogram request)
    Fetches a histogram (bucketed time-series view) for documents matching the query.
    default CompletableFuture<io.fluxzero.common.api.search.SearchHistogram>
    fetchHistogramAsync(io.fluxzero.common.api.search.GetSearchHistogram request)
    Asynchronously fetches a histogram for documents matching the query.
    List<io.fluxzero.common.api.search.DocumentStats>
    fetchStatistics(io.fluxzero.common.api.search.SearchQuery query, List<String> fields, List<String> groupBy)
    Retrieves search statistics (counts, averages, etc.) over matching documents.
    default CompletableFuture<List<io.fluxzero.common.api.search.DocumentStats>>
    fetchStatisticsAsync(io.fluxzero.common.api.search.SearchQuery query, List<String> fields, List<String> groupBy)
    Asynchronously retrieves search statistics over matching documents.
    default List<io.fluxzero.common.api.search.SearchCollection>
    getSearchCollections()
    Retrieves existing regular search collections and audit trails.
    CompletableFuture<Void>
    index(List<io.fluxzero.common.api.search.SerializedDocument> documents, io.fluxzero.common.Guarantee guarantee, boolean ifNotExists)
    Indexes a list of serialized documents into the search engine.
    CompletableFuture<Void>
    move(io.fluxzero.common.api.search.SearchQuery query, String targetCollection, io.fluxzero.common.Guarantee guarantee)
    Moves documents matching a given query to the given target collection.
    CompletableFuture<Void>
    move(String documentId, String collection, String targetCollection, io.fluxzero.common.Guarantee guarantee)
    Moves a document to another collection.
    Stream<SearchHit<io.fluxzero.common.api.search.SerializedDocument>>
    search(io.fluxzero.common.api.search.SearchDocuments searchDocuments, int fetchSize)
    Executes a streaming search query using the given criteria and fetch size.
    default CompletableFuture<List<SearchHit<io.fluxzero.common.api.search.SerializedDocument>>>
    searchAsync(io.fluxzero.common.api.search.SearchDocuments searchDocuments, int fetchSize)
    Asynchronously executes a search query using the given criteria and fetch size and materializes the matching hits.

  • Method Details

    • getSearchCollections

      default List<io.fluxzero.common.api.search.SearchCollection> getSearchCollections()
      Retrieves existing regular search collections and audit trails.

      Implementations predating this operation may throw UnsupportedOperationException.

      Returns:
      the available collections with their storage types, in deterministic order

    • index

      CompletableFuture<Void> index(List<io.fluxzero.common.api.search.SerializedDocument> documents, io.fluxzero.common.Guarantee guarantee, boolean ifNotExists)
      Indexes a list of serialized documents into the search engine.
      Parameters:
      documents - the documents to index
      guarantee - delivery guarantee (see Guarantee)
      ifNotExists - if true, only index documents that do not already exist
      Returns:
      a future that completes when the operation is done

    • search

      Stream<SearchHit<io.fluxzero.common.api.search.SerializedDocument>> search(io.fluxzero.common.api.search.SearchDocuments searchDocuments, int fetchSize)
      Executes a streaming search query using the given criteria and fetch size.
      Parameters:
      searchDocuments - the search parameters and query
      fetchSize - the number of results to fetch per page
      Returns:
      a stream of search hits matching the query

    • searchAsync

      default CompletableFuture<List<SearchHit<io.fluxzero.common.api.search.SerializedDocument>>> searchAsync(io.fluxzero.common.api.search.SearchDocuments searchDocuments, int fetchSize)
      Asynchronously executes a search query using the given criteria and fetch size and materializes the matching hits.

      The default implementation adapts search(SearchDocuments, int) to a future. Remote clients can override this method to use a native asynchronous transport.

      Parameters:
      searchDocuments - the search parameters and query
      fetchSize - the number of results to fetch per page
      Returns:
      a future with search hits matching the query

    • documentExists

      boolean documentExists(io.fluxzero.common.api.search.HasDocument request)
      Checks whether a document with the given criteria exists.
      Parameters:
      request - an object describing the document (e.g., id and collection)
      Returns:
      true if the document exists, false otherwise

    • fetch

      Optional<io.fluxzero.common.api.search.SerializedDocument> fetch(io.fluxzero.common.api.search.GetDocument request)
      Fetches a single serialized document matching the given request.
      Parameters:
      request - an object describing the document to retrieve
      Returns:
      an optional containing the document, if found

    • fetch

      Collection<io.fluxzero.common.api.search.SerializedDocument> fetch(io.fluxzero.common.api.search.GetDocuments request)
      Fetches a collection of serialized documents that match the given request.
      Parameters:
      request - an object describing the documents to retrieve
      Returns:
      a collection of retrieved documents matching

    • delete

      CompletableFuture<Void> delete(io.fluxzero.common.api.search.SearchQuery query, io.fluxzero.common.Guarantee guarantee)
      Deletes documents matching a given query.
      Parameters:
      query - the search query specifying which documents to delete
      guarantee - delivery guarantee
      Returns:
      a future that completes when the deletion has been performed

    • move

      CompletableFuture<Void> move(io.fluxzero.common.api.search.SearchQuery query, String targetCollection, io.fluxzero.common.Guarantee guarantee)
      Moves documents matching a given query to the given target collection.
      Parameters:
      query - the search query specifying which documents to move
      targetCollection - the name of the collection to move documents to
      guarantee - delivery guarantee
      Returns:
      a future that completes when the move has been performed

    • delete

      CompletableFuture<Void> delete(String documentId, String collection, io.fluxzero.common.Guarantee guarantee)
      Deletes a document by its unique id and collection name.
      Parameters:
      documentId - the document id
      collection - the collection to delete from
      guarantee - delivery guarantee
      Returns:
      a future that completes when the deletion has been performed

    • move

      CompletableFuture<Void> move(String documentId, String collection, String targetCollection, io.fluxzero.common.Guarantee guarantee)
      Moves a document to another collection.
      Parameters:
      documentId - the document id
      collection - the collection to move from
      targetCollection - the collection to move to
      guarantee - delivery guarantee
      Returns:
      a future that completes when the move has been performed

    • createAuditTrail

      CompletableFuture<Void> createAuditTrail(io.fluxzero.common.api.search.CreateAuditTrail request)
      Configures Fluxzero to use a search collection as a searchable audit trail.
      Parameters:
      request - a request object specifying the collection to use as an audit trail and retention configuration
      Returns:
      a future that completes when the audit trail has been created.

    • deleteCollection

      default CompletableFuture<Void> deleteCollection(String collection)
      Deletes an entire document collection and all its contents.
      Parameters:
      collection - the name of the collection to delete
      Returns:
      a future that completes when the collection has been deleted

    • deleteCollection

      CompletableFuture<Void> deleteCollection(String collection, io.fluxzero.common.Guarantee guarantee)
      Deletes an entire document collection and all its contents.
      Parameters:
      collection - the name of the collection to delete
      guarantee - delivery guarantee
      Returns:
      a future that completes when the collection has been deleted

    • fetchStatistics

      List<io.fluxzero.common.api.search.DocumentStats> fetchStatistics(io.fluxzero.common.api.search.SearchQuery query, List<String> fields, List<String> groupBy)
      Retrieves search statistics (counts, averages, etc.) over matching documents.
      Parameters:
      query - the query to filter documents
      fields - the fields to compute statistics for
      groupBy - field names used to group statistics
      Returns:
      a list of DocumentStats

    • fetchStatisticsAsync

      default CompletableFuture<List<io.fluxzero.common.api.search.DocumentStats>> fetchStatisticsAsync(io.fluxzero.common.api.search.SearchQuery query, List<String> fields, List<String> groupBy)
      Asynchronously retrieves search statistics over matching documents.

      The default implementation adapts fetchStatistics(SearchQuery, List, List) to a future. Remote clients can override this method to use a native asynchronous transport.

      Parameters:
      query - the query to filter documents
      fields - the fields to compute statistics for
      groupBy - field names used to group statistics
      Returns:
      a future with search statistics

    • fetchHistogram

      io.fluxzero.common.api.search.SearchHistogram fetchHistogram(io.fluxzero.common.api.search.GetSearchHistogram request)
      Fetches a histogram (bucketed time-series view) for documents matching the query.
      Parameters:
      request - the histogram query parameters
      Returns:
      a SearchHistogram representing the result

    • fetchHistogramAsync

      default CompletableFuture<io.fluxzero.common.api.search.SearchHistogram> fetchHistogramAsync(io.fluxzero.common.api.search.GetSearchHistogram request)
      Asynchronously fetches a histogram for documents matching the query.

      The default implementation adapts fetchHistogram(GetSearchHistogram) to a future. Remote clients can override this method to use a native asynchronous transport.

      Parameters:
      request - the histogram query parameters
      Returns:
      a future with the histogram for matching documents

    • fetchFacetStats

      List<io.fluxzero.common.api.search.FacetStats> fetchFacetStats(io.fluxzero.common.api.search.SearchQuery query)
      Retrieves facet statistics (i.e., value counts) for a given query.
      Parameters:
      query - the query to match documents against
      Returns:
      a list of facet statistics

    • fetchFacetStatsAsync

      default CompletableFuture<List<io.fluxzero.common.api.search.FacetStats>> fetchFacetStatsAsync(io.fluxzero.common.api.search.SearchQuery query)
      Asynchronously retrieves facet statistics for a given query.

      The default implementation adapts fetchFacetStats(SearchQuery) to a future. Remote clients can override this method to use a native asynchronous transport.

      Parameters:
      query - the query to match documents against
      Returns:
      a future with facet statistics

    • bulkUpdate

      CompletableFuture<Void> bulkUpdate(Collection<io.fluxzero.common.api.search.DocumentUpdate> updates, io.fluxzero.common.Guarantee guarantee)
      Performs a batch update on a set of documents.
      Parameters:
      updates - the update operations to perform
      guarantee - delivery guarantee
      Returns:
      a future that completes when the updates have been applied

    • close

      void close()
      Closes any underlying resources.
      Specified by:
      close in interface AutoCloseable