io.pinecone.clients

Class Pinecone

java.lang.Object

io.pinecone.clients.Pinecone

public class Pinecone
extends java.lang.Object

The Pinecone class is the main entry point for interacting with Pinecone via the Java SDK. It is used to create, delete, and manage your indexes and collections.

To instantiate the Pinecone class, use the Pinecone.Builder class to pass an API key and any other optional configuration.

     import io.pinecone.clients.Pinecone;

     Pinecone client = new Pinecone.Builder("PINECONE_API_KEY").build();

     // Use the client to interact with Pinecone
     client.describeIndex("YOUR-INDEX");

     // Use the client to obtain an Index or AsyncIndex instance to upsert or query
     Index index = client.getIndexConnection("YOUR-INDEX");
     index.upsert(...);
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Pinecone.Builder A builder class for creating a Pinecone instance.

Method Summary

Modifier and Type	Method and Description
IndexModel	configureIndex(java.lang.String indexName, java.lang.Integer replicas) Overload for configureIndex to only change the number of replicas for an index.
IndexModel	configureIndex(java.lang.String indexName, java.lang.String podType) Overload for configureIndex to only change the podType of an index.
IndexModel	configureIndex(java.lang.String indexName, java.lang.String podType, java.lang.Integer replicas) Configures an existing pod-based index with new settings.
CollectionModel	createCollection(java.lang.String collectionName, java.lang.String sourceIndex) Creates a new collection from a source index.
IndexModel	createPodsIndex(java.lang.String indexName, java.lang.Integer dimension, java.lang.String environment, java.lang.String podType) Overload for creating a new pods index with environment and podType, the minimum required parameters.
IndexModel	createPodsIndex(java.lang.String indexName, java.lang.Integer dimension, java.lang.String environment, java.lang.String podType, java.lang.Integer pods) Overload for creating a new pods index with environment, podType, and pods.
IndexModel	createPodsIndex(java.lang.String indexName, java.lang.Integer dimension, java.lang.String environment, java.lang.String podType, java.lang.Integer pods, CreateIndexRequestSpecPodMetadataConfig metadataConfig) Overload for creating a new pods index with environment, podType, pods, and metadataConfig.
IndexModel	createPodsIndex(java.lang.String indexName, java.lang.Integer dimension, java.lang.String environment, java.lang.String podType, java.lang.Integer replicas, java.lang.Integer shards) Overload for creating a new pods index with environment, podType, replicas, and shards.
IndexModel	createPodsIndex(java.lang.String indexName, java.lang.Integer dimension, java.lang.String environment, java.lang.String podType, java.lang.Integer replicas, java.lang.Integer shards, CreateIndexRequestSpecPodMetadataConfig metadataConfig) Overload for creating a new pods index with environment, podType, replicas, shards, and metadataConfig.
IndexModel	createPodsIndex(java.lang.String indexName, java.lang.Integer dimension, java.lang.String environment, java.lang.String podType, java.lang.String metric) Overload for creating a new pods index with environment, podType, and metric.
IndexModel	createPodsIndex(java.lang.String indexName, java.lang.Integer dimension, java.lang.String environment, java.lang.String podType, java.lang.String metric, CreateIndexRequestSpecPodMetadataConfig metadataConfig) Overload for creating a new pods index with environment, podType, metric, and metadataConfig.
IndexModel	createPodsIndex(java.lang.String indexName, java.lang.Integer dimension, java.lang.String environment, java.lang.String podType, java.lang.String metric, java.lang.Integer replicas, java.lang.Integer shards, java.lang.Integer pods, CreateIndexRequestSpecPodMetadataConfig metadataConfig, java.lang.String sourceCollection) Creates a new pods index with the specified parameters.
IndexModel	createPodsIndex(java.lang.String indexName, java.lang.Integer dimension, java.lang.String environment, java.lang.String podType, java.lang.String metric, java.lang.String sourceCollection) Overload for creating a new pods index with environment, podType, metric, and sourceCollection.
IndexModel	createServerlessIndex(java.lang.String indexName, java.lang.String metric, int dimension, java.lang.String cloud, java.lang.String region) Creates a new serverless index with the specified parameters.
void	deleteCollection(java.lang.String collectionName) Deletes a collection.
void	deleteIndex(java.lang.String indexName) Deletes an index.
CollectionModel	describeCollection(java.lang.String collectionName) Describes an existing collection.
IndexModel	describeIndex(java.lang.String indexName) Retrieves information about an existing index.
AsyncIndex	getAsyncIndexConnection(java.lang.String indexName) Retrieves a connection to a specific index for asynchronous operations.
Index	getIndexConnection(java.lang.String indexName) Retrieves a connection to a specific index for synchronous operations.
CollectionList	listCollections() Lists all collections in the project.
IndexList	listIndexes() Lists all indexes in your project, including the index name, dimension, metric, status, and spec.
static void	validatePodIndexParams(java.lang.String indexName, java.lang.Integer dimension, java.lang.String environment, java.lang.String podType, java.lang.String metric, java.lang.Integer replicas, java.lang.Integer shards, java.lang.Integer pods)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createServerlessIndex

