update docstrings and reorganize

rohanshah18 · rohanshah18 · commit d79f288ec594 · 2025-03-27T17:40:01.000-04:00
diff --git a/src/integration/java/io/pinecone/clients/ConnectionsMapTest.java b/src/integration/java/io/pinecone/clients/ConnectionsMapTest.java
@@ -1,5 +1,6 @@
 package io.pinecone.clients;
 
+import io.pinecone.configs.PineconeConfig;
 import io.pinecone.configs.PineconeConnection;
 import io.pinecone.exceptions.PineconeNotFoundException;
 import io.pinecone.helpers.RandomStringBuilder;
@@ -57,6 +58,10 @@ public void testMultipleIndexesWithMultipleClients() throws InterruptedException
         // Get index1's host
         String host1 = indexModel1.getHost();
 
+        // Create config1 for getting index connection and set the host
+        PineconeConfig config1 = new PineconeConfig(System.getenv("PINECONE_API_KEY"));
+        config1.setHost(host1);
+
         // Create index-2
         pinecone1.createServerlessIndex(indexName2,
                 null,
@@ -72,6 +77,11 @@ public void testMultipleIndexesWithMultipleClients() throws InterruptedException
         // Get index2's host
         String host2 = indexModel2.getHost();
 
+        // Create config2 for getting index connection and set the host
+        PineconeConfig config2 = new PineconeConfig(System.getenv("PINECONE_API_KEY"));
+        config1.setHost(host2);
+
+
         // Establish grpc connection for index-1
         Index index1_1 = pinecone1.getIndexConnection(indexName1);
         // Get connections map
@@ -94,7 +104,7 @@ public void testMultipleIndexesWithMultipleClients() throws InterruptedException
         assertEquals(host2, connectionsMap1_2.get(indexName2).toString());
 
         // Establishing connections with index1 and index2 using another pinecone client
-        pinecone2.getConnection(indexName1);
+        pinecone2.getConnection(indexName1, config1);
         ConcurrentHashMap<String, PineconeConnection> connectionsMap2_1 = pinecone1.getConnectionsMap();
         // Verify the new connections map is pointing to the same reference
         assert connectionsMap2_1 == connectionsMap1_2;
@@ -103,7 +113,7 @@ public void testMultipleIndexesWithMultipleClients() throws InterruptedException
         // Verify the connection value for index1 is host1
         assertEquals(host1, connectionsMap2_1.get(indexName1).toString());
 
-        pinecone2.getConnection(indexName2);
+        pinecone2.getConnection(indexName2, config2);
         ConcurrentHashMap<String, PineconeConnection> connectionsMap2_2 = pinecone1.getConnectionsMap();
         // Verify the new connections map is pointing to the same reference
         assert connectionsMap2_1 == connectionsMap2_2;
diff --git a/src/integration/java/io/pinecone/integration/dataPlane/UpsertAndSearchRecordsTest.java b/src/integration/java/io/pinecone/integration/dataPlane/UpsertAndSearchRecordsTest.java
@@ -0,0 +1,83 @@
+package io.pinecone.integration.dataPlane;
+
+import io.pinecone.clients.Index;
+import io.pinecone.clients.Pinecone;
+import io.pinecone.helpers.RandomStringBuilder;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import org.openapitools.db_control.client.model.CreateIndexForModelRequest;
+import org.openapitools.db_control.client.model.CreateIndexForModelRequestEmbed;
+import org.openapitools.db_control.client.model.DeletionProtection;
+import org.openapitools.db_data.client.ApiException;
+import org.openapitools.db_data.client.model.SearchRecordsRequestQuery;
+import org.openapitools.db_data.client.model.SearchRecordsResponse;
+import org.openapitools.db_data.client.model.UpsertRecord;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+
+public class UpsertAndSearchRecordsTest {
+    @Test
+    public void upsertAndSearchRecordsTest() throws ApiException, org.openapitools.db_control.client.ApiException, InterruptedException {
+        Pinecone pinecone = new Pinecone.Builder(System.getenv("PINECONE_API_KEY")).build();
+        String indexName = RandomStringBuilder.build("inf", 8);
+        HashMap<String, String> fieldMap = new HashMap<>();
+        fieldMap.put("text", "chunk_text");
+        CreateIndexForModelRequestEmbed embed = new CreateIndexForModelRequestEmbed()
+                .model("multilingual-e5-large")
+                .fieldMap(fieldMap);
+        pinecone.createIndexForModel(indexName, CreateIndexForModelRequest.CloudEnum.AWS, "us-west-2", embed, DeletionProtection.DISABLED, new HashMap<>());
+
+        // Wait for index to be created
+        Thread.sleep(10000);
+
+        Index index = pinecone.getIndexConnection(indexName);
+        UpsertRecord record1 = new UpsertRecord();
+        record1.id("rec1");
+        record1.putAdditionalProperty("category", "digestive system");
+        record1.putAdditionalProperty("chunk_text", "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.");
+        ArrayList<UpsertRecord> records = new ArrayList<>();
+
+        UpsertRecord record2 = new UpsertRecord();
+        record2.id("rec2");
+        record2.putAdditionalProperty("category", "cultivation");
+        record2.putAdditionalProperty("chunk_text", "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.");
+
+        UpsertRecord record3 = new UpsertRecord();
+        record3.id("rec3");
+        record3.putAdditionalProperty("category", "immune system");
+        record3.putAdditionalProperty("chunk_text", "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.");
+
+        UpsertRecord record4 = new UpsertRecord();
+        record4.id("rec4");
+        record4.putAdditionalProperty("category", "endocrine system");
+        record4.putAdditionalProperty("chunk_text", "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.");
+
+        records.add(record1);
+        records.add(record2);
+        records.add(record3);
+        records.add(record4);
+
+        index.upsertRecords("example-namespace", records);
+        String namespace = "example-namespace";
+        HashMap<String, String> inputsMap = new HashMap<>();
+        inputsMap.put("text", "Disease prevention");
+        SearchRecordsRequestQuery query = new SearchRecordsRequestQuery()
+                .topK(4)
+                .inputs(inputsMap);
+
+        List<String> fields = new ArrayList<>();
+        fields.add("category");
+        fields.add("chunk_text");
+
+        // Wait for vectors to be upserted
+        Thread.sleep(5000);
+
+        SearchRecordsResponse recordsResponse = index.searchRecords(namespace, query, fields, null);
+        Assertions.assertEquals(records.size(), recordsResponse.getResult().getHits().size());
+        Assertions.assertEquals(record3.getId(), recordsResponse.getResult().getHits().get(0).getId());
+
+        pinecone.deleteIndex(indexName);
+    }
+}
diff --git a/src/main/java/io/pinecone/clients/Index.java b/src/main/java/io/pinecone/clients/Index.java
@@ -66,9 +66,9 @@ public class Index implements IndexInterface<UpsertResponse,
      *     Index index = client.getIndexConnection("my-index");
      * }</pre>
      *
