`pinecone://`¶

Vector database integration for Pinecone via the REST API. The producer issues upsert, query, delete, and fetch against an index, using your API key + index host (or environment-derived host). No external Pinecone SDK is needed.

URI shape¶

pinecone://<index>/<operation>?apiKey=...&host=https://...&namespace=default

Producer-only — CreateConsumer returns an error.

Token	Description
`<index>`	Required — Pinecone index name (used to construct the host when `environment` is given).
`<operation>`	Optional — `upsert` (default), `query`, `delete`, `fetch`.

Parameters¶

Param	Type	Default	Producer/Consumer/Both	Description
`apiKey`	string	—	Producer	Pinecone API key. Sent as `Api-Key: <key>`.
`host`	string	—	Producer	Explicit index host (`https://<index>-<env>.svc.pinecone.io`). Wins over `environment`.
`environment`	string	—	Producer	Pinecone environment (`us-east-1-aws`, etc.). When set, the host is built as `https://<index>-<environment>.svc.pinecone.io`. Required when `host` is not given.
`namespace`	string	—	Producer	Pinecone namespace. Omitted from requests when blank.
`topK`	integer	`5`	Producer	`topK` for `query`.

Operations¶

`upsert`¶

Body: []map[string]any (or a JSON array). Each row needs id, values, and metadata. Request: POST <host>/vectors/upsert with {vectors: [...], namespace?: "..."}.

`query`¶

Body: []float64 (or a JSON array — the query vector). Request: POST <host>/query with {vector, topK, includeMetadata:true, namespace?}. The response's matches array is set as the new body and pinecone.results.count is recorded.

`delete`¶

Set pinecone.ids header to a comma-separated list of vector IDs. Request: POST <host>/vectors/delete with {ids: [...], namespace?}. The header is required — there is no filter-based delete path in this component.

`fetch`¶

Set pinecone.ids header. Request: GET <host>/vectors/fetch?ids=id1&ids=id2&namespace=.... The response's vectors map (id → vector record) becomes the new body.

Headers¶

Read by the producer¶

Header	Description
`pinecone.ids`	`delete` / `fetch` — comma-separated vector IDs. Required for those operations.

Written by the producer¶

Header	Description
`pinecone.index`	Index name.
`pinecone.operation`	Operation executed.
`pinecone.namespace`	Namespace used.
`pinecone.results.count`	`query` only — number of matches.

Examples¶

Upsert embeddings:

- transform:
    starlang: |
      %sl 2.0
      output application/json
      input payload
      ---
      # convert []*rag.Embedding -> Pinecone vectors
      embeddings_to_pinecone(payload)
- target: pinecone://docs/upsert?apiKey=${PINECONE_KEY}&host=https://docs-abc123.svc.us-east-1-aws.pinecone.io&namespace=prod

Query then dispatch:

- rag-embed: { provider: openai, model: text-embedding-3-small }
- target: pinecone://docs/query?apiKey=${PINECONE_KEY}&host=${PINECONE_HOST}&topK=10
- set-body:
    starlang: 'payload[0]["metadata"]["text"]'

Fetch by ID:

- set-header:
    name: pinecone.ids
    constant: "doc-1,doc-2,doc-3"
- target: pinecone://docs/fetch?apiKey=${PINECONE_KEY}&host=${PINECONE_HOST}

Behavior notes¶

Host construction — supply either host (Pinecone's serverless / Pods-tier URLs vary) or environment. The two formats are not interchangeable.
Response cap — io.LimitReader is applied at 100 MB per response.
No upsert without explicit IDs — Pinecone requires id on every row; the component does not generate IDs for you.
delete without IDs is an error — there is no filter-based delete in this surface. If you need filtered deletion, drive the Pinecone control-plane API yourself with http://.

Source¶

pkg/component/pinecone/pinecone.go

pinecone://¶