Pinecone ExecModule

Overview

PineconeModule connects ValkyrAI workflows to Pinecone through the native map I/O ExecModule ABI. It fills the managed vector-database layer for semantic search, retrieval-augmented generation, memory recall, and other agentic workflows without exposing Pinecone API keys to workflow data.

The connector separates Pinecone's fixed control plane from index-specific data operations. Index discovery uses api.pinecone.io; query, fetch, statistics, upsert, update, and delete require the exact index host returned by Pinecone. Reads use bounded retries. Ambiguous mutations use one attempt only.

Usage

1. Create a least-privilege Pinecone API key for the required project.
2. Store the key in the encrypted IntegrationAccount.apiKey SecureField and set the account to READY.
3. Optionally store the default index name in IntegrationAccount.accountId.
4. Run list_indexes or describe_index to obtain the canonical index host.
5. Supply that host as indexHost for data-plane operations and select a tenant-safe namespace.
6. Bind the account through ExecModuleConfig.authConfig.integrationAccount.

Workflow inputs cannot override the API key, control-plane host, authorization header, API version, or retry safety classification.

Inputs

Name	Type	Requirement	Default	Description and constraints
operation	string	Required	None	One of the eight documented operations.
indexName	string	describe_index	Account ID	Lowercase alphanumeric/hyphen name, 1–45 characters.
indexHost	string	Data operations	None	Exact HTTPS *.pinecone.io host returned by Pinecone.
namespace	string	Optional	Provider default	Namespace up to 512 characters. Use it for tenant isolation.
vectorId	string	ID query/update	None	Non-blank vector ID up to 512 characters.
vector	number[]	Query/update	None	Dense vector with 1–20,000 finite numbers.
vectors	object[]	upsert_vectors	None	1–100 {id, values, metadata?} objects.
ids	string[]	Fetch/delete	None	1–100 bounded vector IDs.
metadata	object	update_vector	None	Bounded metadata changes; credential-like top-level keys are rejected.
filter	object	Query/stats/delete	None	Pinecone metadata filter capped at 64 KiB.
topK	integer	Query	10	Match count from 1 through 1,000.
includeValues	boolean	Query	false	Return dense vector values. Leave false unless needed.
includeMetadata	boolean	Query	true	Return match metadata.
deleteAll	boolean	Delete	false	Select every vector in the namespace.
confirmDelete	boolean	Delete	false	Must be true for every delete operation.

query requires exactly one of vector or vectorId. delete_vectors requires exactly one selector: ids, deleteAll, or filter.

Outputs

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
httpStatus / attempts	integer	Provider request	Provider status and total attempts.
items / count	array / integer	Index list or query	Sanitized index models or ordered vector matches.
data	object	Other successes	Sanitized index, vector, stats, or mutation response.
requestId	string	Provider supplies it	Pinecone request identifier for operational correlation.
error	object	Failure	Safe {code,message,httpStatus?,retryable} details.

API keys and authorization values are redacted from responses, errors, logs, and workflow events.

IntegrationAccount Requirements

Setting	Requirement
Provider	Pinecone project with control-plane and index data-plane access
accountName	Human-readable automation identity
accountId	Optional default Pinecone index name
apiKey	Encrypted SecureField containing a scoped Pinecone API key
status	Exactly READY

Create separate accounts or keys when workflows need different project access. Namespace isolation is not a replacement for Pinecone project/key policy or ValkyrAI RBAC.

Configuration

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:pinecone-knowledge"
  },
  "retryPolicy": {
    "maxAttempts": 3,
    "backoffStrategy": "EXPONENTIAL",
    "initialDelayMs": 1000,
    "maxDelayMs": 60000
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"query\",\"indexHost\":\"https://knowledge-example.svc.us-east-1-aws.pinecone.io\",\"namespace\":\"tenant-42\"}"
  }
}

The integration-account reference is symbolic. Persisted workflows use the generated relationship and never plaintext API keys.

Operations

