update with HDC

Author: clun

README.MD

@@ -24,6 +24,27 @@ This client library provides a simplified way to interact with Data API for Astr
 This library is under development and is available in Maven Central.
 You can build it locally and install it in your local repository.
 
+## 📋 Table Of Content
+
+1. Installation
+   1. Prerequisites
+   2. Packaging
+2. QuickStart with Astra DB
+   1. Sign up for Astra DB
+   2. Create a Database
+   3. Get your credentials
+   4. Create a new project and add the dependency
+3. QuickStart with DSE
+    1. Start Data Api.
+    2. Connection to DSE
+    3. Create a namespace
+    4. Create a collection
+4. QuickStart with HCD
+    1. Start Data Api.
+    2. Connection to HCD
+    3. Create a namespace
+    4. Create a collection
+
 ## 1. Installation
 
 ### 1.1 Prerequisites

astra-db-java/src/main/java/com/datastax/astra/client/Collection.java

@@ -90,6 +90,7 @@
 
 import static com.datastax.astra.client.exception.DataApiException.ERROR_CODE_INTERRUPTED;
 import static com.datastax.astra.client.exception.DataApiException.ERROR_CODE_TIMEOUT;
+import static com.datastax.astra.client.model.DataAPIKeywords.SORT_VECTOR;
 import static com.datastax.astra.internal.utils.AnsiUtils.cyan;
 import static com.datastax.astra.internal.utils.AnsiUtils.green;
 import static com.datastax.astra.internal.utils.AnsiUtils.magenta;