public IndexModel createServerlessIndex(java.lang.String indexName,
                                        java.lang.String metric,
                                        int dimension,
                                        java.lang.String cloud,
                                        java.lang.String region)
                                 throws PineconeException

Creates a new serverless index with the specified parameters.

Example:

 
     client.createServerlessIndex("YOUR-INDEX", "cosine", 1536, "aws", "us-west-2");
 

Parameters:

indexName - The name of the index to be created.

metric - The metric type for the index. Must be one of "cosine", "euclidean", or "dotproduct".

dimension - The number of dimensions for the index.

cloud - The cloud provider for the index.

region - The cloud region for the index.

Returns:

IndexModel representing the created serverless index.

Throws:

PineconeException - if the API encounters an error during index creation or if any of the arguments are invalid.

createPodsIndex

public IndexModel createPodsIndex(java.lang.String indexName,
                                  java.lang.Integer dimension,
                                  java.lang.String environment,
                                  java.lang.String podType)

Overload for creating a new pods index with environment and podType, the minimum required parameters.

Example:

 
     client.createPodsIndex("YOUR-INDEX", 1536, "us-east4-gcp", "p1.x2");
 

Parameters:

indexName - The name of the index to be created.

dimension - The number of dimensions for the index.

environment - The cloud environment where you want the index to be hosted.

podType - The type of pod to use. A string with one of s1, p1, or p2 appended with a "." and one of x1, x2, x4, or x8.

Returns:

IndexModel representing the created serverless index.

Throws:

PineconeException - if the API encounters an error during index creation or if any of the arguments are invalid.

createPodsIndex

public IndexModel createPodsIndex(java.lang.String indexName,
                                  java.lang.Integer dimension,
                                  java.lang.String environment,
                                  java.lang.String podType,
                                  java.lang.String metric)

Overload for creating a new pods index with environment, podType, and metric.

Example:

 
     client.createPodsIndex("YOUR-INDEX", 1536, "us-east4-gcp", "p1.x2", "cosine");
 

Parameters:

indexName - The name of the index to be created.

dimension - The number of dimensions for the index.

environment - The cloud environment where you want the index to be hosted.

podType - The type of pod to use. A string with one of s1, p1, or p2 appended with a "." and one of x1, x2, x4, or x8.

metric - The metric type for the index. Must be one of "cosine", "euclidean", or "dotproduct".

Returns:

IndexModel representing the created serverless index.

Throws:

PineconeException - if the API encounters an error during index creation or if any of the arguments are invalid.

createPodsIndex

public IndexModel createPodsIndex(java.lang.String indexName,
                                  java.lang.Integer dimension,
                                  java.lang.String environment,
                                  java.lang.String podType,
                                  java.lang.String metric,
                                  CreateIndexRequestSpecPodMetadataConfig metadataConfig)

Overload for creating a new pods index with environment, podType, metric, and metadataConfig.

