Add suggestions and update docs

Author: Milder Hernandez Cagua

api-test/integration-tests/src/test/java/com/microsoft/semantickernel/tests/connectors/memory/jdbc/JDBCVectorStoreRecordCollectionTest.java

@@ -28,7 +28,7 @@
 @Testcontainers
 public class JDBCVectorStoreRecordCollectionTest {
     @Container
-    private static final MySQLContainer<?> CONTAINER = new MySQLContainer<>("mysql:5.7.34");
+    private static final MySQLContainer<?> CONTAINER = new MySQLContainer<>("mysql:latest");
     private static final String MYSQL_USER = "test";
     private static final String MYSQL_PASSWORD = "test";
     private static MysqlDataSource dataSource;

semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreDefaultQueryProvider.java

@@ -114,6 +114,12 @@ protected String getCollectionTableName(String collectionName) {
         return validateSQLidentifier(prefixForCollectionTables + collectionName);
     }
 
+    /**
+     * Prepares the vector store.
+     * Executes any necessary setup steps for the vector store.
+     *
+     * @throws SKException if an error occurs while preparing the vector store
+     */
     @Override
     public void prepareVectorStore() {
         String createCollectionsTable = "CREATE TABLE IF NOT EXISTS "
@@ -128,6 +134,13 @@ public void prepareVectorStore() {
         }
     }
 
+    /**
+     * Checks if the types of the record class fields are supported.
+     *
+     * @param recordClass the record class
+     * @param recordDefinition the record definition
+     * @throws IllegalArgumentException if the types are not supported
+     */
     @Override
     public void validateSupportedTypes(Class<?> recordClass,
         VectorStoreRecordDefinition recordDefinition) {
@@ -140,6 +153,13 @@ public void validateSupportedTypes(Class<?> recordClass,
             recordDefinition.getVectorDeclaredFields(recordClass), supportedVectorTypes.keySet());
     }
 
+    /**
+     * Checks if a collection exists.
+     *
+     * @param collectionName the collection name
+     * @return true if the collection exists, false otherwise
+     * @throws SKException if an error occurs while checking if the collection exists
+     */
     @Override
     public boolean collectionExists(String collectionName) {
         String query = "SELECT 1 FROM " + validateSQLidentifier(collectionsTable)
@@ -155,6 +175,14 @@ public boolean collectionExists(String collectionName) {
         }
     }
 
+    /**
+     * Creates a collection.
+     *
+     * @param collectionName the collection name
+     * @param recordClass the record class
+     * @param recordDefinition the record definition
+     * @throws SKException if an error occurs while creating the collection
+     */
     @Override
     @SuppressFBWarnings("SQL_PREPARED_STATEMENT_GENERATED_FROM_NONCONSTANT_STRING") // SQL query is generated dynamically with valid identifiers
     public void createCollection(String collectionName, Class<?> recordClass,
@@ -188,6 +216,12 @@ public void createCollection(String collectionName, Class<?> recordClass,
         }
     }
 
+    /**
+     * Deletes a collection.
+     *
+     * @param collectionName the collection name
+     * @throws SKException if an error occurs while deleting the collection
+     */
     @Override
     public void deleteCollection(String collectionName) {
         String deleteCollectionOperation = "DELETE FROM " + validateSQLidentifier(collectionsTable)
@@ -211,6 +245,12 @@ public void deleteCollection(String collectionName) {
         }
     }
 
+    /**
+     * Gets the collection names.
+     *
+     * @return the collection names
+     * @throws SKException if an error occurs while getting the collection names
+     */
     @Override
     public List<String> getCollectionNames() {
         String query = "SELECT collectionId FROM " + validateSQLidentifier(collectionsTable);
@@ -230,6 +270,18 @@ public List<String> getCollectionNames() {
         }
     }
 
+    /**
+     * Gets a list of records from the store.
+     *
+     * @param collectionName the collection name
+     * @param keys the keys
+     * @param recordDefinition the record definition
+     * @param mapper the mapper
+     * @param options the options
+     * @return the records
+     * @param <Record> the record type
+     * @throws SKException if an error occurs while getting the records
+     */
     @Override
     public <Record> List<Record> getRecords(String collectionName, List<String> keys,
         VectorStoreRecordDefinition recordDefinition, JDBCVectorStoreRecordMapper<Record> mapper,
@@ -272,6 +324,15 @@ public void upsertRecords(String collectionName, List<?> records,
             "Upsert is not supported. Try with a specific query provider.");
     }
 
+    /**
+     * Deletes records.
+     *
+     * @param collectionName the collection name
+     * @param keys the keys
+     * @param recordDefinition the record definition
+     * @param options the options
+     * @throws SKException if an error occurs while deleting the records
+     */
     @Override
     public void deleteRecords(String collectionName, List<String> keys,
         VectorStoreRecordDefinition recordDefinition, DeleteRecordOptions options) {
@@ -291,6 +352,13 @@ public void deleteRecords(String collectionName, List<String> keys,
         }
     }
 
+    /**
+     * Validates an SQL identifier.
+     *
+     * @param identifier the identifier
+     * @return the identifier if it is valid
+     * @throws IllegalArgumentException if the identifier is invalid
+     */
     public static String validateSQLidentifier(String identifier) {
         if (identifier.matches("[a-zA-Z_][a-zA-Z0-9_]*")) {
             return identifier;

semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/JDBCVectorStoreRecordCollection.java

@@ -83,6 +83,7 @@ public String getCollectionName() {
      * Checks if the collection exists in the store.
      *
      * @return A Mono emitting a boolean indicating if the collection exists.
+     * @throws SKException if the operation fails
      */
     @Override
     public Mono<Boolean> collectionExistsAsync() {
@@ -95,6 +96,7 @@ public Mono<Boolean> collectionExistsAsync() {
      * Creates the collection in the store.
      *
      * @return A Mono representing the completion of the creation operation.
+     * @throws SKException if the operation fails
      */
     @Override
     public Mono<Void> createCollectionAsync() {
@@ -109,6 +111,7 @@ public Mono<Void> createCollectionAsync() {
      * Creates the collection in the store if it does not exist.
      *
      * @return A Mono representing the completion of the creation operation.
+     * @throws SKException if the operation fails
      */
     @Override
     public Mono<Void> createCollectionIfNotExistsAsync() {
@@ -127,6 +130,7 @@ public Mono<Void> createCollectionIfNotExistsAsync() {
      * Deletes the collection from the store.
      *
      * @return A Mono representing the completion of the deletion operation.
+     * @throws SKException if the operation fails
      */
     @Override
     public Mono<Void> deleteCollectionAsync() {
@@ -142,6 +146,7 @@ public Mono<Void> deleteCollectionAsync() {
      * @param key       The key of the record to get.
      * @param options The options for getting the record.
      * @return A Mono emitting the record.
+     * @throws SKException if the operation fails
      */
     @Override
     public Mono<Record> getAsync(String key, GetRecordOptions options) {
@@ -160,6 +165,7 @@ public Mono<Record> getAsync(String key, GetRecordOptions options) {
      * @param keys The keys of the records to get.
      * @param options The options for getting the records.
      * @return A Mono emitting a collection of records.
+     * @throws SKException if the operation fails
      */
     @Override
     public Mono<List<Record>> getBatchAsync(List<String> keys, GetRecordOptions options) {
@@ -187,6 +193,7 @@ protected String getKeyFromRecord(Record data) {
      * @param data    The record to upsert.
      * @param options The options for upserting the record.
      * @return A Mono emitting the key of the upserted record.
+     * @throws SKException if the operation fails
      */
     @Override
     public Mono<String> upsertAsync(Record data, UpsertRecordOptions options) {
@@ -205,6 +212,7 @@ public Mono<String> upsertAsync(Record data, UpsertRecordOptions options) {
      * @param data    The records to upsert.
      * @param options The options for upserting the records.
      * @return A Mono emitting a collection of keys of the upserted records.
+     * @throws SKException if the operation fails
      */
     @Override
     public Mono<List<String>> upsertBatchAsync(List<Record> data, UpsertRecordOptions options) {
@@ -222,6 +230,7 @@ public Mono<List<String>> upsertBatchAsync(List<Record> data, UpsertRecordOption
      * @param key       The key of the record to delete.
      * @param options The options for deleting the record.
      * @return A Mono representing the completion of the deletion operation.
+     * @throws SKException if the operation fails
      */
     @Override
     public Mono<Void> deleteAsync(String key, DeleteRecordOptions options) {
@@ -234,6 +243,7 @@ public Mono<Void> deleteAsync(String key, DeleteRecordOptions options) {
      * @param keys The keys of the records to delete.
      * @param options The options for deleting the records.
      * @return A Mono representing the completion of the deletion operation.
+     * @throws SKException if the operation fails
      */
     @Override
     public Mono<Void> deleteBatchAsync(List<String> keys, DeleteRecordOptions options) {
@@ -247,6 +257,7 @@ public Mono<Void> deleteBatchAsync(List<String> keys, DeleteRecordOptions option
      * Prepares the collection for use.
      *
      * @return A Mono representing the completion of the preparation operation.
+     * @throws SKException if the operation fails
      */
     @Override
     public Mono<Void> prepareAsync() {

semantickernel-experimental/src/main/java/com/microsoft/semantickernel/connectors/data/jdbc/MySQLVectorStoreQueryProvider.java

@@ -71,6 +71,14 @@ private void setStatementValues(PreparedStatement statement, Object record,
         }
     }
 
+    /**
+     * Upserts records into the collection.
+     * @param collectionName the collection name
+     * @param records the records to upsert
+     * @param recordDefinition the record definition
+     * @param options the upsert options
+     * @throws SKException if the upsert fails
+     */
     @Override
     @SuppressFBWarnings("SQL_PREPARED_STATEMENT_GENERATED_FROM_NONCONSTANT_STRING") // SQL query is generated dynamically with valid identifiers
     public void upsertRecords(String collectionName, List<?> records,

semantickernel-experimental/src/main/java/com/microsoft/semantickernel/data/recorddefinition/VectorStoreRecordDefinition.java

@@ -56,8 +56,12 @@ public List<VectorStoreRecordField> getNonVectorFields() {
         return fields;
     }
 
+    private enum DeclaredFieldType {
+        KEY, DATA, VECTOR
+    }
+
     private List<Field> getDeclaredFields(Class<?> recordClass, List<VectorStoreRecordField> fields,
-        String fieldType) {
+        DeclaredFieldType fieldType) {
         List<Field> declaredFields = new ArrayList<>();
         for (VectorStoreRecordField field : fields) {
             try {
@@ -85,14 +89,14 @@ public List<Field> getDataDeclaredFields(Class<?> recordClass) {
         return getDeclaredFields(
             recordClass,
             dataFields.stream().map(f -> (VectorStoreRecordField) f).collect(Collectors.toList()),
-            "Data");
+            DeclaredFieldType.DATA);
     }
 
     public List<Field> getVectorDeclaredFields(Class<?> recordClass) {
         return getDeclaredFields(
             recordClass,
             vectorFields.stream().map(f -> (VectorStoreRecordField) f).collect(Collectors.toList()),
-            "Vector");
+            DeclaredFieldType.VECTOR);
     }
 
     private VectorStoreRecordDefinition(