Skip to main content
View source

Pinecone

View as Markdown

A RocketRide vector-store node that stores embedded document chunks in a Pinecone index and retrieves them by semantic or keyword search. Use it when a pipeline or agent needs a Pinecone-backed document store.

About Pinecone​

Pinecone is a managed vector database for applications that search embedding data. It organizes vectors into indexes and supports vector queries with metadata filters. Use it when Pinecone is the service your application uses for retrieval and you want RocketRide to store and query the same index.

What it does​

The node accepts embedded documents on its documents lane and can retrieve matching documents for incoming questions. It also exposes the store to an agent as tools. It creates a Pinecone index when documents are first added, and rejects incoming chunks without embeddings. Pick it over a self-managed store when the retrieval corpus belongs in a Pinecone index and its selected deployment mode is already part of the intended Pinecone setup.

The driver treats its Collection setting as the Pinecone index name. When it has to create that index, the supplied embeddings determine its dimension and the selected similarity setting determines its metric.

Lanes​

Lane inLane outDescription
documents—Store embedded document chunks.
questionsdocumentsReturn matching documents.
questionsanswersReturn matching documents as answers.
questionsquestionsEnrich questions with matching documents.

As a tool​

The configured tool-server name defaults to pinecone.

FunctionDescription
searchSearches the store for a non-empty query; accepts optional top_k and metadata filter, and returns matching content, metadata, and scores.
objdirLists the distinct parent paths of active documents in the collection as a map of parent path to one object ID each; accepts optional parent (exact match), offset, and limit (default and cap 1000). offset and limit count documents, not paths: documents that share a parent path appear as one entry, so a page can hold fewer than limit entries while more follow.
getReturns up to limit chunks (default and cap 100) of one document by object_id, ordered by chunk ID, with total, has_more, and truncated; an object ID the store does not hold, or one in the trash, returns a failure object.
statsReturns the collection's count as this store reports it, document_count (null on this store, which does not list documents), the embedding model name, and the vector size.
upsertAdds or updates a non-empty documents array. Each document requires content and an object ID; it can provide an embedding and embedding model or use the bound embedding provider.
deleteDeletes documents for a non-empty object_ids array and returns the deleted count.
soft_deleteMoves the documents of a non-empty object_ids array to the trash, keeping their chunks; the reply echoes the distinct IDs, and matched_chunks is null on this store.
restoreTakes the documents of a non-empty object_ids array out of the trash. A document removed with delete cannot be restored.

search requires a bound embedding provider for semantic similarity search. The functions return a failure object when their required input or an embedding cannot be obtained; get answers an unknown object ID the same way.

search accepts an optional filter object honoring only objectId, nodeId and parent; any other key is rejected. upsert accepts an optional metadata object storing nodeId, parent and chunkId; nodeId defaults to "vectordb_tool", parent to "/", and chunkId to the document's position among the chunks sent for its object ID in the call (0 for the first), and an explicit chunkId may not repeat within the call.

Profiles​

Default: Pinecone Serverless Dense Index (serverless-dense).

ProfileDeployment modeContext
Pinecone Pod-Based Indexpod-basedCreates a pod-based index.
Pinecone Serverless Dense Index (default)serverless-denseCreates a serverless index.

Configuration​

Choose the profile that matches the target index, then provide the API key and collection name. New indexes use the selected profile; an existing index is checked against it during the save-time probe. The profile selection matters at creation time, while the key and collection select which existing Pinecone resource this node connects to.

Index profile​

Pinecone Serverless Dense Index is the default profile and creates an index with the driver's serverless specification; Pinecone Pod-Based Index uses its pod-based specification. Select the one that matches an index you already have, or the kind of index you intend the node to create. The save-time probe compares an existing index's specification with the selected profile and warns if they do not agree; change the profile rather than assuming the node can change the existing index's deployment type.

Collection​