Example:

 
     import org.openapitools.client.model.CreateIndexRequestSpecPodMetadataConfig;
     ...

     CreateIndexRequestSpecPodMetadataConfig metadataConfig =
         new CreateIndexRequestSpecPodMetadataConfig()
         .fields(Arrays.asList("genre", "year"));

     client.createPodsIndex("YOUR-INDEX", 1536, "us-east4-gcp", "p1.x2", "cosine", metadataConfig);
 

Parameters:

indexName - The name of the index to be created.

dimension - The number of dimensions for the index.

environment - The cloud environment where you want the index to be hosted.

podType - The type of pod to use. A string with one of s1, p1, or p2 appended with a "." and one of x1, x2, x4, or x8.

metric - The metric type for the index. Must be one of "cosine", "euclidean", or "dotproduct".

metadataConfig - The configuration for the behavior of Pinecone's internal metadata index. By default, all metadata is indexed; when metadataConfig is present, only specified metadata fields are indexed.

Returns:

IndexModel representing the created serverless index.

Throws:

PineconeException - if the API encounters an error during index creation or if any of the arguments are invalid.

createPodsIndex

public IndexModel createPodsIndex(java.lang.String indexName,
                                  java.lang.Integer dimension,
                                  java.lang.String environment,
                                  java.lang.String podType,
                                  java.lang.String metric,
                                  java.lang.String sourceCollection)

Overload for creating a new pods index with environment, podType, metric, and sourceCollection.

Example:

 
     client.createPodsIndex("YOUR-INDEX", 1536, "us-east4-gcp", "p1.x2", "cosine", "my-collection");
 

Parameters:

indexName - The name of the index to be created.

dimension - The number of dimensions for the index.

environment - The cloud environment where you want the index to be hosted.

podType - The type of pod to use. A string with one of s1, p1, or p2 appended with a "." and one of x1, x2, x4, or x8.

metric - The metric type for the index. Must be one of "cosine", "euclidean", or "dotproduct".

sourceCollection - The name of the collection to be used as the source for the index. Collections are snapshots of an index at a point in time.

Returns:

IndexModel representing the created serverless index.

Throws:

PineconeException - if the API encounters an error during index creation or if any of the arguments are invalid.

createPodsIndex

public IndexModel createPodsIndex(java.lang.String indexName,
                                  java.lang.Integer dimension,
                                  java.lang.String environment,
                                  java.lang.String podType,
                                  java.lang.Integer pods)

Overload for creating a new pods index with environment, podType, and pods.

Example:

 
     client.createPodsIndex("YOUR-INDEX", 1536, "us-east4-gcp", "p1.x2", "cosine", 6);
 

Parameters:

indexName - The name of the index to be created.

dimension - The number of dimensions for the index.

environment - The cloud environment where you want the index to be hosted.

podType - The type of pod to use. A string with one of s1, p1, or p2 appended with a "." and one of x1, x2, x4, or x8.

pods - The number of pods to be used in the index.

Returns:

IndexModel representing the created serverless index.

Throws:

PineconeException - if the API encounters an error during index creation or if any of the arguments are invalid.

createPodsIndex

public IndexModel createPodsIndex(java.lang.String indexName,
                                  java.lang.Integer dimension,
                                  java.lang.String environment,
                                  java.lang.String podType,
                                  java.lang.Integer pods,
                                  CreateIndexRequestSpecPodMetadataConfig metadataConfig)

Overload for creating a new pods index with environment, podType, pods, and metadataConfig.

Example:

 
     import org.openapitools.client.model.CreateIndexRequestSpecPodMetadataConfig;
     ...

     CreateIndexRequestSpecPodMetadataConfig metadataConfig =
         new CreateIndexRequestSpecPodMetadataConfig()
         .fields(Arrays.asList("genre", "year"));
     client.createPodsIndex("YOUR-INDEX", 1536, "us-east4-gcp", "p1.x2", "cosine", 6);
 

Parameters:

indexName - The name of the index to be created.

dimension - The number of dimensions for the index.

environment - The cloud environment where you want the index to be hosted.

podType - The type of pod to use. A string with one of s1, p1, or p2 appended with a "." and one of x1, x2, x4, or x8.

pods - The number of pods to be used in the index.

Returns:

IndexModel representing the created serverless index.

