@mastra/pinecone 0.0.0-error-handler-fix-20251020202607 → 0.0.0-esbuild-bundle-worker-20260807182016
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +326 -3
- package/LICENSE.md +15 -0
- package/README.md +14 -8
- package/dist/docs/SKILL.md +31 -0
- package/dist/docs/assets/SOURCE_MAP.json +6 -0
- package/dist/docs/references/docs-memory-memory-processors.md +385 -0
- package/dist/docs/references/guides-rag-retrieval.md +520 -0
- package/dist/docs/references/guides-rag-vector-databases.md +669 -0
- package/dist/docs/references/reference-vectors-pinecone.md +170 -0
- package/dist/index.cjs +439 -369
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +436 -365
- package/dist/index.js.map +1 -1
- package/dist/vector/index.d.ts +85 -17
- package/dist/vector/index.d.ts.map +1 -1
- package/package.json +22 -15
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
|
|
2
|
+
|
|
3
|
+
# Pinecone vector store
|
|
4
|
+
|
|
5
|
+
The PineconeVector class provides an interface to [Pinecone](https://www.pinecone.io/)'s vector database. It provides real-time vector search, with features like hybrid search, metadata filtering, and namespace management.
|
|
6
|
+
|
|
7
|
+
## Constructor options
|
|
8
|
+
|
|
9
|
+
The constructor accepts all [Pinecone configuration options](https://docs.pinecone.io/reference/typescript-sdk) plus Mastra-specific fields.
|
|
10
|
+
|
|
11
|
+
**id** (`string`): Unique identifier for this vector store instance
|
|
12
|
+
|
|
13
|
+
**apiKey** (`string`): Pinecone API key
|
|
14
|
+
|
|
15
|
+
**controllerHostUrl** (`string`): Custom Pinecone controller host URL
|
|
16
|
+
|
|
17
|
+
**additionalHeaders** (`Record<string, string>`): Additional HTTP headers to include in requests
|
|
18
|
+
|
|
19
|
+
**sourceTag** (`string`): Source tag for request tracking
|
|
20
|
+
|
|
21
|
+
**cloud** (`'aws' | 'gcp' | 'azure'`): Cloud provider for new index creation (Default: `aws`)
|
|
22
|
+
|
|
23
|
+
**region** (`string`): Region for new index creation (Default: `us-east-1`)
|
|
24
|
+
|
|
25
|
+
## Methods
|
|
26
|
+
|
|
27
|
+
### `createIndex()`
|
|
28
|
+
|
|
29
|
+
**indexName** (`string`): Name of the index to create
|
|
30
|
+
|
|
31
|
+
**dimension** (`number`): Vector dimension (must match your embedding model)
|
|
32
|
+
|
|
33
|
+
**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search. Use 'dotproduct' if you plan to use hybrid search. (Default: `cosine`)
|
|
34
|
+
|
|
35
|
+
### `upsert()`
|
|
36
|
+
|
|
37
|
+
**indexName** (`string`): Name of your Pinecone index
|
|
38
|
+
|
|
39
|
+
**vectors** (`number[][]`): Array of dense embedding vectors
|
|
40
|
+
|
|
41
|
+
**sparseVectors** (`{ indices: number[], values: number[] }[]`): Array of sparse vectors for hybrid search. Each vector must have matching indices and values arrays.
|
|
42
|
+
|
|
43
|
+
**metadata** (`Record<string, any>[]`): Metadata for each vector
|
|
44
|
+
|
|
45
|
+
**ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
|
|
46
|
+
|
|
47
|
+
**namespace** (`string`): Optional namespace to store vectors in. Vectors in different namespaces are isolated from each other.
|
|
48
|
+
|
|
49
|
+
### `query()`
|
|
50
|
+
|
|
51
|
+
**indexName** (`string`): Name of the index to query
|
|
52
|
+
|
|
53
|
+
**queryVector** (`number[]`): Dense query vector to find similar vectors
|
|
54
|
+
|
|
55
|
+
**sparseVector** (`{ indices: number[], values: number[] }`): Optional sparse vector for hybrid search. Must have matching indices and values arrays.
|
|
56
|
+
|
|
57
|
+
**topK** (`number`): Number of results to return (Default: `10`)
|
|
58
|
+
|
|
59
|
+
**filter** (`Record<string, any>`): Metadata filters for the query
|
|
60
|
+
|
|
61
|
+
**includeVector** (`boolean`): Whether to include the vector in the result (Default: `false`)
|
|
62
|
+
|
|
63
|
+
**namespace** (`string`): Optional namespace to query vectors from. Only returns results from the specified namespace.
|
|
64
|
+
|
|
65
|
+
### `listIndexes()`
|
|
66
|
+
|
|
67
|
+
Returns an array of index names as strings.
|
|
68
|
+
|
|
69
|
+
### `describeIndex()`
|
|
70
|
+
|
|
71
|
+
**indexName** (`string`): Name of the index to describe
|
|
72
|
+
|
|
73
|
+
Returns:
|
|
74
|
+
|
|
75
|
+
```typescript
|
|
76
|
+
interface IndexStats {
|
|
77
|
+
dimension: number
|
|
78
|
+
count: number
|
|
79
|
+
metric: 'cosine' | 'euclidean' | 'dotproduct'
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### `deleteIndex()`
|
|
84
|
+
|
|
85
|
+
**indexName** (`string`): Name of the index to delete
|
|
86
|
+
|
|
87
|
+
### `updateVector()`
|
|
88
|
+
|
|
89
|
+
Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
|
|
90
|
+
|
|
91
|
+
**indexName** (`string`): Name of the index containing the vector
|
|
92
|
+
|
|
93
|
+
**id** (`string`): ID of the vector to update (mutually exclusive with filter)
|
|
94
|
+
|
|
95
|
+
**filter** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
|
|
96
|
+
|
|
97
|
+
**namespace** (`string`): Optional namespace for the update operation
|
|
98
|
+
|
|
99
|
+
**update** (`object`): Update parameters
|
|
100
|
+
|
|
101
|
+
**update.vector** (`number[]`): New vector values to update
|
|
102
|
+
|
|
103
|
+
**update.metadata** (`Record<string, any>`): New metadata to update
|
|
104
|
+
|
|
105
|
+
### `deleteVector()`
|
|
106
|
+
|
|
107
|
+
**indexName** (`string`): Name of the index containing the vector
|
|
108
|
+
|
|
109
|
+
**id** (`string`): ID of the vector to delete
|
|
110
|
+
|
|
111
|
+
### `deleteVectors()`
|
|
112
|
+
|
|
113
|
+
Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
|
|
114
|
+
|
|
115
|
+
**indexName** (`string`): Name of the index containing the vectors to delete
|
|
116
|
+
|
|
117
|
+
**ids** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
|
|
118
|
+
|
|
119
|
+
**filter** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
|
|
120
|
+
|
|
121
|
+
**namespace** (`string`): Optional namespace for the deletion operation
|
|
122
|
+
|
|
123
|
+
## Response types
|
|
124
|
+
|
|
125
|
+
Query results are returned in this format:
|
|
126
|
+
|
|
127
|
+
```typescript
|
|
128
|
+
interface QueryResult {
|
|
129
|
+
id: string
|
|
130
|
+
score: number
|
|
131
|
+
metadata: Record<string, any>
|
|
132
|
+
vector?: number[] // Only included if includeVector is true
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Error handling
|
|
137
|
+
|
|
138
|
+
The store throws typed errors that can be caught:
|
|
139
|
+
|
|
140
|
+
```typescript
|
|
141
|
+
try {
|
|
142
|
+
await store.query({
|
|
143
|
+
indexName: 'index_name',
|
|
144
|
+
queryVector: queryVector,
|
|
145
|
+
})
|
|
146
|
+
} catch (error) {
|
|
147
|
+
if (error instanceof VectorStoreError) {
|
|
148
|
+
console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
|
|
149
|
+
console.log(error.details) // Additional error context
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Environment variables
|
|
155
|
+
|
|
156
|
+
Required environment variables:
|
|
157
|
+
|
|
158
|
+
- `PINECONE_API_KEY`: Your Pinecone API key
|
|
159
|
+
|
|
160
|
+
## Hybrid search
|
|
161
|
+
|
|
162
|
+
Pinecone supports hybrid search by combining dense and sparse vectors. To use hybrid search:
|
|
163
|
+
|
|
164
|
+
1. Create an index with `metric: 'dotproduct'`
|
|
165
|
+
2. During upsert, provide sparse vectors using the `sparseVectors` parameter
|
|
166
|
+
3. During query, provide a sparse vector using the `sparseVector` parameter
|
|
167
|
+
|
|
168
|
+
## Related
|
|
169
|
+
|
|
170
|
+
- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
|