@@ -174,6 +175,8 @@ public class Collection<T> extends AbstractCommandRunner {
     /** json inputs */
     public static final String INPUT_INCLUDE_SIMILARITY = "includeSimilarity";
     /** json inputs */
+    public static final String INPUT_INCLUDE_SORT_VECTOR = "includeSortVector";
+    /** json inputs */
     private static final String INPUT_UPSERT = "upsert";
     /** json inputs */
     private static final String INPUT_RETURN_DOCUMENT = "returnDocument";
@@ -1216,7 +1219,10 @@ public Optional<T> findOne(Filter filter, FindOneOptions findOneOptions) {
                 .withFilter(filter)
                 .withSort(findOneOptions.getSort())
                 .withProjection(findOneOptions.getProjection())
-                .withOptions(new Document().appendIfNotNull(INPUT_INCLUDE_SIMILARITY, findOneOptions.getIncludeSimilarity()));
+                .withOptions(new Document()
+                  .appendIfNotNull(INPUT_INCLUDE_SIMILARITY, findOneOptions.getIncludeSimilarity())
+                  .appendIfNotNull(INPUT_INCLUDE_SORT_VECTOR, findOneOptions.getIncludeSortVector())
+                );
 
         return Optional.ofNullable(
                 runCommand(findOne, findOneOptions)
@@ -1452,14 +1458,24 @@ public Page<T> findPage(Filter filter, FindOptions options) {
                         .appendIfNotNull("skip", options.getSkip())
                         .appendIfNotNull("limit", options.getLimit())
                         .appendIfNotNull(INPUT_PAGE_STATE, options.getPageState())
+                        .appendIfNotNull(INPUT_INCLUDE_SORT_VECTOR, options.getIncludeSortVector())
                         .appendIfNotNull(INPUT_INCLUDE_SIMILARITY, options.getIncludeSimilarity()));
         ApiResponse apiResponse = runCommand(findCommand, options);
+
+        // load sortVector if available
+        float[] sortVector = null;
+        if (options.getIncludeSortVector() &&
+                apiResponse.getStatus() != null &&
+                apiResponse.getStatus().get(SORT_VECTOR.getKeyword()) != null) {
+            sortVector = apiResponse.getStatus().get(SORT_VECTOR.getKeyword(), float[].class);
+        }
+
         return new Page<>(
                 apiResponse.getData().getNextPageState(),
                 apiResponse.getData().getDocuments()
                         .stream()
                         .map(d -> d.map(getDocumentClass()))
-                        .collect(Collectors.toList()));
+                        .collect(Collectors.toList()), sortVector);
     }
 
     /**
@@ -1703,7 +1719,6 @@ public DeleteResult deleteOne(Filter filter, DeleteOneOptions deleteOneOptions)
      *      the result of the remove many operation
      */
     public DeleteResult deleteMany(Filter filter, DeleteManyOptions options) {
-        Assert.notNull(filter, ARG_FILTER);
         AtomicInteger totalCount = new AtomicInteger(0);
         boolean moreData = false;
         do {
@@ -2153,6 +2168,7 @@ public Optional<T> findOneAndDelete(Filter filter, FindOneAndDeleteOptions optio
      * @return
      *      the result of the bulk write
      */
+    @Deprecated(since = "1.3.0", forRemoval = true)
     public BulkWriteResult bulkWrite(List<Command> commands) {
         return bulkWrite(commands, new BulkWriteOptions());
     }
@@ -2167,6 +2183,7 @@ public BulkWriteResult bulkWrite(List<Command> commands) {
      * @return
      *      the result of the bulk write
      */
+    @Deprecated(since = "1.3.0", forRemoval = true)
     public BulkWriteResult bulkWrite(List<Command> commands, BulkWriteOptions options) {
         notNull(commands, ARG_COMMANDS);
         notNull(options, ARG_OPTIONS);

astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClients.java

@@ -21,7 +21,7 @@
  */
 
 import com.datastax.astra.client.admin.DataAPIDatabaseAdmin;
-import com.datastax.astra.internal.auth.TokenProviderStargateV2;
+import com.datastax.astra.internal.auth.UsernamePasswordTokenProvider;
 import com.datastax.astra.internal.command.LoggingCommandObserver;
 
 import static com.datastax.astra.client.admin.AstraDBAdmin.DEFAULT_NAMESPACE;
@@ -75,7 +75,7 @@ private DataAPIClients() {}
      */
     public static DataAPIClient createForLocal() {
         return new DataAPIClient(
-                new TokenProviderStargateV2().getToken(),
+                new UsernamePasswordTokenProvider().getToken(),
                 DataAPIOptions.builder()
                         .withDestination(DataAPIOptions.DataAPIDestination.CASSANDRA)
                         .withObserver(new LoggingCommandObserver(DataAPIClient.class))

astra-db-java/src/main/java/com/datastax/astra/client/DataAPIOptions.java

@@ -155,6 +155,11 @@ public enum DataAPIDestination {
          */
         DSE,
 
+        /**
+         * Hyper Converged Database
+         */
+        HCD,
+
         /**
          * Local installation of Apache Cassandra
          */

astra-db-java/src/main/java/com/datastax/astra/client/admin/DatabaseAdmin.java

@@ -96,6 +96,7 @@ public interface DatabaseAdmin {
      * }
      * </pre>
      * @return
+     *      list of available providers
      */
     Map<String, EmbeddingProvider> listEmbeddingProviders();
 

astra-db-java/src/main/java/com/datastax/astra/client/model/DataAPIKeywords.java

@@ -94,6 +94,11 @@ public enum DataAPIKeywords {
      */
     VECTOR("$vector"),
 
+    /**
+     * SORT VECTOR.
+     */
+    SORT_VECTOR("sortVector"),
+
     /**
      * VECTORIZE.
      */

astra-db-java/src/main/java/com/datastax/astra/client/model/FindIterable.java

@@ -27,6 +27,7 @@
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Optional;
 
 /**
  * Represents the result of a 'find' command executed on a collection, providing an iterable interface to navigate
@@ -89,11 +90,10 @@ public FindIterator<T> iterator() {
      *      all values of the iterable
      */
      public List<T> all() {
-         if (exhausted) throw new IllegalStateException("Iterable is already exhauted.");
+         if (exhausted) throw new IllegalStateException("Iterable is already exhausted.");
          if (active)    throw new IllegalStateException("Iterable has already been started");
          List<T> results = new ArrayList<>();
          for (T t : this) results.add(t);
          return results;
      }
-
 }

astra-db-java/src/main/java/com/datastax/astra/client/model/FindIterator.java

@@ -104,6 +104,6 @@ public T next() {
      * @since 4.4
      */
     public int available() {
-        return 0;
+        return availableWithoutFetch;
     }
 }

astra-db-java/src/main/java/com/datastax/astra/client/model/FindOneAndDeleteOptions.java

@@ -50,6 +50,10 @@ public FindOneAndDeleteOptions() {
         // left blank as sort is populated in static way
     }
 
+    // ----------------
+    // ---- Sort ------
+    // ----------------
+
     /**
      * Syntax sugar as delete option is only a sort
      *
@@ -59,24 +63,51 @@ public FindOneAndDeleteOptions() {
      *      current command.
      */
     public FindOneAndDeleteOptions sort(Sort... sort) {
-        setSort(OptionsUtils.sort(sort));
+        return sort(OptionsUtils.sort(sort));
+    }
+
+    /**
+     * Syntax sugar as delete option is only a sort
+     * Could be like Map.of("$vectorize", "command, "field1", 1, "field2", -1);
+     *
+     * @param rawSort
+     *      raw sort clause
+     * @return
+     *      current command.
+     */
+    public FindOneAndDeleteOptions sort(Map<String, Object> rawSort) {
+        Document doc = new Document();
+        doc.putAll(rawSort);
+        return sort(doc);
+    }
+
+    /**
+     * Syntax sugar as delete option is only a sort
+     * Could be like Map.of("$vectorize", "command, "field1", 1, "field2", -1);
+     *
+     * @param sorClause
+     *      sort clause as a document
+     * @return
+     *      current command.
+     */
+    public FindOneAndDeleteOptions sort(Document sorClause) {
+        setSort(sorClause);
         return this;
     }
 
     /**
      * Add a criteria with $vectorize in the sort clause.
-     * <p><i style='color: orange;'><b>Note</b> : This feature is under current development.</i></p>
      *
      * @param vectorize an expression to look for vectorization
      * @param sorts The sort criteria to be applied to the findOne operation.
      * @return current command
      */
     public FindOneAndDeleteOptions sort(String vectorize, Sort ... sorts) {
-        setSort(Sorts.vectorize(vectorize));
+        Document doc = Sorts.vectorize(vectorize);
         if (sorts != null) {
-            getSort().putAll(OptionsUtils.sort(sorts));
+            doc.putAll(OptionsUtils.sort(sorts));
         }
-        return this;
+        return sort(doc);
     }
 
     /**
@@ -87,13 +118,17 @@ public FindOneAndDeleteOptions sort(String vectorize, Sort ... sorts) {
      * @return current command
      */
     public FindOneAndDeleteOptions sort(float[] vector, Sort... sorts) {
-        setSort(Sorts.vector(vector));
+        Document doc = Sorts.vector(vector);
         if (sorts != null) {
-            getSort().putAll(OptionsUtils.sort(sorts));
+            doc.putAll(OptionsUtils.sort(sorts));
         }
-        return this;
+        return sort(doc);
     }
 
+    // ----------------------
+    // ---- Projection ------
+    // ----------------------
+
     /**
      * Syntax sugar as delete option is only a sort
      *
@@ -107,59 +142,6 @@ public FindOneAndDeleteOptions projection(Projection... projection) {
         return this;
     }
 
-    /**
-     * Builder for creating {@link FindOneAndDeleteOptions} instances with a fluent API.
-     */
-    public static class Builder {
-
-        /**
-         * Hide constructor.
-         */
-        private Builder() {
-        }
-
-        /**
-         * Initializes the building process with sorting options.
-         *
-         * @param sort The sort criteria to be applied to the delete operation.
-         * @return A new {@link FindOneAndDeleteOptions} instance configured with the provided sort criteria.
-         */
-        public static FindOneAndDeleteOptions sort(Sort... sort) {
-            return new FindOneAndDeleteOptions().sort(sort);
-        }
-
-        /**
-         * Initializes the building process with projection options.
-         *
-         * @param projection The projection criteria to be applied to the delete operation.
-         * @return A new {@link FindOneAndDeleteOptions} instance configured with the provided projection criteria.
-         */
-        public static FindOneAndDeleteOptions projection(Projection... projection) {
-            return new FindOneAndDeleteOptions().projection(projection);
-        }
-
-        /**
-         * Initializes the building process with vectorize options.
-         * <p><i style='color: orange;'><b>Note</b> : This feature is under current development.</i></p>
-         *
-         * @param vectorize The vectorize criteria to be applied to the findOne operation
-         * @param sorts The sort criteria to be applied to the findOne operation.
-         * @return A new {@link FindOneAndDeleteOptions} instance configured with the provided vectorize criteria.
-         */
-        public static FindOneAndDeleteOptions sort(String vectorize, Sort... sorts) {
-            return new FindOneAndDeleteOptions().sort(vectorize, sorts);
-        }
 
-        /**
-         * Initializes the building process with vector options.
-         *
-         * @param vector The vector criteria to be applied to the findOne operation
-         * @param sorts The sort criteria to be applied to the findOne operation.
-         * @return A new {@link FindOneAndDeleteOptions} instance configured with the provided vector criteria.
-         */
-        public static FindOneAndDeleteOptions sort(float[] vector, Sort... sorts) {
-            return new FindOneAndDeleteOptions().sort(vector, sorts);
-        }
-    }
 
 }