Throws:

PineconeException - if the API encounters an error during index creation or if any of the arguments are invalid.

createPodsIndex

public IndexModel createPodsIndex(java.lang.String indexName,
                                  java.lang.Integer dimension,
                                  java.lang.String environment,
                                  java.lang.String podType,
                                  java.lang.Integer replicas,
                                  java.lang.Integer shards)

Overload for creating a new pods index with environment, podType, replicas, and shards.

Example:

     client.createPodsIndex("YOUR-INDEX", 1536, "us-east4-gcp", "p1.x2", "cosine", 2, 2);
 

Parameters:

indexName - The name of the index to be created.

dimension - The number of dimensions for the index.

environment - The cloud environment where you want the index to be hosted.

podType - The type of pod to use. A string with one of s1, p1, or p2 appended with a "." and one of x1, x2, x4, or x8.

replicas - The number of replicas. Replicas duplicate your index. They provide higher availability and throughput and can be scaled.

shards - The number of shards. Shards split your data across multiple pods so you can fit more data into an index.

Returns:

IndexModel representing the created serverless index.

Throws:

PineconeException - if the API encounters an error during index creation or if any of the arguments are invalid.

createPodsIndex

public IndexModel createPodsIndex(java.lang.String indexName,
                                  java.lang.Integer dimension,
                                  java.lang.String environment,
                                  java.lang.String podType,
                                  java.lang.Integer replicas,
                                  java.lang.Integer shards,
                                  CreateIndexRequestSpecPodMetadataConfig metadataConfig)

Overload for creating a new pods index with environment, podType, replicas, shards, and metadataConfig.

Example:

 
     import org.openapitools.client.model.CreateIndexRequestSpecPodMetadataConfig;
     ...

     CreateIndexRequestSpecPodMetadataConfig metadataConfig =
         new CreateIndexRequestSpecPodMetadataConfig()
         .fields(Arrays.asList("genre", "year"));
     client.createPodsIndex("YOUR-INDEX", 1536, "us-east4-gcp", "p1.x2", "cosine", 2, 2, metadataConfig);
 

Parameters:

indexName - The name of the index to be created.

dimension - The number of dimensions for the index.

environment - The cloud environment where you want the index to be hosted.

podType - The type of pod to use. A string with one of s1, p1, or p2 appended with a "." and one of x1, x2, x4, or x8.

replicas - The number of replicas. Replicas duplicate your index. They provide higher availability and throughput and can be scaled.

shards - The number of shards. Shards split your data across multiple pods so you can fit more data into an index.

Returns:

IndexModel representing the created serverless index.

Throws:

PineconeException - if the API encounters an error during index creation or if any of the arguments are invalid.

createPodsIndex

public IndexModel createPodsIndex(java.lang.String indexName,
                                  java.lang.Integer dimension,
                                  java.lang.String environment,
                                  java.lang.String podType,
                                  java.lang.String metric,
                                  java.lang.Integer replicas,
                                  java.lang.Integer shards,
                                  java.lang.Integer pods,
                                  CreateIndexRequestSpecPodMetadataConfig metadataConfig,
                                  java.lang.String sourceCollection)
                           throws PineconeException

Creates a new pods index with the specified parameters.

Example:

 
     import org.openapitools.client.model.CreateIndexRequestSpecPodMetadataConfig;
     ...

     CreateIndexRequestSpecPodMetadataConfig metadataConfig =
         new CreateIndexRequestSpecPodMetadataConfig()
         .fields(Arrays.asList("genre", "year"));
     client.createPodsIndex("YOUR-INDEX", 1536, "us-east4-gcp", "p1.x2", "cosine", 2, 2, 4, null, null);
 

Parameters:

indexName - The name of the index to be created.

dimension - The number of dimensions for the index.

environment - The cloud environment where you want the index to be hosted.

podType - The type of pod to use. A string with one of s1, p1, or p2 appended with a "." and one of x1, x2, x4, or x8.

metric - The metric type for the index. Must be one of "cosine", "euclidean", or "dotproduct".

replicas - The number of replicas. Replicas duplicate your index. They provide higher availability and throughput and can be scaled.

