fix support of vector, remove javadocs warning

Author: clun

astra-db-java-tools/src/main/java/com/datastax/astra/tool/loader/rag/ingestion/RagEmbeddingsModels.java

@@ -1,6 +1,7 @@
 package com.datastax.astra.tool.loader.rag.ingestion;
 
 public enum RagEmbeddingsModels {
+    /** Embedding models */
     NVIDIA_NEMO("nvidia", "NV-Embed-QA", 1024),
     OPENAI_ADA002("open-ai", "text-embedding-ada-002", 1536),
     OPENAI_3_SMALL("open-ai", "text-embedding-3-small", 1536),

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

@@ -1017,6 +1017,8 @@ public CollectionFindCursor<T, T> find(Filter filter, CollectionFindOptions opti
      *      options of find one
      * @param newDocType
      *      new class for return objects if projected
+     * @param <R>
+     *      type of new class for return objects if projected
      * @return
      *      the find iterable interface
      */
@@ -1061,49 +1063,123 @@ public CollectionFindCursor<T, T> findAll() {
         return find(null, new CollectionFindOptions());
     }
 
+    /**
+     * Fine document with pagination with no projection.
+     * @param filter
+     *      filter on documents
+     * @param options
+     *      options lilke sorting
+     * @return
+     *      a page of results
+     */
     public Page<T> findPage(Filter filter, CollectionFindOptions options) {
         return findPage(filter, options, getDocumentClass());
     }
 
-
     // -----------------------------
     // ---   Find and Rerank    ----
     // -----------------------------
 
     /**
-     * Finds all documents in the collection.
+     * Finds and reranks all documents in the collection using the specified options.
+     * This is a convenience method equivalent to calling {@link #findAndRerank(Filter, CollectionFindAndRerankOptions)} with a {@code null} filter.
      *
      * @param options
-     *      options of find one
+     *      the options used to customize the find and rerank operation
      * @return
-     *      the find iterable interface
+     *      a {@link CollectionFindAndRerankCursor} to iterate over the reranked documents
+     *
+     * <p>Example usage:</p>
+     * <pre>
+     * {@code
+     * CollectionFindAndRerankOptions options = new CollectionFindAndRerankOptions();
+     * CollectionFindAndRerankCursor<Document, Document> cursor = collection.findAndRerank(options);
+     * }
+     * </pre>
      */
     @BetaPreview
     public CollectionFindAndRerankCursor<T,T> findAndRerank(CollectionFindAndRerankOptions options) {
         return findAndRerank(null, options, getDocumentClass());
     }
 
     /**
-     * Finds all documents in the collection.
+     * Finds and reranks documents in the collection that match the given filter using the specified options.
      *
      * @param filter
-     *      the query filter
+     *      the query filter to apply to the collection
      * @param options
-     *      options of find one
+     *      the options used to customize the find and rerank operation
      * @return
-     *      the find iterable interface
+     *      a {@link CollectionFindAndRerankCursor} to iterate over the reranked documents
+     *
+     * <p>Example usage:</p>
+     * <pre>
+     * {@code
+     * Filter filter = Filters.eq("status", "active");
+     * CollectionFindAndRerankOptions options = new CollectionFindAndRerankOptions();
+     * CollectionFindAndRerankCursor<Document, Document> cursor = collection.findAndRerank(filter, options);
+     * }
+     * </pre>
      */
     @BetaPreview
     public CollectionFindAndRerankCursor<T,T> findAndRerank(Filter filter, CollectionFindAndRerankOptions options) {
         return findAndRerank(filter, options, getDocumentClass());
     }
 
+    /**
+     * Finds and reranks documents in the collection that match the given filter using the specified options,
+     * mapping the resulting documents to the specified target type.
+     *
+     * @param filter
+     *      the query filter to apply to the collection
+     * @param options
+     *      the options used to customize the find and rerank operation
+     * @param newRowType
+     *      the target class type to map the results to
+     * @param <R>
+     *      the type of the result rows after mapping
+     * @return
+     *      a {@link CollectionFindAndRerankCursor} to iterate over the reranked documents mapped to {@code R}
+     *
+     * <p>Example usage:</p>
+     * <pre>
+     * {@code
+     * Filter filter = Filters.eq("type", "book");
+     * CollectionFindAndRerankOptions options = new CollectionFindAndRerankOptions();
+     * CollectionFindAndRerankCursor<Document, Book> cursor = collection.findAndRerank(filter, options, Book.class);
+     * }
+     * </pre>
+     */
     @BetaPreview
     public <R> CollectionFindAndRerankCursor<T, R> findAndRerank(Filter filter, CollectionFindAndRerankOptions options, Class<R> newRowType) {
         return new CollectionFindAndRerankCursor<>(this, filter, options, newRowType);
     }
 
 
+    /**
+     * Finds and reranks documents in the collection using the given filter and options,
+     * and returns a paginated result containing reranked items mapped to the specified result type.
+     *
+     * @param filter
+     *      the query filter to apply to the collection
+     * @param options
+     *      the options used to customize the find and rerank operation
+     * @param newRowType
+     *      the target class type to map the results to
+     * @param <R>
+     *      the type of the result items after mapping
+     * @return
+     *      a {@link Page} of {@link RerankResult} objects containing the paginated reranked results
+     *
+     * <p>Example usage:</p>
+     * <pre>
+     * {@code
+     * Filter filter = Filters.gt("score", 50);
+     * CollectionFindAndRerankOptions options = new CollectionFindAndRerankOptions().limit(10);
+     * Page<RerankResult<Book>> page = collection.findAndRerankPage(filter, options, Book.class);
+     * }
+     * </pre>
+     */
     @BetaPreview
     public <R> Page<RerankResult<R>> findAndRerankPage(Filter filter, CollectionFindAndRerankOptions options, Class<R> newRowType) {
         Command findAndRerankCommand = Command
@@ -1181,6 +1257,8 @@ public <R> Page<RerankResult<R>> findAndRerankPage(Filter filter, CollectionFind
      * 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 <R> type of the result rows after mapping
+     * @param newRowType The class type to which the documents should be mapped.
      * @param filter The filter criteria used to select documents from the collection.
      * @param options The {@link CollectionFindOptions} 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.

astra-db-java/src/main/java/com/datastax/astra/client/collections/commands/options/CollectionFindAndRerankOptions.java

@@ -113,6 +113,12 @@ public CollectionFindAndRerankOptions sort(Sort... sorts) {
         return this;
     }
 
+    /**
+     * Return the sort clause as an arryr
+     *
+     * @return
+     *    Sort clause
+     */
     public Sort[] getSortArray() {
         return this.sort;
     }
@@ -189,9 +195,14 @@ public CollectionFindAndRerankOptions rerankOn(String rerankOn) {
         return this;
     }
 
-
-    public CollectionFindAndRerankOptions rerankQuery(String $lexical) {
-        this.rerankQuery = rerankOn;
+    /**
+     * Add a rerankQuery clause in the find block
+     *
+     * @param rerankQuery value for rerankQuery options
+     * @return current command
+     */
+    public CollectionFindAndRerankOptions rerankQuery(String rerankQuery) {
+        this.rerankQuery = rerankQuery;
         return this;
     }
 }

astra-db-java/src/main/java/com/datastax/astra/client/collections/definition/CollectionDefinition.java

@@ -346,6 +346,12 @@ public LexicalOptions getLexical() {
         return lexical;
     }
 
+    /**
+     * Builder pattern, disabled lexical
+     *
+     * @return
+     *      self reference
+     */
     public CollectionDefinition disableLexical() {
         if (getLexical() == null) {
             lexical(new LexicalOptions().enabled(false));
@@ -443,6 +449,11 @@ public CollectionDefinition rerank(String provider, String model) {
         return this;
     }
 
+    /**
+     * Builder pattern, disable reranking
+     *
+     * @return self reference
+     */
     public CollectionDefinition disableRerank() {
         if (getRerank() == null) {
             rerank = new CollectionRerankOptions().enabled(false);

astra-db-java/src/main/java/com/datastax/astra/client/collections/definition/documents/Document.java

@@ -42,6 +42,7 @@
 import com.datastax.astra.client.core.vector.DataAPIVector;
 import com.datastax.astra.client.core.vectorize.Vectorize;
 import com.datastax.astra.client.exceptions.InvalidFieldExpressionException;
+import com.datastax.astra.client.exceptions.UnexpectedDataAPIResponseException;
 import com.datastax.astra.internal.serdes.DataAPISerializer;
 import com.datastax.astra.internal.serdes.collections.DocumentSerializer;
 import com.datastax.astra.internal.utils.Assert;
@@ -444,10 +445,31 @@ public Optional<String> getVectorize() {
      *      vector list
      */
     @JsonIgnore
+    @SuppressWarnings("unchecked")
     public Optional<DataAPIVector> getVector() {
-        return Optional
-                .ofNullable((float[]) documentMap.get(DataAPIKeywords.VECTOR.getKeyword()))
-                .map(DataAPIVector::new);
+        if (!documentMap.containsKey(DataAPIKeywords.VECTOR.getKeyword())) {
+            return Optional.empty();
+        }
+
+        Object o = documentMap.get(DataAPIKeywords.VECTOR.getKeyword());
+
+        // Get a vector from a list of doubles
+        if (o instanceof DataAPIVector) {
+            return Optional.of((DataAPIVector) o);
+        } else if (o instanceof ArrayList<?> list && !list.isEmpty() && list.get(0) instanceof Double) {
+            ArrayList<Double> a = (ArrayList<Double>) list;
+            float[] floatArray = new float[a.size()];
+            for (int i = 0; i < a.size(); i++) {
+                floatArray[i] = a.get(i).floatValue();
+            }
+            return Optional.of(new DataAPIVector(floatArray));
+        } else if (o instanceof float[] array) {
+            // Get a vector from a float array
+            return Optional.of(new DataAPIVector(array));
+        } else {
+            throw new UnexpectedDataAPIResponseException("Could not parse $vector of type " + o.getClass().getName() +
+                    " to a DataAPIVector. Expected a list of Double, a float array or binary data");
+        }
     }
 
     /**
@@ -712,6 +734,21 @@ public <T> List<T> getList(@NonNull final String key, @NonNull final Class<T> cl
         return constructValuesList(key, clazz, null);
     }
 
+    /**
+     * Gets the list value of the given key, casting the list elements to the given {@code Class<T>}.  This is useful to avoid having
+     * casts in client code, though the effect is the same.
+     *
+     * @param <K>
+     *        type of the key
+     * @param <V>
+     *        type of the value
+     * @param key   the key
+     * @param keyClass the non-null class to cast the list value to
+     * @param valueClass the type of the value class
+     * @return the list value of the given key, or null if the instance does not contain this key.
+     * @throws ClassCastException if the elements in the list value of the given key is not of type T or the value is not a list
+     * @since 3.10
+     */
     public <K,V> Map<K,V> getMap(@NonNull final String key, @NonNull final Class<K> keyClass, @NonNull final Class<V> valueClass) {
         return constructValuesMap(key, keyClass, valueClass, null);
     }
@@ -823,6 +860,9 @@ public String toJson() {
      * Check if the given dot-delimited path exists as a key (final segment).
      * e.g. containsKey("foo.bar") returns true if "bar" is present in the Map
      * located at "foo".
+     *
+     * @param key for key
+     * @return if the key is present
      */
     public boolean containsKey(String key) {
         Assert.hasLength(key, "Field name should not be null");
@@ -838,6 +878,14 @@ public boolean containsKey(String key) {
         return true;
     }
 
+    /**
+     * Check if the given dot-delimited path exists as a key (final segment).
+     * e.g. containsKey("foo.bar") returns true if "bar" is present in the Map
+     * located at "foo".
+     *
+     * @param fieldPathSegment for key
+     * @return if the key is present
+     */
     public Object get(final String[] fieldPathSegment) {
         return get(EscapeUtils.escapeFieldNames(fieldPathSegment));
     }

astra-db-java/src/main/java/com/datastax/astra/client/core/hybrid/HybridLimits.java

@@ -67,6 +67,8 @@ public HybridLimits(Map<String, Integer> mapOfLimits) {
      *
      * @param limit
      *      lexical limit.
+     * @return
+     *      self reference
      */
     public HybridLimits lexical(Integer limit) {
         if (mapOfLimits == null) {
@@ -81,6 +83,8 @@ public HybridLimits lexical(Integer limit) {
      *
      * @param limit
      *      vector limit.
+     * @return
+     *      self reference
      */
     public HybridLimits vector(Integer limit) {
         if (mapOfLimits == null) {