-     * @param config The {@link PineconeConfig} configuration of the index.
+     * @param config     The {@link PineconeConfig} configuration of the index.
      * @param connection The {@link PineconeConnection} configuration to be used for this index.
-     * @param indexName The name of the index to interact with. The index host will be automatically resolved.
+     * @param indexName  The name of the index to interact with. The index host will be automatically resolved.
      * @throws PineconeValidationException if the connection object is null.
      */
     public Index(PineconeConfig config, PineconeConnection connection, String indexName) {
@@ -813,7 +813,7 @@ public DescribeIndexStatsResponse describeIndexStats(Struct filter) {
     /**
      * {@inheritDoc}
      * <p> Example:
-     *  <pre>{@code
+     * <pre>{@code
      *     import io.pinecone.proto.ListResponse;
      *
      *     ...
@@ -832,7 +832,7 @@ public ListResponse list() {
     /**
      * {@inheritDoc}
      * <p>Example:
-     *  <pre>{@code
+     * <pre>{@code
      *     import io.pinecone.proto.ListResponse;
      *
      *     ...
@@ -850,7 +850,7 @@ public ListResponse list(String namespace) {
     /**
      * {@inheritDoc}
      * <p>Example:
-     *  <pre>{@code
+     * <pre>{@code
      *     import io.pinecone.proto.ListResponse;
      *
      *     ...
@@ -868,7 +868,7 @@ public ListResponse list(String namespace, int limit, String paginationToken) {
     /**
      * {@inheritDoc}
      * <p>Example:
-     *  <pre>{@code
+     * <pre>{@code
      *     import io.pinecone.proto.ListResponse;
      *
      *     ...
@@ -886,7 +886,7 @@ public ListResponse list(String namespace, int limit) {
     /**
      * {@inheritDoc}
      * <p>Example:
-     *  <pre>{@code
+     * <pre>{@code
      *     import io.pinecone.proto.ListResponse;
      *
      *     ...
@@ -905,7 +905,7 @@ public ListResponse list(String namespace, String prefix) {
     /**
      * {@inheritDoc}
      * <p> Example:
-     *  <pre>{@code
+     * <pre>{@code
      *     import io.pinecone.proto.ListResponse;
      *
      *     ...
@@ -925,7 +925,7 @@ public ListResponse list(String namespace, String prefix, int limit) {
     /**
      * {@inheritDoc}
      * <p>Example:
-     *  <pre>{@code
+     * <pre>{@code
      *     import io.pinecone.proto.ListResponse;
      *
      *     ...
@@ -950,22 +950,23 @@ public ListResponse list(String namespace, String prefix, String paginationToken
      * through a list of vector IDs. It then makes a synchronous RPC call to fetch the list of vector IDs.
      *
      * <p>Example:
-     *  <pre>{@code
+     * <pre>{@code
      *     import io.pinecone.proto.ListResponse;
      *
      *     ...
      *
      *     ListResponse listResponse = index.list("example-namespace", "st-", "some-pagToken", 10);
      *   }</pre>
-     * @param namespace The namespace that holds the vector IDs you want to retrieve. If namespace is not specified,
-     *                  the default namespace is used.
-     * @param prefix The prefix with which vector IDs must start to be included in the response.
+     *
+     * @param namespace       The namespace that holds the vector IDs you want to retrieve. If namespace is not specified,
+     *                        the default namespace is used.
+     * @param prefix          The prefix with which vector IDs must start to be included in the response.
      * @param paginationToken The token to paginate through the list of vector IDs.
-     * @param limit The maximum number of vector IDs you want to retrieve.
+     * @param limit           The maximum number of vector IDs you want to retrieve.
      * @return {@link ListResponse} containing the list of vector IDs fetched from the specified namespace.
-     *         The response includes vector IDs up to {@code 100} items.
+     * The response includes vector IDs up to {@code 100} items.
      * @throws RuntimeException if there are issues processing the request or communicating with the server.
-     *         This includes network issues, server errors, or serialization issues with the request or response.
+     *                          This includes network issues, server errors, or serialization issues with the request or response.
      */
     public ListResponse list(String namespace, String prefix, String paginationToken, int limit) {
         validateListEndpointParameters(namespace, prefix, paginationToken, limit, true, true, true, true);
@@ -974,17 +975,81 @@ public ListResponse list(String namespace, String prefix, String paginationToken
         return blockingStub.list(listRequest);
     }
 
+    /**
+     * <p>Upserts records into a specified namespace within a Pinecone index. This operation
+     * will insert new records or update existing ones based on the provided data.</p>
+     *
+     * <p>The method sends a list of {@link UpsertRecord} objects to the specified namespace
+     * in the Pinecone index, either inserting new records or updating existing records
+     * depending on whether the record IDs already exist.</p>
+     *
+     * <p>Example:
+     * <pre>{@code
+     *     List<UpsertRecord> records = new ArrayList<>();
+     *     records.add(new UpsertRecord("rec1", "Apple's first product, the Apple I, was released in 1976.", "product"));
+     *     records.add(new UpsertRecord("rec2", "Apples are a great source of dietary fiber.", "nutrition"));
+     *
+     *     try {
+     *         index.upsertRecords("example-namespace", records);
+     *     } catch (ApiException e) {
+     *
+     *     }
+     * }</pre></p>
+     *
+     * @param namespace    The namespace within the Pinecone index where the records will be upserted.
+     *                     The namespace must be an existing namespace or a valid one to create new records.
+     * @param upsertRecord A list of {@link UpsertRecord} objects containing the records to be upserted.
+     *                     Each record must include a unique ID and the data to be stored.
+     * @throws ApiException If there is an issue with the upsert operation. This could include network errors,
+     *                      invalid input data, or issues communicating with the Pinecone service.
+     */
     public void upsertRecords(String namespace, List<UpsertRecord> upsertRecord) throws ApiException {
         vectorOperations.upsertRecordsNamespace(namespace, upsertRecord);
     }
 
-    public SearchRecordsResponse searchRecords(String id, String namespace, Object filter, int topK, SearchRecordsVector vector) throws ApiException {
-        SearchRecordsRequestQuery searchRecordsRequestquery = new SearchRecordsRequestQuery()
-                .id(id)
-                .filter(filter)
-                .topK(topK)
-                .vector(vector);
-        SearchRecordsRequest request = new SearchRecordsRequest().query(searchRecordsRequestquery);
+    /**
+     * <p>Searches for records in a specified namespace within a Pinecone index by converting a query into a vector embedding.
+     * Optionally, a reranking operation can be applied to refine the results.</p>
+     *
+     * <p>This method sends a search query along with specified fields to the Pinecone index, retrieves the relevant records,
+     * and applies an optional reranking operation if provided.</p>
+     *
+     * <p>Example:
+     * <pre>{@code
+     *     String namespace = "example-namespace";
+     *     HashMap<String, String> inputsMap = new HashMap<>();
+     *     inputsMap.put("text", "Disease prevention");
+     *     SearchRecordsRequestQuery query = new SearchRecordsRequestQuery()
+     *             .topK(3)
+     *             .inputs(inputsMap);
+     *
+     *     List<String> fields = new ArrayList<>();
+     *     fields.add("category");
+     *     fields.add("chunk_text");
+     *
+     *     SearchRecordsResponse recordsResponse = index.searchRecords(namespace, query, fields, null);
+     * }</pre></p>
+     *
+     * @param namespace The namespace within the Pinecone index where the search will be performed.
+     *                  The namespace must exist and contain records to search through.
+     * @param query The query to be converted into a vector embedding for the search operation.
+     *              This query contains the input data for the search and parameters like topK for result limits.
+     * @param fields A list of fields to be searched within the records. These fields define which parts of the records
+     *               are considered during the search.
+     * @param rerank (Optional) A reranking operation that can be applied to refine or reorder the search results.
+     *               Pass null if no reranking is required.
+     * @return A {@link SearchRecordsResponse} object containing the search results, including the top matching records.
+     * @throws ApiException If there is an issue with the search operation. This could include network errors,
+     *                      invalid input data, or issues communicating with the Pinecone service.
+     */
+    public SearchRecordsResponse searchRecords(String namespace,
+                                               SearchRecordsRequestQuery query,
+                                               List<String> fields,
+                                               SearchRecordsRequestRerank rerank) throws ApiException {
+        SearchRecordsRequest request = new SearchRecordsRequest()
+                .query(query)
+                .fields(fields)
+                .rerank(rerank);
 
         return vectorOperations.searchRecordsNamespace(namespace, request);
     }
diff --git a/src/main/java/io/pinecone/clients/Pinecone.java b/src/main/java/io/pinecone/clients/Pinecone.java
@@ -221,7 +221,7 @@ public IndexModel createSparseServelessIndex(String indexName,
      * Example:
      * <pre>{@code
      *     client.createIndexForModel("my-index", CreateIndexForModelRequest.CloudEnum.AWS,
-     *                                            "us-west-2", embedConfig, DeletionProtection.ENABLED, tags);
+     *                                            "us-west-2", embedConfig, DeletionProtection.DISABLED, tags);
      * }</pre>
      *
      * @param name The name of the index to be created. The name must be between 1 and 45 characters,
@@ -993,8 +993,11 @@ public Index getIndexConnection(String indexName) throws PineconeValidationExcep
             throw new PineconeValidationException("Index name cannot be null or empty");
         }
 
-        PineconeConnection connection = getConnection(indexName);
-        return new Index(config, connection, indexName);
+        PineconeConfig perConnectionConfig = new PineconeConfig(config.getApiKey(), config.getSourceTag());
+        perConnectionConfig.setHost(getIndexHost(indexName));
+
+        PineconeConnection connection = getConnection(indexName, perConnectionConfig);
+        return new Index(perConnectionConfig, connection, indexName);
     }
 
     /**
@@ -1022,7 +1025,10 @@ public AsyncIndex getAsyncIndexConnection(String indexName) throws PineconeValid
             throw new PineconeValidationException("Index name cannot be null or empty");
         }
 
-        PineconeConnection connection = getConnection(indexName);
+        PineconeConfig perConnectionConfig = new PineconeConfig(config.getApiKey(), config.getSourceTag());
+        perConnectionConfig.setHost(getIndexHost(indexName));
+
+        PineconeConnection connection = getConnection(indexName, perConnectionConfig);
         return new AsyncIndex(config, connection, indexName);
     }
 
@@ -1038,9 +1044,7 @@ public Inference getInferenceClient() {
         return new Inference(config);
     }
 
-    PineconeConnection getConnection(String indexName) {
-        PineconeConfig perConnectionConfig = new PineconeConfig(config.getApiKey(), config.getSourceTag());
-        perConnectionConfig.setHost(getIndexHost(indexName));
+    PineconeConnection getConnection(String indexName, PineconeConfig perConnectionConfig) {
         return connectionsMap.computeIfAbsent(indexName, key -> new PineconeConnection(perConnectionConfig));
     }
 

Original file line number	Diff line number	Diff line change
`@@ -221,7 +221,7 @@ public IndexModel createSparseServelessIndex(String indexName,`
`221`	`221`	`* Example:`
`222`	`222`	`* <pre>{@code`
`223`	`223`	`* client.createIndexForModel("my-index", CreateIndexForModelRequest.CloudEnum.AWS,`
`224`		`- * "us-west-2", embedConfig, DeletionProtection.ENABLED, tags);`
	`224`	`+ * "us-west-2", embedConfig, DeletionProtection.DISABLED, tags);`
`225`	`225`	`* }</pre>`
`226`	`226`	`*`
`227`	`227`	`* @param name The name of the index to be created. The name must be between 1 and 45 characters,`
`@@ -993,8 +993,11 @@ public Index getIndexConnection(String indexName) throws PineconeValidationExcep`
`993`	`993`	`throw new PineconeValidationException("Index name cannot be null or empty");`
`994`	`994`	`}`
`995`	`995`
`996`		`- PineconeConnection connection = getConnection(indexName);`
`997`		`- return new Index(config, connection, indexName);`
	`996`	`+ PineconeConfig perConnectionConfig = new PineconeConfig(config.getApiKey(), config.getSourceTag());`
	`997`	`+ perConnectionConfig.setHost(getIndexHost(indexName));`
	`998`	`+`
	`999`	`+ PineconeConnection connection = getConnection(indexName, perConnectionConfig);`
	`1000`	`+ return new Index(perConnectionConfig, connection, indexName);`
`998`	`1001`	`}`
`999`	`1002`
`1000`	`1003`	`/**`
`@@ -1022,7 +1025,10 @@ public AsyncIndex getAsyncIndexConnection(String indexName) throws PineconeValid`
`1022`	`1025`	`throw new PineconeValidationException("Index name cannot be null or empty");`
`1023`	`1026`	`}`
`1024`	`1027`
`1025`		`- PineconeConnection connection = getConnection(indexName);`
	`1028`	`+ PineconeConfig perConnectionConfig = new PineconeConfig(config.getApiKey(), config.getSourceTag());`
	`1029`	`+ perConnectionConfig.setHost(getIndexHost(indexName));`
	`1030`	`+`
	`1031`	`+ PineconeConnection connection = getConnection(indexName, perConnectionConfig);`
`1026`	`1032`	`return new AsyncIndex(config, connection, indexName);`
`1027`	`1033`	`}`
`1028`	`1034`
`@@ -1038,9 +1044,7 @@ public Inference getInferenceClient() {`
`1038`	`1044`	`return new Inference(config);`
`1039`	`1045`	`}`
`1040`	`1046`
`1041`		`- PineconeConnection getConnection(String indexName) {`
`1042`		`- PineconeConfig perConnectionConfig = new PineconeConfig(config.getApiKey(), config.getSourceTag());`
`1043`		`- perConnectionConfig.setHost(getIndexHost(indexName));`
	`1047`	`+ PineconeConnection getConnection(String indexName, PineconeConfig perConnectionConfig) {`
`1044`	`1048`	`return connectionsMap.computeIfAbsent(indexName, key -> new PineconeConnection(perConnectionConfig));`
`1045`	`1049`	`}`
`1046`	`1050`