The collection is the Pinecone index name and defaults to rocketride. Validation requires lowercase letters, numbers, and hyphens only; it rejects leading or trailing hyphens, consecutive hyphens, and names over 45 characters. Choose a name that identifies the one index this node will use. Change it to direct the node to a different Pinecone index, not to split a corpus inside one index. A validation warning flags a name that cannot be used by the configured service.

Similarity and retrieval score​

The runtime accepts cosine, euclidean, or dotproduct as the similarity setting, defaulting to cosine; another value stops initialization. This value becomes the metric when the driver creates an index, so make it agree with the embedding data and leave an existing index's metric alone. Choosing the wrong metric changes ranking and can make good matches appear weak.

Although the configuration value score is read with a default of 0.5, the semantic-search filtering code reads the separately named threshhold_search attribute, whose initial value is 0.0; therefore the configured score is not applied by this implementation. Do not rely on this setting to suppress weak Pinecone results. If relevance needs stricter filtering, apply a downstream constraint or use a store whose retrieval threshold is enforced until this implementation changes.

API key​

The API key is trimmed before the Pinecone client is created. It is needed both to open the store and for the save-time probe that lists indexes. Rotate or replace it when authentication fails rather than changing the collection name; the probe can also reveal a key that reaches Pinecone but cannot inspect the chosen index. Keep one key per intended service boundary when the node should not see every index available to a broader application credential.

Tool Server Name​

The tool-server name defaults to pinecone and labels this store in tool-response messages. Pipeline agents address all eight functions listed above by node ID, for example <node id>.search or <node id>.restore; changing this label does not change those addresses.

Authentication​

Set the API key for the selected Pinecone profile. The runtime creates its client with that key, and the save-time probe uses it to list indexes and check an existing index's deployment mode.

Notes​

Search and document lifecycle​

Semantic search requires an embedding and does not accept a non-zero offset. Keyword search adds a content filter to the metadata filters. A batch that holds an object's chunk 0 deletes that object's existing chunks before the new chunks are upserted, so a re-ingest replaces the object; a batch without chunk 0 adds its chunks to the stored ones, so an object written in several batches keeps them all. Rows get generated IDs, so a batch without chunk 0 that repeats a chunk number already stored keeps both copies; to change a chunk, write the object again from chunk 0. The store can mark chunks deleted or active, and its default filters exclude marked-deleted chunks.

The node retrieves semantic results with the requested limit (or 25 when no limit is supplied). It runs the collection-existence and embedding-model checks before searching, which makes a missing index or incompatible model fail before results are returned.

Index creation is intentionally opinionated: the serverless branch supplies an AWS us-east-1 specification, while the pod branch supplies one p1.x1 pod in us-east1-gcp. Those are creation-time defaults in this node, not settings that alter an existing index. Choose an already compatible index when those defaults are not appropriate for the intended deployment.

Rendering and paths​

Rendering retrieves an object's chunks in chunkId order and sends joined text to the callback in renderChunkSize groups. For path listing, the driver requests enough records for the requested offset and limit, then slices the results locally.

Metadata filters include document identity, parent path, permissions, table information, and deletion state. The driver defaults isDeleted to false in its Pinecone filter, so a soft-deleted source does not appear in normal retrieval. That makes reactivating or explicitly including deleted material a separate caller choice rather than an accidental result of broad searching.

Upstream docs​

Schema​

FieldTypeDescriptionDefault
pinecone.collectionstringCollection
Enter the name of the collection. Accepted are: Lower case, alphanumeric characters, hyphens
"rocketride"
pinecone.profilestringType of Pinecone Connection
Connect to...
"pod-based"
pinecone.providerstringconst: "pinecone"
pinecone.serverNamestringTool Server Name
Label for this store in tool-response messages (for example, a refused write names pinecone.delete). Pipeline agents address the available functions as node-id.function; apps use the function name and node ID. Changing this label does not change those addresses. See the node README for the available functions and their tool-exposure and write-permission settings.
"pinecone"

Dependencies​

  • pinecone
  • pinecone-plugin-assistant
  • pinecone-plugin-interface