Skip to content

Release v7.0.0

Latest
Latest

Choose a tag to compare

View all tags
@austin-denoble austin-denoble released this 28 Sep 18:46
v7.0.0
2f0e86e

This version of the Pinecone Go SDK depends on version 2026-07 of the Pinecone API. You can read more about versioning here. The v6 release line continues to target 2026-04.

go get github.com/pinecone-io/go-pinecone/v7/pinecone

The primary additions in this release are schema-defined indexes and the Documents API, which together bring full-text search to the Go SDK.

Upgrading from v6

If your workload upserts and queries an existing index, upgrading doesn't change what your code means generally. UpsertVectors, QueryByVectorValues, QueryByVectorId, FetchVectors, UpdateVector, DeleteVectorsById, DeleteVectorsByFilter, ListVectors, DescribeIndexStats, and the rest of the vector operations take the same arguments and return the same types they did in v6, as do UpsertRecords and SearchRecords for indexes created with a model. pc.Index(...) still returns an *IndexConnection, and the new document operations are exposed on that connmection. None of the vector operation are deprecated, and indexes you created before 2026-07 go on being served by them. Apart from the /v7 import path, three things change on that path: some invalid requests now fail locally instead of being refused by the server, QueryByVectorIdRequest.SparseValues is removed, and Client.Index returns an error instead of exiting the process when the gRPC client can't be created.

The breaking changes are concentrated in creating and configuring indexes: pod-based index creation is removed, a few legacy create and configure parameters now return an error, and enum constants such as Cosine and Ready are renamed with their type as a prefix. CreateServerlessIndex, CreateBYOCIndex, and CreateIndexForModel need no edits beyond the renamed constants. They keep their signatures and create the same kind of index they did before. Which operations serve an index depends on the index, not the SDK version. An index created with those methods uses the vector operations, even when v7 creates it. An index created with CreateIndex and a document schema uses the document operations.

Features

Schema-defined indexes

An index is now described by a schema, the typed fields it declares, and a deployment, where it runs. The new Client.CreateIndex creates an index from an explicit IndexSchema, with an optional IndexDeployment (defaults to serverless on AWS in us-east-1). At creation you can declare:

Field type Stores Limit
DenseVectorField Fixed-dimension dense vectors, with a Dimension and Metric 1 per index
SparseVectorField Sparse vectors 1 per index
StringField with FullTextSearch Text indexed for BM25 full-text search 100 per index

Metadata fields don't need to be declared. They're indexed automatically when you upsert data.

idx, err := pc.CreateIndex(ctx, &pinecone.CreateIndexRequest{
	Name: "articles",
	Schema: pinecone.IndexSchema{
		Fields: map[string]pinecone.IndexSchemaField{
			"title": {String: &pinecone.StringField{FullTextSearch: &pinecone.FullTextSearchConfig{}}},
			"body":  {String: &pinecone.StringField{FullTextSearch: &pinecone.FullTextSearchConfig{}}},
		},
	},
})

A schema can combine text and vector fields in one document index:

Schema: pinecone.IndexSchema{
	Fields: map[string]pinecone.IndexSchemaField{
		"embedding":    {DenseVector: &pinecone.DenseVectorField{Dimension: 1536, Metric: pinecone.IndexMetricDotproduct}},
		"sparse_terms": {SparseVector: &pinecone.SparseVectorField{}},
		"body":         {String: &pinecone.StringField{FullTextSearch: &pinecone.FullTextSearchConfig{}}},
	},
},

FullTextSearchConfig controls text analysis per field: Language, Stemming, StopWords, and character Ngram tokenization for substring and prefix matching.

Index gains Schema, Deployment, ReadCapacity, and related fields. CreateServerlessIndex, CreateBYOCIndex, and CreateIndexForModel keep their signatures and create the same vector and integrated-embedding indexes as before.

Documents API

Indexes with a document schema are read and written through six new IndexConnection methods:

Method Description
UpsertDocuments Write documents, replacing any with the same _id
SearchDocuments Rank documents with full-text, query-string, dense vector, or sparse vector scoring
FetchDocuments Retrieve documents by ID or by filter
UpdateDocuments Patch fields by ID, or on every document that matches a filter
DeleteDocuments Delete by ID, by filter, or all at once
ListDocuments List document IDs, optionally by prefix

