Pinecone Go SDK ·

The Pinecone Go SDK is the official Go client for Pinecone Database.

Features

• Documents API: Full-text search, query strings, and vector search over indexes with a document schema.
• Integrated embedding: Have Pinecone embed document text with hosted models, so you can search by meaning without managing vectors.
• Vectors API: Upsert, query, fetch, update, delete, and list records in vector indexes over gRPC.
• Legacy Records API: Upsert and search text in legacy integrated indexes created with CreateIndexForModel.
• Index management: Create, configure, and delete indexes, and manage backups, collections, and namespaces.
• Inference API: Generate embeddings and rerank results with models hosted by Pinecone.
• Admin API: Manage projects, organizations, API keys, service accounts, role bindings, invites, and users.
• Retries: Optional automatic retries with exponential backoff.

The SDK targets Pinecone API version 2026-07, covering the control plane, data plane, Inference, and Admin APIs. For the API reference, see Pinecone API.

Documentation

• Guides: detailed usage guides for each area of the SDK
• API reference for the latest release, or for main
• Pinecone documentation

If you're upgrading from v6 or earlier, see the v7 migration guide. v7 moves to API version 2026-07, which adds document indexes and removes the ability to create pod-based indexes.

Prerequisites

• Go 1.25 or later
• A Pinecone API key. Sign up at app.pinecone.io, then set the key as the PINECONE_API_KEY environment variable.

Installation

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

To upgrade to the latest version:

go get -u github.com/pinecone-io/go-pinecone/v7/pinecone@latest

Quickstart

These quickstarts are also on pkg.go.dev as package examples, which are compiled with the SDK's tests.

Full-text search

The following program creates a document index with two full-text-search fields, upserts documents, and searches them:

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/pinecone-io/go-pinecone/v7/pinecone"
)

func main() {
	ctx := context.Background()

	// Reads the API key from the PINECONE_API_KEY environment variable.
	pc, err := pinecone.NewClient(pinecone.NewClientParams{})
	if err != nil {
		log.Fatalf("Failed to create Client: %v", err)
	}

	_, 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{}}},
			},
		},
	})
	if err != nil {
		log.Fatalf("Failed to create index: %v", err)
	}

	idx := waitUntilReady(ctx, pc, "articles")

	idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "example-namespace"})
	if err != nil {
		log.Fatalf("Failed to create IndexConnection: %v", err)
	}
	defer idxConnection.Close()

	_, 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},
		},
	})
	if err != nil {
		log.Fatalf("Failed to upsert documents: %v", err)
	}

	// Documents are indexed asynchronously and can take up to a minute to become searchable.
	time.Sleep(30 * time.Second)

	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"},
	})
	if err != nil {
		log.Fatalf("Failed to search documents: %v", err)
	}
	for _, match := range res.Matches {
		fmt.Printf("%s: %v\n", match.Id, match.Fields["title"])
	}
}

// waitUntilReady polls DescribeIndex until the index is ready to serve requests.
func waitUntilReady(ctx context.Context, pc *pinecone.Client, name string) *pinecone.Index {
	for {
		idx, err := pc.DescribeIndex(ctx, name)
		if err != nil {
			log.Fatalf("Failed to describe index: %v", err)
		}
		if idx.Status != nil && idx.Status.Ready {
			return idx
		}
		time.Sleep(5 * time.Second)
	}
}

For query strings, vector fields, filtering, and the other document operations, see Working with documents.

Bring your own vectors

The following example creates a vector index, upserts records with vectors you've generated, and queries by similarity. It reuses the client setup and waitUntilReady from the example above.

metric := pinecone.IndexMetricCosine
dimension := int32(3)

_, err = pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
	Name:      "docs-example",
	Cloud:     pinecone.CloudAWS,
	Region:    "us-east-1",
	Metric:    &metric,
	Dimension: &dimension,
})
if err != nil {
	log.Fatalf("Failed to create index: %v", err)
}

idx := waitUntilReady(ctx, pc, "docs-example")

idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "example-namespace"})
if err != nil {
	log.Fatalf("Failed to create IndexConnection: %v", err)
}
defer idxConnection.Close()

_, err = idxConnection.UpsertVectors(ctx, []*pinecone.Vector{
	{Id: "A", Values: &[]float32{0.1, 0.2, 0.3}},
	{Id: "B", Values: &[]float32{0.3, 0.2, 0.1}},
})
if err != nil {
	log.Fatalf("Failed to upsert vectors: %v", err)
}

res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{
	Vector: []float32{0.1, 0.2, 0.3},
	TopK:   2,
})
if err != nil {
	log.Fatalf("Failed to query: %v", err)
}
for _, match := range res.Matches {
	fmt.Printf("%s: %f\n", match.Vector.Id, match.Score)
}

For metadata, filtering, and the other vector operations, see Working with vectors.

Integrated embedding

Document indexes support fields with integrated embedding: Pinecone embeds a string field's text with a hosted model when you upsert, and embeds your query text when you search, so you never handle the vectors yourself. The following example declares Embed on the body field. It reuses the client setup and waitUntilReady from the full-text search example.

_, err = pc.CreateIndex(ctx, &pinecone.CreateIndexRequest{
	Name: "embedded-articles",
	Schema: pinecone.IndexSchema{
		Fields: map[string]pinecone.IndexSchemaField{
			"body": {String: &pinecone.StringField{Embed: &pinecone.EmbedConfig{}}},
		},
	},
})
if err != nil {
	log.Fatalf("Failed to create index: %v", err)
}

idx := waitUntilReady(ctx, pc, "embedded-articles")

idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "example-namespace"})
if err != nil {
	log.Fatalf("Failed to create IndexConnection: %v", err)
}
defer idxConnection.Close()

_, err = idxConnection.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{
	Documents: []pinecone.Document{
		{"_id": "doc-1", "body": "Apples are a great source of dietary fiber.", "category": "nutrition"},
		{"_id": "doc-2", "body": "The Apple I was released in 1976.", "category": "product"},
	},
})
if err != nil {
	log.Fatalf("Failed to upsert documents: %v", err)
}

// Documents are indexed asynchronously and can take up to a minute to become searchable.
time.Sleep(30 * time.Second)

query := "healthy snacks"
res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
	TopK: 2,
	ScoreBy: []pinecone.DocumentScoringMethod{
		{Type: pinecone.DocumentScoringTypeEmbed, Fields: []string{"body"}, Query: &query},
	},
	IncludeFields: []string{"body"},
})
if err != nil {
	log.Fatalf("Failed to search documents: %v", err)
}
for _, match := range res.Matches {
	fmt.Printf("%s: %v\n", match.Id, match.Fields["body"])
}

The text is also stored and indexed for full-text search, so the same field supports text scoring. Set SparseEmbed on the field for sparse embeddings. For the full set of options, see Integrated embedding.

Indexes created with CreateIndexForModel are legacy integrated indexes, which require the legacy Records API (UpsertRecords and SearchRecords). See Legacy integrated indexes.

Guides

• Client configuration: API keys, custom headers, retries, and targeting an index
• Index management
  • Indexes: schemas, deployments, read capacity, and configuring indexes
  • Backups
  • Collections
• Data operations
  • Working with documents
  • Working with vectors
  • Namespaces
  • Bulk import
• Inference
  • Inference API: embeddings, reranking, and hosted models
  • Legacy integrated indexes: indexes created with CreateIndexForModel, and the legacy Records API
• Admin API
• v7 migration guide

Support

To get help with the Pinecone Go SDK, file an issue on GitHub, visit the community forum, or open a support ticket.

Contributing

See CONTRIBUTING.md for development setup and guidelines.