Slice and estimatedCount

Author: clun

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

@@ -1310,6 +1310,32 @@ public Page<T> findPage(Filter filter, FindOptions options) {
                         .collect(Collectors.toList()));
     }
 
+    /**
+     * Executes a paginated 'find' query on the collection using the specified filter and find options asynchronously.
+     * <p>
+     * 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 {@code FindOptions}, such as sorting,
+     * projection, pagination, and more. The result is wrapped in a {@link Page} object, which includes the documents found,
+     * the page size, and the state for fetching subsequent pages.
+     * </p>
+     * <p>
+     * Pagination is facilitated by the {@code skip}, {@code limit}, and {@code pageState} parameters within {@code 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 {@code includeSimilarity} is set, which is useful for vector-based search queries.
+     * </p>
+     * <p>
+     * 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 {@link Page} object returned by the method.
+     * </p>
+     *
+     * @param filter The filter criteria used to select documents from the collection.
+     * @param options The {@link FindOptions} providing additional query parameters, such as sorting and pagination.
+     * @return A {@link Page} object containing the documents that match the query, along with pagination information.
+     */
+    public CompletableFuture<Page<T>> findPageASync(Filter filter, FindOptions options) {
+        return CompletableFuture.supplyAsync(() -> findPage(filter, options));
+    }
+
     // --------------------------
     // ---   Distinct        ----
     // --------------------------
@@ -1380,6 +1406,25 @@ public int countDocuments(int upperBound) throws TooManyDocumentsToCountExceptio
         return countDocuments(null, upperBound);
     }
 
+    /**
+     * Executes the "estimatedDocumentCount" command to estimate the number of documents
+     * in a collection.
+     * <p>
+     * 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.
+     * </p>
+     * @return the estimated number of documents in the collection.
+     * @throws IllegalStateException if the command response does not contain the expected result count.
+     */
+    public long estimatedDocumentCount() {
+        Command command = new Command("estimatedDocumentCount");
+        // Run command
+        ApiResponse response = runCommand(command);
+        // Build Result
+        return response.getStatus().getInteger(RESULT_COUNT);
+    }
+
     /**
      * Counts the number of documents in the collection with a filter.
      *

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

@@ -111,7 +111,7 @@ public Command withReplacement(Object replacement) {
      * @return
      *      self-reference
      */
-    public Command withProjection(Map<String, Integer> projection) {
+    public Command withProjection(Map<String, Object> projection) {
         payload.appendIfNotNull("projection", projection);
         return this;
     }

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

@@ -79,6 +79,11 @@ public enum DataAPIKeywords {
      */
     EXISTS("$exists"),
 
+    /**
+     * SIMILARITY.
+     */
+    SLICE("$slice"),
+
     /**
      * SIMILARITY.
      */

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

@@ -41,7 +41,7 @@ public class FindOneAndDeleteOptions {
     /**
      * Select.
      */
-    private Map<String, Integer> projection;
+    private Map<String, Object> projection;
 
     /**
      * Default constructor.

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

@@ -42,7 +42,7 @@ public class FindOneAndReplaceOptions {
     /**
      * Options to project (select) the result.
      */
-    private Map<String, Integer> projection;
+    private Map<String, Object> projection;
 
     /**
      * Flag to enforce the replacement

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

@@ -43,7 +43,7 @@ public class FindOneAndUpdateOptions {
     /**
      * Select.
      */
-    private Map<String, Integer> projection;
+    private Map<String, Object> projection;
 
     /**
      * Upsert flag.

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

@@ -41,7 +41,7 @@ public class FindOneOptions {
     /**
      * Select.
      */
-    private Map<String, Integer> projection;
+    private Map<String, Object> projection;
 
     /**
      * Options.

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

@@ -41,7 +41,7 @@ public class FindOptions {
     /**
      * Projection for return document (select)
      */
-    private Map<String, Integer> projection;
+    private Map<String, Object> projection;
 
     /**
      * Skip a few result in the beginning

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

@@ -33,17 +33,42 @@ public class Projection {
     private final String field;
 
     /** Is the field present in the result. */
-    private final boolean present;
+    private final Boolean present;
+
+    /** Mutually exclusive with 'present', provide a slice */
+    private final Integer sliceStart;
+
+    /** Mutually exclusive with 'present', provide a slice end */
+    private final Integer sliceEnd;
 
     /**
      * Default constructor.
+     *
      * @param field
      *      field value
      * @param present
      *      tell if field is present
      */
     public Projection(String field, boolean present) {
-        this.field = field;
-        this.present = present;
+        this(field, present, null, null);
+    }
+
+    /**
+     * Default constructor.
+     *
+     * @param field
+     *      field value
+     * @param present
+     *      tell if field is present
+     * @param sliceStart
+     *     start of slice (mutually exclusive with 'present')
+     * @param sliceEnd
+     *     end of slice (mutually exclusive with 'present'), optional
+     */
+    public Projection(String field, Boolean present, Integer sliceStart, Integer sliceEnd) {
+        this.field      = field;
+        this.present    = present;
+        this.sliceStart = sliceStart;
+        this.sliceEnd   = sliceEnd;
     }
 }

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

@@ -42,10 +42,41 @@ private Projections() {}
      */
     public static Projection[] include(String... field) {
         return Arrays.stream(field)
-                .map(f -> new Projection(f, true))
+                .map(f -> new Projection(f, true, null, null))
                 .toArray(Projection[]::new);
     }
 
+    /**
+     * Specifies the number of elements in an array to return in the query result.
+     * <pre>
+     * {@code
+     * // Return the first two elements
+     * { $slice: 2 }
+     *
+     * // Return the last two elements
+     * { $slice: -2 }
+     *
+     * // Skip 4 elements (from 0th index), return the next 2
+     * { $slice: [4, 2] }
+     *
+     * // Skip backward 4 elements, return next 2 elements (forward)
+     * { $slice: [-4, 2] }
+     * }
+     * </pre>
+     *
+     * @param field
+     *      field name for slice
+     * @param start
+     *      start index of slice
+     * @param end
+     *     end index of slice
+     * @return
+     *      a projection for the slide
+     */
+    public static Projection slice(String field, Integer start, Integer end) {
+        return new Projection(field, null, start, end);
+    }
+
     /**
      * Exclude  a field in the result.
      *
@@ -56,7 +87,7 @@ public static Projection[] include(String... field) {
      */
     public static Projection[] exclude(String... field) {
         return Arrays.stream(field)
-                .map(f -> new Projection(f, false))
+                .map(f -> new Projection(f, false, null, null))
                 .toArray(Projection[]::new);
     }
 }