diff --git a/README.md b/README.md index 0d158189..44e74176 100644 --- a/README.md +++ b/README.md @@ -348,6 +348,58 @@ String podType = "p1.x1"; IndexModel indexModel = pinecone.createPodsIndex(indexName, dimension, environment, podType, "enabled"); ``` +### Create a BYOC index + +The following is an example of creating a BYOC (Bring Your Own Cloud) index. BYOC indexes allow you to deploy Pinecone indexes in your own cloud infrastructure. You must have a BYOC environment set up with Pinecone before creating a BYOC index. The BYOC environment name is provided during BYOC onboarding. + +```java +import io.pinecone.clients.Pinecone; +import org.openapitools.db_control.client.model.IndexModel; +... + +Pinecone pinecone = new Pinecone.Builder("PINECONE_API_KEY").build(); + +String indexName = "example-index"; +String similarityMetric = "cosine"; +int dimension = 1538; +String byocEnvironment = "your-byoc-environment"; + +IndexModel indexModel = pinecone.createByocIndex(indexName, similarityMetric, dimension, byocEnvironment); +``` + +### Create a BYOC index with metadata schema + +The following example creates a BYOC index with metadata schema configuration to limit metadata indexing to specific fields for improved performance. + +```java +import io.pinecone.clients.Pinecone; +import org.openapitools.db_control.client.model.IndexModel; +import org.openapitools.db_control.client.model.BackupModelSchema; +import org.openapitools.db_control.client.model.BackupModelSchemaFieldsValue; +import java.util.HashMap; +import java.util.Map; +... + +Pinecone pinecone = new Pinecone.Builder("PINECONE_API_KEY").build(); + +String indexName = "example-index"; +String similarityMetric = "cosine"; +int dimension = 1538; +String byocEnvironment = "your-byoc-environment"; +HashMap tags = new HashMap<>(); +tags.put("env", "production"); + +// Configure metadata schema +Map fields = new HashMap<>(); +fields.put("genre", new BackupModelSchemaFieldsValue().filterable(true)); +fields.put("year", new BackupModelSchemaFieldsValue().filterable(true)); +fields.put("description", new BackupModelSchemaFieldsValue().filterable(true)); +BackupModelSchema schema = new BackupModelSchema().fields(fields); + +IndexModel indexModel = pinecone.createByocIndex( + indexName, similarityMetric, dimension, byocEnvironment, "enabled", tags, schema); +``` + ## List indexes The following example returns all indexes (and their corresponding metadata) in your project. diff --git a/src/main/java/io/pinecone/clients/Pinecone.java b/src/main/java/io/pinecone/clients/Pinecone.java index a33e7e6f..ef3d953f 100644 --- a/src/main/java/io/pinecone/clients/Pinecone.java +++ b/src/main/java/io/pinecone/clients/Pinecone.java @@ -411,6 +411,114 @@ public IndexModel createIndexForModel(String name, return manageIndexesApi.createIndexForModel(Configuration.VERSION, createIndexForModelRequest); } + /** + * Creates a new BYOC (Bring Your Own Cloud) index with minimal required parameters. + *

+ * BYOC indexes allow you to deploy Pinecone indexes in your own cloud infrastructure. + * You must have a BYOC environment set up with Pinecone before creating a BYOC index. + *

+ * Example: + *

{@code
+     *     client.createByocIndex("YOUR-INDEX", "cosine", 1536, "your-byoc-environment");
+     * }
+ * + * @param indexName The name of the index to be created. + * @param metric The metric type for the index. Must be one of "cosine", "euclidean", or "dotproduct". + * @param dimension The number of dimensions for the index. + * @param environment The BYOC environment where the index will be hosted. This is provided during BYOC onboarding. + * @return {@link IndexModel} representing the created BYOC index. + * @throws PineconeException if the API encounters an error during index creation or if any of the arguments are invalid. + */ + public IndexModel createByocIndex(String indexName, + String metric, + int dimension, + String environment) throws PineconeException { + return createByocIndex(indexName, metric, dimension, environment, "disabled", null, null); + } + + /** + * Creates a new BYOC (Bring Your Own Cloud) index with the specified parameters, including optional deletion protection, tags, and metadata schema configuration. + *

+ * BYOC indexes allow you to deploy Pinecone indexes in your own cloud infrastructure. + * You must have a BYOC environment set up with Pinecone before creating a BYOC index. + *

+ * Example with metadata schema: + *

{@code
+     *     import org.openapitools.db_control.client.model.BackupModelSchema;
+     *     import org.openapitools.db_control.client.model.BackupModelSchemaFieldsValue;
+     *     ...
+     *
+     *     Map fields = new HashMap<>();
+     *     fields.put("genre", new BackupModelSchemaFieldsValue().filterable(true));
+     *     fields.put("year", new BackupModelSchemaFieldsValue().filterable(true));
+     *     BackupModelSchema schema = new BackupModelSchema().fields(fields);
+     *     client.createByocIndex("YOUR-INDEX", "cosine", 1536, "aws-us-east-1-b921",
+     *                            DeletionProtection.ENABLED, null, schema);
+     * }
+ * + * @param indexName The name of the index to be created. + * @param metric The metric type for the index. Must be one of "cosine", "euclidean", or "dotproduct". + * @param dimension The number of dimensions for the index. + * @param environment The BYOC environment where the index will be hosted. This is provided during BYOC onboarding. + * @param deletionProtection Enable or disable deletion protection for the index. + * @param tags A map of tags to associate with the Index. + * @param schema The metadata schema configuration. If null, all metadata fields are indexed. + * Use this to limit metadata indexing to specific fields for improved performance. + * @return {@link IndexModel} representing the created BYOC index. + * @throws PineconeException if the API encounters an error during index creation or if any of the arguments are invalid. + */ + public IndexModel createByocIndex(String indexName, + String metric, + int dimension, + String environment, + String deletionProtection, + Map tags, + BackupModelSchema schema) throws PineconeException { + if (indexName == null || indexName.isEmpty()) { + throw new PineconeValidationException("Index name cannot be null or empty"); + } + + if (metric == null || metric.isEmpty()) { + metric = "cosine"; + } + + if (dimension < 1) { + throw new PineconeValidationException("Dimension must be greater than 0. See limits for more info: https://docs.pinecone.io/reference/limits"); + } + + if (environment == null || environment.isEmpty()) { + throw new PineconeValidationException("Environment cannot be null or empty"); + } + + ByocSpec byocSpec = new ByocSpec().environment(environment); + + if (schema != null) { + byocSpec.schema(schema); + } + + IndexSpec createByocIndexRequestSpec = new IndexSpec(new IndexSpecBYOC().byoc(byocSpec)); + + IndexModel indexModel = null; + + try { + CreateIndexRequest createIndexRequest = new CreateIndexRequest() + .name(indexName) + .metric(metric) + .dimension(dimension) + .spec(createByocIndexRequestSpec) + .deletionProtection(deletionProtection); + + if(tags != null && !tags.isEmpty()) { + createIndexRequest.tags(tags); + } + + indexModel = manageIndexesApi.createIndex(Configuration.VERSION, createIndexRequest); + } catch (ApiException apiException) { + handleApiException(apiException); + } + return indexModel; + } + /** * Overload for creating a new pods index with environment and podType, the minimum required parameters. *