shards - The number of shards. Shards split your data across multiple pods so you can fit more data into an index.

pods - The number of pods to be used in the index. This should be equal to shards x replicas.

metadataConfig - The configuration for the behavior of Pinecone's internal metadata index. By default, all metadata is indexed; when metadataConfig is present, only specified metadata fields are indexed.

sourceCollection - The name of the collection to be used as the source for the index. Collections are snapshots of an index at a point in time.

Returns:

IndexModel representing the created serverless index.

Throws:

PineconeException - if the API encounters an error during index creation or if any of the arguments are invalid.

validatePodIndexParams

public static void validatePodIndexParams(java.lang.String indexName,
                                          java.lang.Integer dimension,
                                          java.lang.String environment,
                                          java.lang.String podType,
                                          java.lang.String metric,
                                          java.lang.Integer replicas,
                                          java.lang.Integer shards,
                                          java.lang.Integer pods)

describeIndex

public IndexModel describeIndex(java.lang.String indexName)
                         throws PineconeException

Retrieves information about an existing index.

Example:

 
     import org.openapitools.client.model.IndexModel;
     ...

     IndexModel indexModel = client.describeIndex("YOUR-INDEX");
 

Parameters:

indexName - The name of the index to describe.

Returns:

IndexModel with the details of the index.

Throws:

PineconeException - if an error occurs during the operation or the index does not exist.

configureIndex

public IndexModel configureIndex(java.lang.String indexName,
                                 java.lang.String podType,
                                 java.lang.Integer replicas)
                          throws PineconeException

Configures an existing pod-based index with new settings.

Example:

 
     import org.openapitools.client.model.IndexModel;
     ...

     // Make a configuration change
     IndexModel indexModel = client.configureIndex("YOUR-INDEX", "p1.x2", 4);

     // Call describeIndex to see the index status as the change is applied.
     indexModel = client.describeIndex("YOUR-INDEX");
 

Parameters:

indexName - The name of the index to configure.

podType - The new podType for the index. Can be null if not changing the pod type.

replicas - The desired number of replicas for the index, lowest value is 0. Can be null if not changing the number of replicas.

Returns:

IndexModel representing the configured index.

Throws:

PineconeException - if an error occurs during the operation, the index does not exist, or if any of the arguments are invalid.

configureIndex

public IndexModel configureIndex(java.lang.String indexName,
                                 java.lang.Integer replicas)
                          throws PineconeException

Overload for configureIndex to only change the number of replicas for an index.

Example:

 
     import org.openapitools.client.model.IndexModel;
     ...

     IndexModel indexModel = client.configureIndex("YOUR-INDEX", 4);
 

Parameters:

indexName - The name of the index.

replicas - The desired number of replicas for the index, lowest value is 0.

Returns:

IndexModel of the configured index.

Throws:

PineconeException - if an error occurs during the operation, the index does not exist, or if the number of replicas is invalid.

configureIndex

public IndexModel configureIndex(java.lang.String indexName,
                                 java.lang.String podType)
                          throws PineconeException

Overload for configureIndex to only change the podType of an index.

Example:

 
     import org.openapitools.client.model.IndexModel;
     ...

     IndexModel indexModel = client.configureIndex("YOUR-INDEX", "p1.x2");
 

Parameters:

indexName - The name of the index.

podType - The new podType for the index.

Returns:

IndexModel of the configured index.

Throws:

PineconeException - if an error occurs during the operation, the index does not exist, or if the podType is invalid.

listIndexes

public IndexList listIndexes()
                      throws PineconeException

Lists all indexes in your project, including the index name, dimension, metric, status, and spec.

Example:

 
     import org.openapitools.client.model.IndexList;
     ...

     IndexList indexes = client.listIndexes();
 

Returns:

IndexList containing all indexes.

Throws:

PineconeException - if an error occurs during the operation.

deleteIndex

public void deleteIndex(java.lang.String indexName)
                 throws PineconeException

Deletes an index.

Deleting an index is an irreversible operation. All data in the index will be lost. When you use this command, a request is sent to the Pinecone control plane to delete the index, but the termination is not synchronous because resources take a few moments to be released.