A Document is a map[string]interface{} with an "_id" and at least one schema field. Any other field is stored as filterable metadata.

_, err = idxConnection.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{
	Documents: []pinecone.Document{
		{"_id": "doc-1", "title": "Apple orchards", "body": "Apple trees are grown in orchards across the world.", "year": 2021},
		{"_id": "doc-2", "title": "Citrus groves", "body": "Oranges and lemons grow in warm climates.", "year": 2023},
		{"_id": "doc-3", "title": "Orchard pests", "body": "Codling moths are a common pest in apple orchards.", "year": 2024},
	},
})

query := "apple orchards"
res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
	TopK: 3,
	ScoreBy: []pinecone.DocumentScoringMethod{
		{Type: "text", Fields: []string{"title", "body"}, Query: &query},
	},
	IncludeFields: []string{"title"},
})
for _, match := range res.Matches {
	fmt.Printf("%s: %v\n", match.Id, match.Fields["title"])
}

ScoreBy supports four scoring types: "text" (BM25), "query_string" (Lucene syntax), "dense_vector", and "sparse_vector". Search and fetch filters accept the text-match operators $match_phrase, $match_all, and $match_any alongside the usual metadata operators. For example, you can rank by vector similarity while requiring a phrase:

res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
	TopK: 10,
	ScoreBy: []pinecone.DocumentScoringMethod{
		{Type: "dense_vector", Fields: []string{"embedding"}, Values: &queryVector},
	},
	Filter: map[string]interface{}{
		"body": map[string]interface{}{"$match_phrase": "apple orchards"},
	},
})

See Working with documents and Indexes for the full guides.

Breaking changes

v7 targets API version 2026-07, and a few APIs changed with it:

  • Module path is now github.com/pinecone-io/go-pinecone/v7.
  • Pod-based index creation is removed (CreatePodIndex, CreatePodIndexRequest). Existing pod-based indexes keep working.
  • Enum constants are prefixed with their type name, for example Aws → CloudAWS and Cosine → IndexMetricCosine.
  • Signature changes: ListImports takes a *ListImportsRequest, and QueryByVectorIdRequest.SparseValues is removed.
  • Unsupported parameters now return an error: SourceCollection and Schema on the legacy create requests, and ConfigureIndexParams.Embed, which is replaced by ConfigureIndexParams.Schema.
  • Backup field types changed, some invalid requests now fail client-side, and a few behaviors changed without a signature change.

See the v7 migration guide for details and before-and-after examples.

Other changes

  • The README is now a short overview with quickstarts. Detailed usage lives in the guides/ directory, and the quickstarts are also on pkg.go.dev.
  • google.golang.org/grpc is updated to v1.84.0, which resolves several gRPC-Go security advisories.

What's Changed

  • Implement API 2026-07 with schema-defined indexes, the Documents API, and full-text search, building on the upgrade work by @joerg84 in #169. Also adds client-side validation, AdminClient token refresh, and a ReadCapacity option on CreateIndexFromBackup (e28f365) by @austin-denoble
  • Restructure and correct doc comments across the package so field docs render on pkg.go.dev and match API behavior (5fea0ff) by @austin-denoble
  • Bump the module path to /v7 (8d32117) by @austin-denoble
  • Rewrite the README around quickstarts, move detailed usage into guides/, add a documents guide and the v7 migration guide, and add the quickstarts as package examples (cd413f7) by @austin-denoble
  • Bump Go dependencies, including google.golang.org/grpc to v1.84.0 and google.golang.org/protobuf to v1.36.12 (a80f15b) by @dependabot
  • Fix the returnDocuments variable spelling in the rerank tests by @fmterrors, from #171 (fcbd37b)
  • chore: add CODEOWNERS by @jhamon in #164
  • Drop a stale link from the README (3c55b68) by @joerg84

New Contributors

Full Changelog: v6.1.0...v7.0.0

Contributors

jhamon, joerg84, and 3 other contributors
Assets 2
Loading