Package com.datastax.astra.client

Class Collection<T>

java.lang.Object
com.datastax.astra.internal.command.AbstractCommandRunner
com.datastax.astra.client.Collection<T>
Type Parameters:
T - Java bean to unmarshall documents for collection.
All Implemented Interfaces:
CommandRunner
public class Collection<T> extends AbstractCommandRunner
A Data API collection, the main object to interact with the Data API, especially for DDL operations.

A Collection is spawned from a Database object, from which it inherits the details on how to reach the API server (endpoint, authentication). A Collection has a name, which is its unique identifier for a namespace and options to specialize the usage as vector collections or advanced indexing parameters.

A Collection is typed object designed to work both with default @Document (wrapper for a Map) and application plain old java objects (pojo). The serialization is performed with Jackson and application beans can be annotated.

All features are provided in synchronous and asynchronous flavors.

Example usage:

 
 // Given a Database
 Database db = new DataAPIClient("token").getDatabase("api_endpoint");

 // Initialization with no POJO
 Collection<Document> collection = db.getCollection("collection1");

 // Initialization with POJO
 Collection<MyBean> collection = db.getCollection("collection1", MyBean.class);

  • Field Details

  • Constructor Details

    • Collection

      protected Collection(Database db, String collectionName, Class<T> clazz)
      Constructs an instance of a collection within the specified database. This constructor initializes the collection with a given name and associates it with a specific class type that represents the schema of documents within the collection. This setup is designed for CRUD (Create, Read, Update, Delete) operations.
      Parameters:
      db - The Database instance representing the client's namespace for HTTP communication with the database. It encapsulates the configuration and management of the database connection, ensuring that operations on this collection are executed within the context of this database.
      collectionName - A String that uniquely identifies the collection within the database. This name is used to route operations to the correct collection and should adhere to the database's naming conventions.
      clazz - The Class<DOC> object that represents the model for documents within this collection. This class is used for serialization and deserialization of documents to and from the database. It ensures type safety and facilitates the mapping of database documents to Java objects.

      Example usage:

       
 // Given a client
 DataAPIClient client = new DataAPIClient("token");
 // Given a database
 Database myDb = client.getDatabase("myDb");
 // Initialize a collection with a working class
 Collection<MyDocumentClass> myCollection = new Collection<>(myDb, "myCollectionName", MyDocumentClass.class);

  • Method Details

    • getNamespaceName

      public String getNamespaceName()
      Retrieves the name of the parent namespace associated with this collection. A namespace in this context typically refers to a higher-level categorization or grouping mechanism within the database that encompasses one or more collections. This method allows for identifying the broader context in which this collection exists, which can be useful for operations requiring knowledge of the database structure or for dynamic database interaction patterns.
      Returns:
      A String representing the name of the parent namespace of the current collection. This name serves as an identifier for the namespace and can be used to navigate or query the database structure.

      Example usage:

       
 Collection myCollection = ... // assume myCollection is already initialized
 String namespaceName = myCollection.getNamespaceName();
 System.out.println("The collection belongs to the namespace: " + namespaceName);

    • getDefinition

      public CollectionInfo getDefinition()
      Retrieves the full definition of the collection, encompassing both its name and its configuration options. This comprehensive information is encapsulated in a CollectionInfo object, providing access to the collection's metadata and settings.

      The returned CollectionInfo includes details such as the collection's name, which serves as its unique identifier within the database, and a set of options that describe its configuration. These options may cover aspects like indexing preferences, read/write permissions, and other customizable settings that were specified at the time of collection creation.

      Example usage:

       
 // Given a collection
 DataApiCollection<Document> collection;
 // Access its Definition
 CollectionDefinition definition = collection.getDefinition();
 System.out.println("Name=" + definition.getName());
 CollectionOptions options = definition.getOptions();
 if (options != null) {
   // Operations based on collection options
 }
      Returns:
      A CollectionInfo object containing the full definition of the collection, including its name and configuration options. This object provides a comprehensive view of the collection's settings and identity within the database.

    • getOptions

      public CollectionOptions getOptions()
      Retrieves the configuration options for the collection, including vector and indexing settings. These options specify how the collection should be created and managed, potentially affecting performance, search capabilities, and data organization.

      Example usage:

       
 // Given a collection
 DataApiCollection<Document> collection;
 // Access its Options
 CollectionOptions options = collection.getOptions();
 if (null != c.getVector()) {
   System.out.println(c.getVector().getDimension());
   System.out.println(c.getVector().getMetric());
 }
 if (null != c.getIndexing()) {
   System.out.println(c.getIndexing().getAllow());
   System.out.println(c.getIndexing().getDeny());
 }
      Returns:
      An instance of CollectionOptions containing the collection's configuration settings, such as vector and indexing options. Returns null if no options are set or applicable.

    • getName

      public String getName()
      Retrieves the name of the collection. This name serves as a unique identifier within the database and is used to reference the collection in database operations such as queries, updates, and deletions. The collection name is defined at the time of collection creation and is immutable.
      Returns:
      A String representing the name of the collection. This is the same name that was specified when the collection was created or initialized.

    • insertOne

      public final InsertOneResult insertOne(T document)
      Inserts a single document into the collection as an atomic operation, ensuring that the document is added in a single, indivisible step.

      Note: The document can optionally include an _id property, which serves as its unique identifier within the collection. If the _id property is provided and it matches the _id of an existing document in the collection, the insertion will fail and an error will be raised. This behavior ensures that each document in the collection has a unique identifier. If the _id property is not provided, the server will automatically generate a unique _id for the document, ensuring its uniqueness within the collection.

      The `_id` can be of multiple types, by default it can be any json scalar String, Number, $date. But at the collection definition level you can enforce property `defaultId` to work with specialize ids.

      • If defaultId is set to uuid, ids will be uuid v4 UUID
      • If defaultId is set to objectId, ids will be an ObjectId
      • If defaultId is set to uuidv6, ids will be an UUIDv6
      • If defaultId is set to uuidv7, ids will be an UUIDv7

      The method returns an InsertOneResult object, which provides details about the outcome of the insertion operation. This object can be used to verify the success of the operation and to access the _id of the inserted document, whether it was provided explicitly or generated automatically.

      Parameters:
      document - the document to be inserted into the collection. This parameter should represent the document in its entirety. The _id field is optional and, if omitted, will be automatically generated.
      Returns:
      An InsertOneResult object that contains information about the result of the insertion operation, including the _id of the newly inserted document.

      Example usage:

       
 // Create a document without id.
 Document newDocument = new Document("name", "John Doe").append("age", 30);
 InsertOneResult result = collection.insertOne(newDocument);
 System.out.println("(generated) document id: " + result.getInsertedId());

 // Provide a document id
 Document doc2 = Document.create("doc2").append("name", "John Doe").append("age", 30);
 InsertOneResult result = collection.insertOne(doc2);
 result.getInsertedId(); // will be "doc2"

 // More way to provide to populate ids.
 Document doc3 = new Document("doc3");
 Document doc4 = new Document().id("doc4");
 Document doc5 = new Document().append("_id", "doc5");

    • insertOneAsync

      public final CompletableFuture<InsertOneResult> insertOneAsync(T document)
      Asynchronously inserts a single document into the collection. This method provides the same functionality as insertOne(Object), but it operates asynchronously, returning a CompletableFuture that will be completed with the insertion result. Utilizing this method is beneficial for non-blocking operations, allowing other tasks to proceed while the document insertion is being processed.

      The asynchronous operation ensures that your application can remain responsive, making this method ideal for applications requiring high throughput or for operations that do not need immediate completion confirmation.

      For details on the behavior, parameters, and return type, refer to the documentation of the synchronous insertOne(Object) method. This method inherits all the properties and behaviors of its synchronous counterpart, including error handling and the generation or requirement of the _id field.

      Parameters:
      document - The document to be inserted into the collection. The specifications regarding the document structure and the _id field are the same as described in insertOne(Object).
      Returns:
      A CompletableFuture that, upon completion, contains the result of the insert operation as an InsertOneResult. The completion may occur with a result in case of success or with an exception in case of failure.

      Example usage:

       
 // Asynchronously inserting a document
 Document newDocument = new Document().append("name", "Async User").append("age", 34);
 CompletableFuture<InsertOneResult> futureResult = collection.insertOneAsync(newDocument);
 futureResult.thenAccept(result -> System.out.println("Inserted document id: " + result.getInsertedId()))
             .exceptionally(error -> { System.err.println("Insertion failed: " + error.getMessage()); return null; });

    • insertOne

      public final InsertOneResult insertOne(T document, float[] embeddings)
      Inserts a single document into the collection in an atomic operation, similar to the insertOne(Object) method, but with the additional capability to include vector embeddings. These embeddings are typically used for advanced querying capabilities, such as similarity search or machine learning models. This method ensures atomicity of the insertion, maintaining the integrity and consistency of the collection.

      Note: Like the base insertOne method, if the _id field is explicitly provided and matches an existing document's _id in the collection, the insertion will fail with an error. If the _id field is not provided, it will be automatically generated by the server, ensuring the document's uniqueness within the collection. This variant of the method allows for the explicit addition of a "$vector" property to the document, storing the provided embeddings.

      The embeddings should be a float array representing the vector to be associated with the document. This vector can be utilized by the database for operations that require vector space computations. An array containing only zero is not valid as it would lead to computation error with division by zero.

      Parameters:
      document - The document to be inserted. This can include or omit the _id field. If omitted, an _id will be automatically generated.
      embeddings - The vector embeddings to be associated with the document, expressed as an array of floats. This array populates the "$vector" property of the document, enabling vector-based operations.
      Returns:
      An InsertOneResult object that contains information about the result of the insertion, including the _id of the newly inserted document, whether it was explicitly provided or generated.

      Example usage:

       
 // Document without an explicit _id and embeddings for vector-based operations
 Document newDocument = new Document().append("name", "Jane Doe").append("age", 25);
 float[] embeddings = new float[]{0.12f, 0.34f, 0.56f, 0.78f};
 InsertOneResult result = collection.insertOne(newDocument, embeddings);
 System.out.println("Inserted document id: " + result.getInsertedId());

    • insertOneAsync

      public final CompletableFuture<InsertOneResult> insertOneAsync(T document, float[] embeddings)
      Asynchronously inserts a single document into the collection with vector embeddings. This method mirrors the functionality of insertOne(Object,float[]), operating asynchronously to return a CompletableFuture that completes with the insertion result. It is designed for use cases where non-blocking operations are essential, enabling other processes to continue while the document insertion is executed in the background.

      This method provides a convenient way to insert documents along with their associated vector embeddings without halting the execution of your application, making it particularly suitable for applications that require high levels of responsiveness or for operations where immediate confirmation of completion is not critical.

      For a comprehensive understanding of the behavior, parameters, including the purpose and use of vector embeddings, refer to the synchronous insertOne(Object,float[] embeddings) method. This asynchronous variant adopts all the behaviors and properties of its synchronous counterpart.

      Parameters:
      document - The document to be inserted, potentially without an _id field which, if omitted, will be automatically generated.
      embeddings - The vector embeddings associated with the document, intended to be used for advanced database operations such as similarity search.
      Returns:
      A CompletableFuture that, upon completion, contains the result of the insert operation as an InsertOneResult. This future may be completed with a successful result or an exception in case of insertion failure.

      Example usage:

       
 // Asynchronously inserting a document with embeddings
 Document newDocument = new Document().append("title", "Async Insert with Embeddings").append("content", "Content for embeddings");
 float[] embeddings = {0.1f, 0.2f, 0.3f};
 CompletableFuture<InsertOneResult> futureResult = collection.insertOneAsync(newDocument, embeddings);
 futureResult.thenAccept(result -> System.out.println("Inserted document id: " + result.getInsertedId()))
              .exceptionally(error -> { System.err.println("Insertion failed: " + error.getMessage()); return null; });

    • insertOne

      public final InsertOneResult insertOne(T document, String vectorize)
      Inserts a single document into the collection in an atomic operation, extending the base functionality of the insertOne(Object) method by adding the capability to compute and include a vector of embeddings directly within the document. This is achieved through a specified expression, which the service translates into vector embeddings. These embeddings can then be utilized for advanced database operations that leverage vector similarity.

      Note : This feature is under current development.

      Note: As with the base insertOne method, providing an _id field that matches an existing document's _id in the collection will cause the insertion to fail with an error. If the _id field is not present, it will be automatically generated, ensuring the document's uniqueness. This method variant introduces the ability to automatically compute embeddings based on the provided vectorize string, populating the "$vectorize" property of the document for later use in vector-based operations.

      The vectorize parameter should be a string that conveys meaningful information about the document, which will be converted into a vector representation by the database's embedding service. This functionality is especially useful for enabling semantic searches or clustering documents based on their content similarity.

      Parameters:
      document - The document to be inserted. It can optionally include the _id field. If omitted, an _id will be automatically generated.
      vectorize - The expression to be translated into a vector of embeddings. This string is processed by the service to generate vector embeddings that are stored in the document under the "$vectorize" property.
      Returns:
      An InsertOneResult object that contains information about the result of the insertion, including the _id of the newly inserted document, whether it was explicitly provided or generated.

      Example usage:

       
 // Document without an explicit _id and a string to be vectorized
 Document newDocument = new Document().append("title", "How to Use Vectorization");
 String vectorizeExpression = "This is a guide on vectorization.";
 InsertOneResult result = collection.insertOne(newDocument, vectorizeExpression);
 System.out.println("Inserted document id: " + result.getInsertedId());

    • insertOneAsync

      public final CompletableFuture<InsertOneResult> insertOneAsync(T document, String vectorize)
      Asynchronously inserts a single document into the collection with a vectorization expression. This method provides an asynchronous counterpart to insertOne(Object,String), allowing for non-blocking operations while a document, along with its vectorization based on the provided string, is inserted into the collection.

      Note : This feature is under current development.

      Utilizing this method facilitates the insertion of documents in scenarios where application responsiveness is crucial. It allows the application to continue with other tasks while the document insertion, including its vectorization, is processed in the background. This is particularly useful for operations that can benefit from parallel execution or when the insertion time is not critical to the application's flow.

      For detailed information on the behavior and parameters, especially the purpose and processing of the vectorize string, refer to the documentation of the synchronous insertOne(Object,String) method. This asynchronous method inherits all functionalities and behaviors from its synchronous counterpart, ensuring consistency across the API.

      Parameters:
      document - The document to be inserted into the collection. The requirements and options regarding the _id field and the document structure are identical to those described in the synchronous version.
      vectorize - The string expression that will be used to compute the vector embeddings. This parameter enables the automatic generation of embeddings to be associated with the document, enhancing its usefulness for vector-based operations within the database.
      Returns:
      A CompletableFuture that, when completed, provides the InsertOneResult indicating the outcome of the insert operation. The future may complete normally with the insertion result or exceptionally in case of an error.

      Example usage:

       
 // Asynchronously inserting a document with a vectorization expression
 Document newDocument = new Document().append("title", "Async Insert with Vectorization").append("description", "Description for vectorization");
 String vectorizationExpression = "Description for vectorization";
 CompletableFuture<InsertOneResult> futureResult = collection.insertOneAsync(newDocument, vectorizationExpression);
 futureResult.thenAccept(result -> System.out.println("Inserted document id: " + result.getInsertedId()))
              .exceptionally(error -> { System.err.println("Insertion failed: " + error.getMessage()); return null; });

    • insertMany

      public InsertManyResult insertMany(List<? extends T> documents, InsertManyOptions options)
      Inserts a batch of documents into the collection concurrently, optimizing the insertion process for large datasets. This method provides a powerful mechanism to insert multiple documents with customizable concurrency levels and batch sizes, while also ensuring error handling and performance optimization.

      Validation: The method validates the input documents list for nullity and emptiness. It also checks each document within the list to ensure none are null, throwing an IllegalArgumentException if these conditions are not met.

      Concurrency and Ordering: If concurrent insertion is requested with ordered inserts (via options), the method throws an IllegalArgumentException, as ordered operations cannot be performed concurrently.

      Chunk Size and Maximum Insertions: The method checks if the specified chunk size exceeds the maximum number of documents allowed for insertion in a single operation, throwing an IllegalArgumentException if this limit is breached.

      Documents are then split into chunks, each processed in parallel, according to the concurrency level specified in options. The results of these insertions are aggregated into a single InsertManyResult.

      Timeout Handling: The method attempts to complete all insertion tasks within the specified timeout. If tasks do not complete in time, a TimeoutException is thrown.

      Error Handling: Exceptions encountered during insertion or result aggregation are captured, and a RuntimeException is thrown, indicating an issue with merging results into a single InsertManyResult.

      Example usage: Inserting a list of 100 documents 

       
 InsertManyOptions options = InsertManyOptions.builder()
   .ordered(false)     // required for concurrent processing
   .withConcurrency(5) // recommended
   .withChunkSize(20)  // maximum chunk size is 20
   .withTimeout(100)   // global timeout
   .build();
 List<Document> documents = new ArrayList<>();
 for (int i = 0; i < 100; i++) {
     documents.add(new Document().append("key" + i, "value" + i));
 }
 InsertManyResult result = collection.insertMany(documents, options);
 System.out.println("Inserted document count: " + result.getInsertedIds().size());

      Performance Monitoring: Logs the total response time for the insert many operation, aiding in performance analysis and optimization efforts.

      Parameters:
      documents - A list of documents to be inserted. Must not be null or empty, and no document should be null.
      options - Detailed options for the insert many operation, including concurrency level, chunk size, and whether the inserts should be ordered.
      Returns:
      An InsertManyResult object containing the IDs of all successfully inserted documents.
      Throws:
      IllegalArgumentException - if the documents list is null or empty, any document is null, or if the options specified are invalid.
      RuntimeException - if there is an error in merging the results of concurrent insertions.

    • insertManyAsync

      public CompletableFuture<InsertManyResult> insertManyAsync(List<? extends T> documents, InsertManyOptions options)
      Asynchronously inserts a batch of documents into the collection with customizable insertion options. This method is the asynchronous counterpart to insertMany(List, InsertManyOptions), allowing for non-blocking operations. It employs default or specified InsertManyOptions to optimize the insertion process for large datasets, utilizing concurrency and batch processing to enhance performance.

      Utilizing CompletableFuture, this method facilitates the insertion of multiple documents without halting the execution of your application, making it well-suited for applications requiring high throughput or responsiveness. For scenarios necessitating specific insertion behaviors, such as concurrency levels and chunk sizes, the provided options parameter enables fine-tuned control over the asynchronous operation.

      This method inherits all the validation, chunking, and result aggregation logic from its synchronous counterpart, ensuring consistent behavior and error handling, while extending functionality to support asynchronous execution patterns.

      Usage: Recommended for inserting large numbers of documents or when the application's workflow benefits from non-blocking operations. For simpler use cases or default settings, the overload without options provides a more straightforward approach.

      Example usage: Asynchronously inserting a list of documents with custom options.

       
 List<Document> documents = new ArrayList<>();
 for (int i = 0; i < 100; i++) {
     documents.add(new Document().append("key" + i, "value" + i));
 }
 InsertManyOptions options = new InsertManyOptions().setConcurrency(5).setChunkSize(20);
 CompletableFuture<InsertManyResult> futureResult = collection.insertManyAsync(documents, options);
 futureResult.thenAccept(result -> System.out.println("Inserted document count: " + result.getInsertedIds().size()))
             .exceptionally(error -> { System.err.println("Insertion failed: " + error.getMessage()); return null; });
      Parameters:
      documents - A list of documents to be inserted. The list must not be null or empty, and no document should be null.
      options - Detailed options for the insert many operation, allowing customization of concurrency level, chunk size, and insertion order.
      Returns:
      A CompletableFuture that, upon completion, contains the InsertManyResult indicating the outcome of the insert operation. The future may complete normally with the insertion result or exceptionally in case of an error.
      Throws:
      IllegalArgumentException - if the documents list is null or empty, or if any document is null.

    • insertMany

      public InsertManyResult insertMany(List<? extends T> documents)
      Inserts a batch of documents into the collection using default insertion options. This method is a simplified version of insertMany(List, InsertManyOptions), intended for use cases where default settings for concurrency, chunk size, and insertion order are sufficient. It provides an efficient way to insert multiple documents concurrently, optimizing the insertion process with predefined settings.

      The default InsertManyOptions used by this method assumes non-concurrent (sequential) insertion, with no specific chunk size or timeout constraints. This is suitable for general use cases where the simplicity of invocation is prioritized over the customization of insertion parameters. For more advanced control over the insertion process, including the ability to specify concurrency levels, chunk sizes, and operation timeouts, use the overloaded insertMany(List, InsertManyOptions) method.

      This method leverages the same underlying insertion logic as its overloaded counterpart, ensuring consistent behavior and error handling. It automatically handles validation of the input documents list, chunking of documents based on default settings, and aggregation of insertion results into a single InsertManyResult.

      Usage: Ideal for inserting a collection of documents without the need for custom insertion options. Simplifies the insertion process for basic use cases.

      Parameters:
      documents - A list of documents to be inserted. Must not be null or empty, and no document should be null.
      Returns:
      An InsertManyResult object containing the IDs of all successfully inserted documents.
      Throws:
      IllegalArgumentException - if the documents list is null or empty, or if any document is null.
      RuntimeException - if there is an error in merging the results of concurrent insertions.

    • insertMany

      @SafeVarargs public final InsertManyResult insertMany(T... documents)
      Inserts a batch of documents into the collection using default insertion options. This method is a simplified version of insertMany(List, InsertManyOptions), intended for use cases where default settings for concurrency, chunk size, and insertion order are sufficient. It provides an efficient way to insert multiple documents concurrently, optimizing the insertion process with predefined settings.

      The default InsertManyOptions used by this method assumes non-concurrent (sequential) insertion, with no specific chunk size or timeout constraints. This is suitable for general use cases where the simplicity of invocation is prioritized over the customization of insertion parameters. For more advanced control over the insertion process, including the ability to specify concurrency levels, chunk sizes, and operation timeouts, use the overloaded insertMany(List, InsertManyOptions) method.

      This method leverages the same underlying insertion logic as its overloaded counterpart, ensuring consistent behavior and error handling. It automatically handles validation of the input documents list, chunking of documents based on default settings, and aggregation of insertion results into a single InsertManyResult.

      Usage: Ideal for inserting a collection of documents without the need for custom insertion options. Simplifies the insertion process for basic use cases.

      Parameters:
      documents - A list of documents to be inserted. Must not be null or empty, and no document should be null.
      Returns:
      An InsertManyResult object containing the IDs of all successfully inserted documents.
      Throws:
      IllegalArgumentException - if the documents list is null or empty, or if any document is null.
      RuntimeException - if there is an error in merging the results of concurrent insertions.

    • insertManyAsync

      public CompletableFuture<InsertManyResult> insertManyAsync(List<? extends T> documents)
      Asynchronously inserts a batch of documents into the collection using default insertion options. This method provides an asynchronous alternative to insertMany(List), facilitating non-blocking operations while employing a simplified insertion process suited for general use cases.

      Utilizing CompletableFuture, this method allows the insertion of multiple documents without interrupting the application's execution flow. It is particularly useful in scenarios requiring high throughput or when maintaining application responsiveness is critical. The default insertion settings are applied, simplifying the operation and making it accessible for basic insertion needs without the necessity for custom configuration.

      This method inherits the core logic and validations from its synchronous counterpart, ensuring consistent behavior and error handling. It automatically manages the input documents list, applying default options for chunking and concurrency, and aggregates the results into a single InsertManyResult asynchronously.

      Usage: Ideal for applications that benefit from asynchronous document insertion, especially when inserting a large number of documents under default settings. This method simplifies asynchronous batch insertions, making it straightforward to integrate into existing workflows.

      Example usage: Asynchronously inserting a list of 100 documents using default options.

       
 List<Document> documents = new ArrayList<>();
 for (int i = 0; i < 100; i++) {
     documents.add(new Document().append("key" + i, "value" + i));
 }
 CompletableFuture<InsertManyResult> futureResult = collection.insertManyAsync(documents);
 futureResult.thenAccept(result -> System.out.println("Inserted document count: " + result.getInsertedIds().size()))
             .exceptionally(error -> { System.err.println("Insertion failed: " + error.getMessage()); return null; });
      Parameters:
      documents - A list of documents to be inserted. Must not be null or empty, and no document within the list should be null.
      Returns:
      A CompletableFuture that, upon completion, contains the InsertManyResult indicating the outcome of the insert operation. The future may complete with the insertion results or exceptionally in case of an error.
      Throws:
      IllegalArgumentException - if the documents list is null or empty, or if any document is null.

    • findOne

      public Optional<T> findOne(Filter filter)
      Attempts to find a single document within the collection that matches the given filter criteria. This method efficiently locates the first document that fulfills the specified conditions, making it an optimal choice for queries where a unique identifier or specific characteristics are used to identify a document. Its efficiency stems from the ability to halt the search as soon as a matching document is found, potentially avoiding a full collection scan.

      Utilizing a Filter instance to articulate the search criteria, this method sifts through the collection to find a document that aligns with the provided conditions. The filter defines the parameters that a document must satisfy to be deemed a match, encompassing a wide range of possible attributes and values specific to the document structure and contents within the collection.

      In cases where the search does not yield a matching document, this method returns an empty Optional, signifying the absence of a compatible document. This design choice facilitates more graceful error handling, allowing callers to easily distinguish between the presence and absence of a match without resorting to exception handling for non-existent documents. Consequently, client code can implement more robust and cleaner retrieval logic by leveraging the Optional pattern.

      Example usage:

       
  // Given a collection
  DataApiCollection<Document> collection;
  // Assuming a Document in the collection with an id field
  Document doc = new Document().id(1).append("name", "John Doe");
  // To find the document with the id 1
  Optional<Document> foundDoc = collection.findOne(Filters.eq("_id", 1));
  foundDoc.ifPresent(System.out::println);
      Parameters:
      filter - The Filter instance encapsulating the search criteria used to pinpoint the desired document. This object specifies the exact conditions that must be met for a document to be selected as a match.
      Returns:
      An Optional encapsulating the found document, if any, that meets the filter criteria. If no document matches the specified conditions, an empty Optional is returned, ensuring that retrieval operations can be performed safely without the concern of NoSuchElementException.

    • findOne

      public Optional<T> findOne(Filter filter, FindOneOptions options)
      Attempts to find a single document within the collection that matches the given filter criteria. This method is designed to return the first document that satisfies the filter conditions, making it particularly useful for retrieving specific documents when unique identifiers or specific criteria are known. If no document matches the filter, the method will return an empty Optional, indicating the absence of a matching document. This approach avoids throwing exceptions for non-existent documents, thereby facilitating cleaner and more robust error handling in client code.

      Example usage:

       
  // Given a collection
  DataApiCollection<Document> collection;
  // Assuming a Document in the collection with an id field
  Document doc = new Document().id(1).append("name", "John Doe");
  // To find the document with the id 1
  FindOneOptions options2 = FindOneOptions.builder()
    .withIncludeSimilarity()     // return similarity in vector search
    .projections("_id", "name")  // return a subset of fields
    .build();
  Optional<Document> foundDoc = collection.findOne(Filters.eq("_id", 1), );
  foundDoc.ifPresent(System.out::println);
      Parameters:
      filter - The Filter instance containing the criteria used to identify the desired document. It specifies the conditions that a document must meet to be considered a match.
      options - The FindOneOptions instance containing additional options for the find operation,
      Returns:
      An Optional that contains the found document if one exists that matches the filter criteria. Returns an empty Optional if no matching document is found, enabling safe retrieval operations without the risk of NoSuchElementException.

    • findOneASync

      public CompletableFuture<Optional<T>> findOneASync(Filter filter)
      Initiates an asynchronous search to find a single document that matches the given filter criteria. This method leverages the functionality of to perform the search, but it does so asynchronously, returning a CompletableFuture. This approach allows the calling thread to remain responsive and perform other tasks while the search operation completes. The result of the operation is wrapped in a CompletableFuture that, upon completion, will contain an Optional instance. This instance either holds the document that matches the filter criteria or is empty if no such document exists.
      Parameters:
      filter - The Filter specifying the conditions that the document must meet to be considered a match. This parameter determines how the search is conducted and what criteria the document must satisfy to be retrieved.
      Returns:
      CompletableFuture that, when completed, will contain the result of the search operation. If a matching document is found, the Optional is non-empty; otherwise, it is empty to indicate the absence of a matching document. This future allows for non-blocking operations and facilitates the integration of asynchronous programming patterns.

    • findOneASync

      public CompletableFuture<Optional<T>> findOneASync(Filter filter, FindOneOptions options)
      Asynchronously attempts to find a single document within the collection that matches the given filter criteria, utilizing the specified FindOneOptions for the query. This method offers a non-blocking approach to querying the database, making it well-suited for applications requiring efficient I/O operations without compromising the responsiveness of the application.

      By executing the search operation in an asynchronous manner, this method allows other tasks to proceed concurrently, effectively utilizing system resources and improving application throughput. The query leverages a Filter instance to define the search criteria, and FindOneOptions to specify query customizations, such as projection or sort parameters.

      In cases where no document matches the filter, the method returns a CompletableFuture completed with an empty Optional, thus avoiding exceptions for non-existent documents. This behavior ensures a more graceful handling of such scenarios, allowing for cleaner and more robust client code by leveraging the Optional pattern within asynchronous workflows.

      Parameters:
      filter - The Filter instance encapsulating the criteria used to identify the desired document. It defines the conditions that a document must meet to be considered a match.
      options - The FindOneOptions providing additional query configurations such as projection and sort criteria to tailor the search operation.
      Returns:
      A CompletableFuture that, upon completion, contains an Optional with the found document if one exists matching the filter criteria. If no matching document is found, a completed future with an empty Optional is returned, facilitating safe asynchronous retrieval.

      Example usage:

       
 Filter filter = Filters.eq("id", 1);
 FindOneOptions options = FindOneOptions.builder().projection("name");
 CompletableFuture<Optional<Document>> futureDoc = collection.findOneASync(filter, options);
 futureDoc.thenAccept(doc -> doc.ifPresent(System.out::println));

    • findById

      public Optional<T> findById(Object id)
      Retrieves a document by its identifier from the collection.

      This method searches for a document with the specified id. If a matching document is found, it is returned wrapped in an Optional, otherwise, an empty Optional is returned. This approach provides a null-safe way to handle the presence or absence of a document.

      Parameters:
      id - The identifier of the document to find.
      Returns:
      An Optional containing the found document, or an empty Optional if no document matches the provided id.

    • findByIdASync

      public CompletableFuture<Optional<T>> findByIdASync(Object id)
      Asynchronously retrieves a document from the collection by its unique identifier. This method wraps the synchronous findById operation in a CompletableFuture, enabling non-blocking database queries that improve application responsiveness and efficiency. The method is ideal for applications that require the retrieval of specific documents without impacting the performance of the user interface or other concurrent operations.

      The unique identifier used to locate the document is typically the primary key or a unique field within the collection. This method abstracts the complexity of asynchronous programming, providing a straightforward way to execute and handle database queries within a non-blocking model.

      If the document with the specified identifier exists, it is wrapped in an Optional and returned within the completed future. Otherwise, the future is completed with an empty Optional, neatly handling cases where no matching document is found without throwing exceptions.

      Parameters:
      id - The unique identifier of the document to retrieve. This can be of any type that the database recognizes as a valid identifier format (e.g., String, Integer).
      Returns:
      A CompletableFuture that, upon completion, contains an Optional with the document if found. If no document matches the specified identifier, a completed future with an empty Optional is returned.

      Example usage:

       
 Object documentId = "uniqueDocumentId123";
 CompletableFuture<Optional<Document>> futureDocument = collection.findByIdASync(documentId);
 futureDocument.thenAccept(document -> document.ifPresent(System.out::println));

    • find

      public FindIterable<T> find(Filter filter, FindOptions options)
      Finds all documents in the collection.
      Parameters:
      filter - the query filter
      options - options of find one
      Returns:
      the find iterable interface

    • find

      public FindIterable<T> find()
      Retrieves all documents in the collection.

      This method returns an iterable interface that allows iterating over all documents in the collection, without applying any filters. It leverages the default FindOptions for query execution.

      Returns:
      A FindIterable for iterating over all documents in the collection.

    • find

      public FindIterable<T> find(Filter filter)
      Retrieves documents in the collection that match the specified filter.

      This method returns an iterable interface for documents that meet the criteria defined by the filter. It uses default FindOptions for query execution, allowing for customization of the query if needed.

      Parameters:
      filter - The query filter to apply when retrieving documents.
      Returns:
      A FindIterable for iterating over the documents that match the filter.

    • find

      public FindIterable<T> find(Filter filter, float[] vector, int limit)
      Finds documents in the collection that match the specified filter and sorts them based on their similarity to a provided vector, limiting the number of results returned.

      This method is particularly useful for vector-based search operations where documents are ranked according to their distance from a reference vector. The limit parameter controls the maximum number of documents to return, allowing for efficient retrieval of the most relevant documents.

      Parameters:
      filter - The query filter to apply when retrieving documents.
      vector - A float array representing the vector used to sort the documents.
      limit - The maximum number of documents to return.
      Returns:
      A FindIterable for iterating over the sorted and limited documents.

    • find

      public FindIterable<T> find(float[] vector, int limit)
      Finds documents in the collection that match the specified filter and sorts them based on their similarity to a provided vector, limiting the number of results returned.

      This method is particularly useful for vector-based search operations where documents are ranked according to their distance from a reference vector. The limit parameter controls the maximum number of documents to return, allowing for efficient retrieval of the most relevant documents.

      Parameters:
      vector - A float array representing the vector used to sort the documents.
      limit - The maximum number of documents to return.
      Returns:
      A FindIterable for iterating over the sorted and limited documents.

    • find

      public FindIterable<T> find(Filter filter, String vectorize, int limit)
      Finds documents in the collection that match the specified filter and sorts them based on their similarity to a provided vector, limiting the number of results returned.

      Note : This feature is under current development.

      This method leverage the 'vectorization' to compute the embeddings on the fly in order to execute the search.

      Parameters:
      filter - The query filter to apply when retrieving documents.
      vectorize - A float array representing the vector used to sort the documents.
      limit - The maximum number of documents to return.
      Returns:
      A FindIterable for iterating over the sorted and limited documents.

    • find

      public FindIterable<T> find(FindOptions options)
      Finds all documents in the collection, applying the specified find options.

      This method allows for detailed control over the query execution through FindOptions, which can specify sorting, projection, limits, and other query parameters. If no filter is applied, all documents in the collection are considered.

      Parameters:
      options - The FindOptions to apply when executing the find operation.
      Returns:
      A FindIterable for iterating over the documents according to the specified options.

    • findPage

      public Page<T> findPage(Filter filter, FindOptions options)
      Executes a paginated 'find' query on the collection using the specified filter and find options.

      This method constructs and executes a command to fetch a specific page of documents from the collection that match the provided filter criteria. It allows for detailed control over the query through FindOptions, such as sorting, projection, pagination, and more. The result is wrapped in a Page object, which includes the documents found, the page size, and the state for fetching subsequent pages.

      Pagination is facilitated by the skip, limit, and pageState parameters within FindOptions, enabling efficient data retrieval in scenarios where the total dataset is too large to be fetched in a single request. Optionally, similarity scoring can be included if includeSimilarity is set, which is useful for vector-based search queries.

      The method processes the command's response, mapping each document to the specified document class and collecting them into a list. This list, along with the maximum page size and the next page state, is used to construct the Page object returned by the method.

      Parameters:
      filter - The filter criteria used to select documents from the collection.
      options - The FindOptions providing additional query parameters, such as sorting and pagination.
      Returns:
      A Page object containing the documents that match the query, along with pagination information.

    • findPageASync

      public CompletableFuture<Page<T>> findPageASync(Filter filter, FindOptions options)
      Executes a paginated 'find' query on the collection using the specified filter and find options asynchronously.

      This method constructs and executes a command to fetch a specific page of documents from the collection that match the provided filter criteria. It allows for detailed control over the query through FindOptions, such as sorting, projection, pagination, and more. The result is wrapped in a Page object, which includes the documents found, the page size, and the state for fetching subsequent pages.

      Pagination is facilitated by the skip, limit, and pageState parameters within FindOptions, enabling efficient data retrieval in scenarios where the total dataset is too large to be fetched in a single request. Optionally, similarity scoring can be included if includeSimilarity is set, which is useful for vector-based search queries.

      The method processes the command's response, mapping each document to the specified document class and collecting them into a list. This list, along with the maximum page size and the next page state, is used to construct the Page object returned by the method.

      Parameters:
      filter - The filter criteria used to select documents from the collection.
      options - The FindOptions providing additional query parameters, such as sorting and pagination.
      Returns:
      A Page object containing the documents that match the query, along with pagination information.

    • distinct

      public <F> DistinctIterable<T,F> distinct(String fieldName, Class<F> resultClass)
      Gets the distinct values of the specified field name. The iteration is performed at CLIENT-SIDE and will exhaust all the collections elements.
      Type Parameters:
      F - the target type of the iterable.
      Parameters:
      fieldName - the field name
      resultClass - the class to cast any distinct items into.
      Returns:
      an iterable of distinct values

    • distinct

      public <F> DistinctIterable<T,F> distinct(String fieldName, Filter filter, Class<F> resultClass)
      Gets the distinct values of the specified field name.
      Type Parameters:
      F - the target type of the iterable.
      Parameters:
      fieldName - the field name
      filter - the query filter
      resultClass - the class to cast any distinct items into.
      Returns:
      an iterable of distinct values

    • countDocuments

      public int countDocuments(int upperBound) throws TooManyDocumentsToCountException
      Counts the number of documents in the collection.

      Takes in a `upperBound` option which dictates the maximum number of documents that may be present before a TooManyDocumentsToCountException is thrown. If the limit is higher than the highest limit accepted by the Data API, a TooManyDocumentsToCountException will be thrown anyway (i.e. `1000`).

      Count operations are expensive: for this reason, the best practice is to provide a reasonable `upperBound` according to the caller expectations. Moreover, indiscriminate usage of count operations for sizeable amounts of documents (i.e. in the thousands and more) is discouraged in favor of alternative application-specific solutions. Keep in mind that the Data API has a hard upper limit on the amount of documents it will count, and that an exception will be thrown by this method if this limit is encountered.

      Parameters:
      upperBound - The maximum number of documents to count.
      Returns:
      The number of documents in the collection.
      Throws:
      TooManyDocumentsToCountException - If the number of documents counted exceeds the provided limit.

    • estimatedDocumentCount

      public long estimatedDocumentCount()
      Executes the "estimatedDocumentCount" command to estimate the number of documents in a collection.

      This method sends a command to estimate the document count and parses the count from the command's response. It handles the execution of the command and the extraction of the document count from the response.

      Returns:
      the estimated number of documents in the collection.
      Throws:
      IllegalStateException - if the command response does not contain the expected result count.

    • countDocuments

      public int countDocuments(Filter filter, int upperBound) throws TooManyDocumentsToCountException
      Counts the number of documents in the collection with a filter.

      Takes in a `upperBound` option which dictates the maximum number of documents that may be present before a TooManyDocumentsToCountException is thrown. If the limit is higher than the highest limit accepted by the Data API, a TooManyDocumentsToCountException will be thrown anyway (i.e. `1000`).

      Count operations are expensive: for this reason, the best practice is to provide a reasonable `upperBound` according to the caller expectations. Moreover, indiscriminate usage of count operations for sizeable amounts of documents (i.e. in the thousands and more) is discouraged in favor of alternative application-specific solutions. Keep in mind that the Data API has a hard upper limit on the amount of documents it will count, and that an exception will be thrown by this method if this limit is encountered.

      Parameters:
      filter - A filter to select the documents to count. If not provided, all documents will be counted.
      upperBound - The maximum number of documents to count.
      Returns:
      The number of documents in the collection.
      Throws:
      TooManyDocumentsToCountException - If the number of documents counted exceeds the provided limit.

    • deleteOne

      public DeleteResult deleteOne(Filter filter)
      Removes at most one document from the collection that matches the given filter. If no documents match, the collection is not modified.
      Parameters:
      filter - the query filter to apply the delete operation
      Returns:
      the result of the remove one operation

    • deleteOne

      public DeleteResult deleteOne(Filter filter, DeleteOneOptions deleteOneOptions)
      Removes at most one document from the collection that matches the given filter. If no documents match, the collection is not modified.
      Parameters:
      filter - the query filter to apply the delete operation
      deleteOneOptions - the option to driver the deletes (here sort)
      Returns:
      the result of the remove one operation

    • deleteMany

      public DeleteResult deleteMany(Filter filter)
      Removes all documents from the collection that match the given query filter. If no documents match, the collection is not modified.
      Parameters:
      filter - the query filter to apply the delete operation
      Returns:
      the result of the remove many operation

    • deleteAll

      public DeleteResult deleteAll()
      Removes all documents from the collection that match the given query filter. If no documents match, the collection is not modified.
      Returns:
      the result of the remove many operation

    • exists

      public boolean exists()
      Checks if the specified collection exists within the current namespace.

      This method delegates the existence check to the existCollection method of the associated namespace, evaluates the existence based on the collection's name, as retrieved by getName().

      Returns:
      true if the collection exists within the namespace, false otherwise.

    • drop

      public void drop()
      Delete the current collection and all documents that its contains.

    • findOneAndReplace

      public Optional<T> findOneAndReplace(Filter filter, T replacement)
      Atomically find a document and replace it.
      Parameters:
      filter - the query filter to apply the replace operation
      replacement - the replacement document
      Returns:
      the document that was replaced. Depending on the value of the returnOriginal property, this will either be the document as it was before the update or as it is after the update. If no documents matched the query filter, then null will be returned

    • findOneAndReplace

      public Optional<T> findOneAndReplace(Filter filter, T replacement, FindOneAndReplaceOptions options)
      Atomically find a document and replace it.

      Note: Supports retryable writes on MongoDB server versions 3.6 or higher when the retryWrites setting is enabled.

      Parameters:
      filter - the query filter to apply the replace operation
      replacement - the replacement document
      options - the options to apply to the operation
      Returns:
      the document that was replaced. Depending on the value of the returnOriginal property, this will either be the document as it was before the update or as it is after the update. If no documents matched the query filter, then null will be returned

    • replaceOne

      public UpdateResult replaceOne(Filter filter, T replacement)
      Replace a single document on the collection with a new one, optionally inserting a new document if no match is found.
      Parameters:
      filter - the query filter to apply the replace operation
      replacement - the replacement document
      Returns:
      result of the replace one operation

    • replaceOne

      public UpdateResult replaceOne(Filter filter, T replacement, ReplaceOneOptions replaceOneOptions)
      Replace a document in the collection according to the specified arguments.
      Parameters:
      filter - the query filter to apply the replace operation
      replacement - the replacement document
      replaceOneOptions - the options to apply to the replace operation
      Returns:
      the result of the replace one operation

    • findOneAndUpdate

      public Optional<T> findOneAndUpdate(Filter filter, Update update)
      Atomically find a document and update it.

      Note: Supports retryable writes on MongoDB server versions 3.6 or higher when the retryWrites setting is enabled.

      Parameters:
      filter - a document describing the query filter, which may not be null.
      update - a document describing the update, which may not be null. The update to apply must include at least one update operator.
      Returns:
      the document that was updated before the update was applied. If no documents matched the query filter, then null will be returned

    • findOneAndUpdate

      public Optional<T> findOneAndUpdate(Filter filter, Update update, FindOneAndUpdateOptions options)
      Atomically find a document and update it.
      Parameters:
      filter - a document describing the query filter, which may not be null.
      update - a document describing the update, which may not be null. The update to apply must include at least one update operator.
      options - the options to apply to the operation
      Returns:
      the document that was updated. Depending on the value of the returnOriginal property, this will either be the document as it was before the update or as it is after the update. If no documents matched the query filter, then null will be returned

    • updateOne

      public UpdateResult updateOne(Filter filter, Update update)
      Update a single document in the collection according to the specified arguments.
      Parameters:
      filter - a document describing the query filter, which may not be null.
      update - a document describing the update, which may not be null. The update to apply must include at least one update operator.
      Returns:
      the result of the update one operation

    • updateOne

      public UpdateResult updateOne(Filter filter, Update update, UpdateOneOptions updateOptions)
      Update a single document in the collection according to the specified arguments.
      Parameters:
      filter - a document describing the query filter, which may not be null.
      update - a document describing the update, which may not be null. The update to apply must include at least one update operator.
      updateOptions - the options to apply to the update operation
      Returns:
      the result of the update one operation

    • updateMany

      public UpdateResult updateMany(Filter filter, Update update)
      Update all documents in the collection according to the specified arguments.
      Parameters:
      filter - a document describing the query filter, which may not be null.
      update - a document describing the update, which may not be null. The update to apply must include only update operators.
      Returns:
      the result of the update many operation

    • updateMany

      public UpdateResult updateMany(Filter filter, Update update, UpdateManyOptions options)
      Update all documents in the collection according to the specified arguments.
      Parameters:
      filter - a document describing the query filter, which may not be null.
      update - a document describing the update, which may not be null. The update to apply must include only update operators.
      options - the options to apply to the update operation
      Returns:
      the result of the update many operation

    • findOneAndDelete

      public Optional<T> findOneAndDelete(Filter filter)
      Atomically find a document and remove it.
      Parameters:
      filter - the query filter to find the document with
      Returns:
      the document that was removed. If no documents matched the query filter, then null will be returned

    • findOneAndDeleteAsync

      public CompletableFuture<Optional<T>> findOneAndDeleteAsync(Filter filter)
      Delete and return a document asynchronous.
      Parameters:
      filter - filter to delete
      Returns:
      the document that was removed. If no documents matched the query filter, then null will be returned

    • findOneAndDelete

      public Optional<T> findOneAndDelete(Filter filter, FindOneAndDeleteOptions options)
      Atomically find a document and remove it.
      Parameters:
      filter - the query filter to find the document with
      options - the options to apply to the operation
      Returns:
      the document that was removed. If no documents matched the query filter, then null will be returned

    • bulkWrite

      public BulkWriteResult bulkWrite(List<Command> commands)
      Executes a mix of inserts, updates, replaces, and deletes.
      Parameters:
      commands - list of commands to run
      Returns:
      the result of the bulk write

    • bulkWrite

      public BulkWriteResult bulkWrite(List<Command> commands, BulkWriteOptions options)
      Executes a mix of inserts, updates, replaces, and deletes.
      Parameters:
      commands - list of commands to run
      options - if requests must be ordered or not
      Returns:
      the result of the bulk write

    • enableLogging

      public Collection<T> enableLogging()
      Register the logging listener to the collection.
      Returns:
      self reference

    • getApiEndpoint

      protected String getApiEndpoint()
      The subclass should provide the endpoint, url to post request.
      Specified by:
      getApiEndpoint in class AbstractCommandRunner
      Returns:
      url on which to post the request

    • getToken

      protected String getToken()
      Authentication token provided by subclass.
      Specified by:
      getToken in class AbstractCommandRunner
      Returns:
      authentication token

    • getHttpClientOptions

      protected DataAPIOptions.HttpClientOptions getHttpClientOptions()
      Options to initialize the HTTP client.
      Specified by:
      getHttpClientOptions in class AbstractCommandRunner
      Returns:
      options for the http client.