Documentation
¶
Overview ¶
Package pinecone exposes Pinecone through the Core vector-store capability interfaces. Documents are stored as vectors in a Pinecone index (`{id, values, metadata}`); retrieval runs the index's similarity query. Documents containing media are rejected before indexing I/O because this adapter persists document text and metadata only.
Metadata numbers use Pinecone's double representation only when their decimal value survives JSON round-tripping. Unrepresentable values are rejected before upsert rather than rounded or converted to strings.
Requirements: a Pinecone account and an existing index (created via the Pinecone console or control-plane API — Pinecone does not allow lazy index creation from the data plane). The store uses the official pinecone-io/go-pinecone v4 client.
Vector similarity. Pinecone configures cosine / dotproduct / euclidean at index-creation time; the store reads but does not override. Because the metric decides what a raw score means, NewStore reads the index's own metric from the control plane and refuses a configured value that disagrees with ErrIncompatibleIndex — a mismatch would otherwise return scores that are wrong rather than absent, with MinScore filtering by the wrong direction.
A key with custom permissions may be denied the control plane, which Pinecone documents as the reason a caller "must target your index by host when performing data operations" — the shape StoreConfig.IndexHost already has. Construction does not demand that permission: an authorization denial leaves the configured metric unverified, while any other failure is reported. Dimensionality is never compared: this store declares none, and Pinecone rejects a wrong-width vector on the first request.
Filter visitor produces Pinecone's metadata-filter syntax — `{"author": {"$eq": "Alice"}}`, `{"$and": [...]}`, `{"$in": [...]}`. The result feeds the `Filter` field of the query request. Pinecone has no native LIKE / regex; the visitor rejects filter.OpLike expressions explicitly.
Document text. Pinecone itself stores only id + vector + flat metadata — there is no first-class text body. The store always stashes the original document text under a reserved metadata key; retrieval reverses the mapping back into document.Document.Text.
Upsert acknowledgment. Pinecone answers an upsert with the number of vectors it accepted; Index requires that count to match what it sent rather than treating a short write as a complete one.
Filtered deletion is a pod-based index capability. Serverless and starter indexes reject a metadata filter, and that rejection surfaces as an error instead of an empty match set; compose deletion from DeleteIDs there.
Null tests map to $exists. Pinecone metadata holds strings, numbers, booleans and string lists, so a key is either present with a value or absent and there is no stored null — which makes $exists: false exactly the filter AST's IS NULL, and $exists: true its negation.
Operation limits. A query returns at most MaxTopK results and one upsert carries at most MaxVectorsPerUpsert records. Index splits a larger batch rather than sending a request certain to be rejected; Search refuses a larger TopK locally, because that one cannot be split. Pinecone also caps an upsert request at 2 MB, which a record count cannot predict, so that limit surfaces as a provider error.
Lifecycle. The store implements vectorstore.Closer because it creates a resource of its own: construction opens an index connection through Client.Index, and Close releases that connection rather than the caller's client. The client stays the caller's to close.
See https://docs.pinecone.io/ for the full API surface.
Index ¶
- Constants
- Variables
- type DistanceMetric
- type Store
- func (s *Store) Close() error
- func (s *Store) DeleteIDs(ctx context.Context, ids []string) (err error)
- func (s *Store) DeleteWhere(ctx context.Context, expr filter.Predicate) (err error)
- func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
- func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
- type StoreConfig
Constants ¶
const ( // MaxTopK is the largest number of results one query may return. MaxTopK = 10_000 // MaxVectorsPerUpsert is the largest number of records one upsert may // carry. Pinecone also caps the request at 2 MB, which the store cannot // predict from the record count alone; that limit surfaces as an error. MaxVectorsPerUpsert = 1_000 )
Documented Pinecone operation limits. A request past either of them is rejected by the service, so the store either splits the work or refuses locally instead of sending one that cannot succeed.
const (
Provider = "Pinecone"
)
Provider is the stable backend name for host-side attribution.
Variables ¶
var ( ErrMissingClient = errors.New("pinecone: Client is required") ErrMissingIndexHost = errors.New("pinecone: IndexHost is required") ErrMissingEmbeddingModel = errors.New("pinecone: EmbeddingModel is required") ErrMissingDocumentBatcher = errors.New("pinecone: DocumentBatcher is required") ErrMissingDistanceMetric = errors.New("pinecone: DistanceMetric is required") // ErrIncompatibleIndex reports an index that is not the one the store was // configured for: either nothing is served at IndexHost, or the index // there was created with a different distance metric. ErrIncompatibleIndex = errors.New("pinecone: index is incompatible") )
Functions ¶
This section is empty.
Types ¶
type DistanceMetric ¶
type DistanceMetric string
DistanceMetric records the similarity metric configured on the existing Pinecone index. The data-plane connection does not expose index metadata, so the value is declared here and checked against the control plane at construction.
const ( DistanceCosine DistanceMetric = "cosine" DistanceDot DistanceMetric = "dotproduct" DistanceEuclidean DistanceMetric = "euclidean" )
The metric is a closed vocabulary because score direction and threshold semantics depend on it: the same raw number means "near" under one metric and "far" under another, so an unrecognized value must be rejected rather than guessed.
func (DistanceMetric) String ¶
func (d DistanceMetric) String() string
func (DistanceMetric) Valid ¶
func (d DistanceMetric) Valid() bool
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store implements vectorstore.Store against a Pinecone index. Pinecone owns index creation and dimensionality, so this type validates against the index it is pointed at rather than provisioning one.
func NewStore ¶
func NewStore(ctx context.Context, config StoreConfig) (*Store, error)
NewStore confirms the index agrees with the configured metric during construction, which is why it takes a context: a store returned with the wrong metric would go on returning scores that are wrong rather than absent, and the misconfiguration is at wiring.
func (*Store) DeleteIDs ¶
DeleteIDs removes vectors by their string ids. An empty slice is a no-op; unknown ids are silently ignored (idempotent). Implements vectorstore.IDDeleter.
func (*Store) DeleteWhere ¶
DeleteWhere removes every vector matching expr. Pinecone implements metadata-filtered deletion on pod-based indexes only; serverless and starter indexes reject the request, and the error is reported rather than treated as an empty match set. Compose deletion from Store.DeleteIDs on those indexes. Implements vectorstore.FilterDeleter.
func (*Store) Index ¶
func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
func (*Store) Search ¶
func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
type StoreConfig ¶
type StoreConfig struct {
// Client is the Pinecone client instance.
// Required: must be provided, otherwise initialization will fail.
Client *pinecone.Client
// IndexHost is the host URL of the Pinecone index.
// Required: must be a non-empty string.
// Obtain it from DescribeIndex or the Pinecone web console.
IndexHost string
// Namespace is the index namespace to use for all operations.
// Optional: defaults to the default namespace if empty.
Namespace string
// EmbeddingModel is the model used to generate vector embeddings from text.
// Required: must be provided.
EmbeddingModel embedding.Model
// DocumentBatcher is responsible for batching documents before insertion.
// Required: must be provided.
DocumentBatcher vectorstore.Batcher
// DistanceMetric is the metric the index was created with. Required
// because Pinecone returns metric-specific raw scores. NewStore reads the
// index's own metric and refuses a mismatch with [ErrIncompatibleIndex],
// so this states a fact rather than carrying an unchecked obligation.
DistanceMetric DistanceMetric
}
StoreConfig contains configuration options for Pinecone vector store.
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
Source Files