You can check the status of the index by calling the describeIndex command. With repeated polling of the describeIndex command, you will see the index transition to a Terminating state before eventually resulting in a 404 after it has been removed.

Example:

 
     import org.openapitools.client.model.IndexModel;
     ...

     // Delete an index
     client.deleteIndex("YOUR-INDEX");

     // Get index status with describeIndex
     IndexModel indexModel = client.describeIndex("YOUR-INDEX");
     indexModel.getStatus().getState();
 

Parameters:

indexName - The name of the index to delete.

Throws:

PineconeException - if an error occurs during the deletion operation or the index does not exist.

createCollection

public CollectionModel createCollection(java.lang.String collectionName,
                                        java.lang.String sourceIndex)
                                 throws PineconeException

Creates a new collection from a source index.

Example:

 
     import org.openapitools.client.model.CollectionModel;
     ...

     CollectionModel collection = client.createCollection("my-collection", "my-source-index");
 

Parameters:

collectionName - The name of the new collection.

sourceIndex - The name of the source index.

Returns:

CollectionModel representing the created collection.

Throws:

PineconeException - if an error occurs during the operation, or the source collection is invalid.

describeCollection

public CollectionModel describeCollection(java.lang.String collectionName)
                                   throws PineconeException

Describes an existing collection.

Example:

 
     import io.pinecone.clients.Pinecone;
     import org.openapitools.client.model.CollectionModel;
     ...

     CollectionModel collection = client.describeCollection("my-collection");
 

Parameters:

collectionName - The name of the collection to describe.

Returns:

CollectionModel with the description of the collection.

Throws:

PineconeException - if an error occurs during the operation or the collection does not exist.

listCollections

public CollectionList listCollections()
                               throws PineconeException

Lists all collections in the project.

Example:

 
     import org.openapitools.client.model.CollectionList;
     ...

     CollectionList collections = client.listCollections();
 

Returns:

CollectionList containing all collections.

Throws:

PineconeException - if an error occurs during the listing operation.

deleteCollection

public void deleteCollection(java.lang.String collectionName)
                      throws PineconeException

Deletes a collection.

Deleting a collection is an irreversible operation. All data in the collection will be lost. This method tells Pinecone you would like to delete a collection, but it takes a few moments to complete the operation. Use the describeCollection() method to confirm that the collection has been deleted.

Example:

 
     client.deleteCollection('my-collection');

     // Verify collection status with describeCollection
     client.describeCollection('my-collection');
 

Parameters:

collectionName - The name of the collection to delete.

Throws:

PineconeException - if an error occurs during the deletion operation or the collection does not exist.

getIndexConnection

public Index getIndexConnection(java.lang.String indexName)
                         throws PineconeValidationException

Retrieves a connection to a specific index for synchronous operations. This method initializes and returns an Index object that represents a connection to an index and allowing for synchronous operations against it.

Example:

 
     import io.pinecone.clients.Index;
     ...

     Index index = client.getIndexConnection("YOUR-INDEX");

     // Use the index object to interact with the index
     index.describeIndexStats();
 

Parameters:

indexName - The name of the index to connect to. Must not be null or empty.

Returns:

An Index object representing the connection to the specified index.

Throws:

PineconeValidationException - If the indexName is null or empty.

getAsyncIndexConnection

public AsyncIndex getAsyncIndexConnection(java.lang.String indexName)
                                   throws PineconeValidationException

Retrieves a connection to a specific index for asynchronous operations. This method initializes and returns an AsyncIndex object that represents a connection to an index and allowing for synchronous operations against it.

Example:

 
     import io.pinecone.clients.AsyncIndex;
     ...

     AsyncIndex asyncIndex = client.getAsyncIndexConnection("YOUR-INDEX");

     // Use the index object to interact with the index
     asyncIndex.describeIndexStats();
 

Parameters:

indexName - The name of the index to connect to. Must not be null or empty.

Returns:

An AsyncIndex object representing the connection to the specified index.

Throws:

PineconeValidationException - If the indexName is null or empty.