Operation	Pinecone behavior	Side effect
list_indexes	Lists project indexes through the fixed control plane.	Read-only; conservative retries.
describe_index	Gets index dimension, metric, readiness, spec, and canonical host.	Read-only; conservative retries.
query	Searches by one dense vector or existing vector ID with optional namespace/filter.	Read-only POST; conservative retries.
fetch_vectors	Fetches up to 100 IDs from one namespace.	Read-only; conservative retries.
describe_stats	Gets index/namespace statistics with an optional metadata filter.	Read-only POST; conservative retries.
upsert_vectors	Inserts or replaces up to 100 explicit vectors.	Mutation; single attempt.
update_vector	Changes one vector's values, metadata, or both.	Mutation; single attempt.
delete_vectors	Deletes IDs, filtered vectors, or a namespace after confirmation.	Destructive mutation; single attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing key/host/input, invalid vector, oversized payload, unsafe metadata, or absent delete confirmation.	No	Correct the named input; no request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_REQUIRED	No bound account.	No	Bind a Pinecone IntegrationAccount.
INTEGRATION_ACCOUNT_NOT_READY	Account is not READY.	No	Repair or reconnect the account.
PINECONE_HTTP_400	Dimension mismatch, invalid filter, or provider validation failure.	No	Correct the vector/filter/index selection.
PINECONE_HTTP_401 / 403	Invalid key or insufficient project/index access.	No	Rotate or rescope the IntegrationAccount key.
PINECONE_HTTP_404	Index, host, namespace resource, or vector is unavailable.	No	Refresh index discovery and verify identifiers.
PINECONE_HTTP_429 / 5xx	Rate limit or transient provider failure.	Reads only	Retry a read; reconcile a mutation before manual retry.
NETWORK_ERROR	Timeout, DNS, TLS, or connectivity failure.	Reads only	Verify connectivity and host; do not blindly repeat mutations.
RESPONSE_TOO_LARGE	Response exceeded 10 MiB.	No	Reduce topK, IDs, or included vector values.

Example

Query a tenant namespace for the most relevant runbooks:

{
  "operation": "query",
  "indexHost": "https://knowledge-example.svc.us-east-1-aws.pinecone.io",
  "namespace": "tenant-42",
  "vector": [0.12, -0.08, 0.41, 0.19],
  "filter": {"kind": {"$eq": "runbook"}},
  "topK": 3,
  "includeMetadata": true,
  "includeValues": false
}

Expected result:

{
  "status": "success",
  "operation": "query",
  "httpStatus": 200,
  "count": 2,
  "items": [
    {"id": "runbook-17", "score": 0.97, "metadata": {"kind": "runbook"}},
    {"id": "runbook-04", "score": 0.91, "metadata": {"kind": "runbook"}}
  ],
  "attempts": 1
}

Notes

• Pagination: this version bounds query matches and fetch IDs in one operation. Control-plane index listing is returned as one provider response. Vector-ID listing and integrated-embedding record pagination are deferred.
• Rate limits: list_indexes, describe_index, query, fetch_vectors, and describe_stats may retry HTTP 408, 429, 500, 502, 503, and 504 with bounded exponential backoff and integer Retry-After. Mutations are always single-attempt.
• API limits: request bodies are capped at 2 MiB, responses at 10 MiB, dense dimensions at 20,000, vector batches and ID sets at 100, filters/metadata at 64 KiB, and topK at 1,000.
• Idempotency: upsert and update use stable vector IDs, but a timeout remains ambiguous. Fetch or query the exact vector before a manual retry. Never automatically retry a delete.
• Destructive behavior: every delete requires confirmDelete: true. deleteAll applies only to the selected namespace; omitting a namespace uses Pinecone's default namespace and should be treated as broad scope.
• Host safety: data operations accept only the exact HTTPS *.pinecone.io index host. The module never follows a provider-supplied absolute URL or constructs a data host from an index name.
• API version: the connector sends X-Pinecone-Api-Version: 2025-04 and uses the stable vector endpoints for explicit dense embeddings.
• External verification: local tests verify validation, headers, fixed-host routing, request construction, response mapping, retries, redaction, mutation guards, and metadata discovery. Live Pinecone authentication, quotas, dimensions, consistency, private endpoints, and billing require separately authorized provider credentials and are not exercised in repository tests.
• Deferred operations: index create/configure/delete, backups, collections, assistant APIs, sparse-only vectors, integrated embedding/search records, reranking, vector-ID pagination, bulk import, and namespace deletion lifecycle.
• Functional references: n8n Pinecone Vector Store, Pinecone index targeting, Pinecone query API, and Pinecone upsert API.