Merge branch 2025-04 to main for release

README.md

@@ -588,8 +588,10 @@ Pinecone indexes support working with vector data using operations such as upser
 
 ### Targeting an index
 
-To perform data operations on an index, you target it using the `Index` method on a `Client` object. You will
-need your index's `Host` value, which you can retrieve via `DescribeIndex` or `ListIndexes`.
+To perform data operations on an index, you target it using the `Index` method on a `Client` object which returns a pointer to an `IndexConnection`. Calling `Index` will create and dial the index via a new gRPC connection. You can target a specific `Namespace` when calling `Index`, but if you want to reuse the connection with different namespaces, you can call `IndexConnection.WithNamespace`. If no `Namespace` is provided when establishing a new
+`IndexConnection`, the default of `"__default__"` will be used.
+
+You will need your index's `Host` value, which you can retrieve via `DescribeIndex` or `ListIndexes`.
 
 ```go
 package main
@@ -628,9 +630,57 @@ func main() {
 }
 ```
 
+### Working with namespaces
+
+Within an index, records are partitioned into namespaces, and all upserts, queries, and other data operations always target one namespace. You can read more about [namespaces here](https://docs.pinecone.io/guides/index-data/indexing-overview#namespaces).
+
+You can list all namespaces in an index in a paginated format, describe a specific namespace, or delete a namespace. NOTE: Deleting a namespace will delete all record information partitioned in that namespace.
+
+```go
+	ctx := context.Background()
+
+	pc, err := pinecone.NewClient(pinecone.NewClientParams{
+		ApiKey:    "YOUR_API_KEY",
+	})
+	if err != nil {
+		log.Fatalf("Failed to create Client: %v", err)
+	}
+
+	idx, err := pc.DescribeIndex(ctx, "example-index")
+	if err != nil {
+		log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err)
+	}
+
+	idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host})
+	if err != nil {
+		log.Fatalf("Failed to create IndexConnection for Host: %v: %v", idx.Host, err)
+	}
+
+	// list namespaces
+	limit := uint32(10)
+	namespaces, err := idxConnection.ListNamespaces(ctx, &pinecone.ListNamespacesParams{
+		Limit: &limit,
+	})
+	if err != nil {
+		log.Fatalf("Failed to list namespaces for Host: %v: %v", idx.Host, err)
+	}
+
+	// describe a namespace
+	namespace1, err := idxConnection.DescribeNamespace(ctx, "my-namespace-1")
+	if err != nil {
+		log.Fatalf("Failed to describe namespace: %v: %v", "my-namespace-1", err)
+	}
+
+	// delete a namespace
+	err := idxConnection.DeleteNamespace("my-namespace-1")
+	if err != nil {
+		log.Fatalf("Failed to delete namespace: %v: %v", "my-namespace-1", err)
+	}
+```
+
 ### Upsert vectors
 
-The following example upserts dense vectors and metadata to `example-index`.
+The following example upserts dense vectors and metadata to `example-index` in the namespace `my-namespace`. Upserting to a specific `Namespace` will implicitly create the namespace if it does not exist already.
 
 ```go
 package main
@@ -663,7 +713,7 @@ func main() {
 		log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err)
 	}
 
-	idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host})
+	idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "my-namespace"})
 	if err != nil {
 		log.Fatalf("Failed to create IndexConnection for Host: %v: %v", idx.Host, err)
 	}
@@ -1580,12 +1630,73 @@ func main() {
 }
 ```
 
+## Backups
+
+A backup is a static copy of a serverless index that only consumes storage. It is a non-queryable representation of a set of records. You can create a backup of a serverless index, and you can create a new serverless index from a backup. You can optionally apply new `Tags` and `DeletionProtection` configurations for the index when calling `CreateIndexFromBackup`. You can read more about [backups here](https://docs.pinecone.io/guides/manage-data/backups-overview).
+
+```go
+	ctx := context.Background()
+
+	clientParams := pinecone.NewClientParams{
+		ApiKey: os.Getenv("PINECONE_API_KEY"),
+	}
+
+	pc, err := pinecone.NewClient(clientParams)
+	if err != nil {
+		log.Fatalf("Failed to create Client: %w", err)
+	}
+
+	indexName := "my-index"
+	backupName := fmt.Sprintf("backup-%s", )
+	backupDesc := fmt.Sprintf("Backup created for index %s", indexName)
+	fmt.Printf("Creating backup: %s for index: %s\n", backupName, indexName)
+
+	backup, err := pc.CreateBackup(ctx, &pinecone.CreateBackupParams{
+		IndexName:   indexName,
+		Name:        &backupName,
+		Description: &backupDesc,
+	})
+	if err != nil {
+		log.Fatalf("Failed to create backup: %w", err)
+	}
+
+	backup, err = pc.DescribeBackup(ctx, backup.BackupId)
+	if err != nil {
+		log.Fatalf("Failed to describe backup: %w", err)
+	}
+
+	// wait for backup to be "Complete" before triggering a restore job
+	log.Printf("Backup status: %v", backup.Status)
+
+	limit := 10
+	backups, err := pc.ListBackups(ctx, &pinecone.ListBackupsParams{
+		Limit: &limit,
+		IndexName: &indexName,
+	})
+	if err != nil {
+		log.Fatalf("Failed to list backups: %w", err)
+	}
+
+	// create a new serverless index from the backup
+	restoredIndexName := indexName + "-from-backup"
+	restoredIndexTags := pinecone.IndexTags{"restored_on": time.Now().Format("2006-01-02 15:04")}
+	createIndexFromBackupResp, err := pc.CreateIndexFromBackup(context.Background(), &pinecone.CreateIndexFromBackupParams{
+		BackupId: ts.backupId,
+		Name:     restoredIndexName,
+		Tags:     &restoredIndexTags,
+	})
+
+	// check the status of the index restoration
+	restoreJob, err := pc.DescribeRestoreJob(ctx, restoreJob.RestoreJobId)
+	if err != nil {
+		log.Fatalf("Failed to describe restore job: %w", err)
+	}
+```
+
 ## Inference
 
-The `Client` object has an `Inference` namespace which allows interacting with
-Pinecone's [Inference API](https://docs.pinecone.io/guides/inference/generate-embeddings). The Inference
-API is a service that gives you access to embedding models hosted on Pinecone's infrastructure. Read more
-at [Understanding Pinecone Inference](https://docs.pinecone.io/guides/inference/understanding-inference).
+The `Client` object has an `Inference` namespace which exposes an `InferenceService` pointer which allows interacting with Pinecone's [Inference API](https://docs.pinecone.io/guides/inference/generate-embeddings).
+The Inference API is a service that gives you access to embedding models hosted on Pinecone's infrastructure. Read more at [Understanding Pinecone Inference](https://docs.pinecone.io/guides/inference/understanding-inference).
 
 ### Create Embeddings
 
@@ -1699,6 +1810,60 @@ indicating higher relevance.
     fmt.Printf("rerank response: %+v", rerankResponse)
 ```
 
+### Hosted Models
+
+To see available models hosted by Pinecone, you can use the `DescribeModel` and `ListModels` methods on the `InferenceService` struct. This allows you to retrieve detailed information about specific models.
+
+You can list all available models, with the options of filtering by model `Type` (`"embed"`, `"rerank"`), and `VectorType` (`"sparse"`, `"dense"`) for models with `Type` `"embed"`.
+
+```go
+	ctx := context.Background()
+
+	pc, err := pinecone.NewClient(pinecone.NewClientParams{
+		ApiKey:    "YOUR_API_KEY",
+	})
+	if err != nil {
+		log.Fatalf("Failed to create Client: %v", err)
+	}
+
+	embed := "embed"
+	rerank := "rerank"
+
+	embedModels, err := pc.Inference.ListModels(ctx, &pinecone.ListModelsParams{
+		Type: &embed,
+	})
+	if err != nil {
+		log.Fatalf("Failed to list embedding models: %v", err)
+	}
+
+	rerankModels, err := pc.Inference.ListModels(ctx, &pinecone.ListModelsParams{
+		Type: &rerank,
+	})
+	if err != nil {
+		log.Fatalf("Failed to list reranking models: %v", err)
+	}
+```
+
+You can also describe a single model by name:
+
+```go
+	ctx := context.Background()
+
+	pc, err := pinecone.NewClient(pinecone.NewClientParams{
+		ApiKey:    "YOUR_API_KEY",
+	})
+	if err != nil {
+		log.Fatalf("Failed to create Client: %v", err)
+	}
+
+	model, err := pc.Inference.DescribeModel(ctx, "multilingual-e5-large")
+	if err != nil {
+		log.Fatalf("Failed to get model: %v", err)
+	}
+
+	fmt.Printf("Model (multilingual-e5-large): %+v\n", model)
+```
+
 ### Integrated Inference
 
 When using an index with integrated inference, embedding and reranking operations are tied to index operations and do not require extra steps. This allows working with an index that accepts source text and converts it to vectors automatically using an embedding model hosted by Pinecone.

go.mod

@@ -1,4 +1,4 @@
-module github.com/pinecone-io/go-pinecone/v3
+module github.com/pinecone-io/go-pinecone/v4
 
 go 1.21
 
@@ -16,7 +16,7 @@ require (
 	github.com/apapsch/go-jsonmerge/v2 v2.0.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	golang.org/x/net v0.33.0 // indirect
+	golang.org/x/net v0.35.0 // indirect
 	golang.org/x/sys v0.30.0 // indirect
 	golang.org/x/text v0.22.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20240528184218-531527333157 // indirect

go.sum

@@ -19,8 +19,8 @@ github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-golang.org/x/net v0.33.0 h1:74SYHlV8BIgHIFC/LrYkOGIwL19eTYXQ5wc6TBuO36I=
-golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4=
+golang.org/x/net v0.35.0 h1:T5GQRQb2y08kTAByq9L4/bz8cipCdA8FbRTXewonqY8=
+golang.org/x/net v0.35.0/go.mod h1:EglIi67kWsHKlRzzVMUD93VMSWGFOMSZgxFjparz1Qk=
 golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc=
 golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/text v0.22.0 h1:bofq7m3/HAFvbF51jz3Q9wLg3jkvSPuiZu/pD1XwgtM=