Pinecone

The pinecone connector owns a Pinecone index — the API key and index addressing — and the pinecone-upsert, pinecone-query, pinecone-fetch, and pinecone-delete blocks bind to it by name. Pair it with ai-embed for the common RAG shape: embed text, upsert the vector, then embed a query and search for matches.

Provides a source: no — it is a service connector. Blocks that bind to it: pinecone-upsert, pinecone-query, pinecone-fetch, pinecone-delete.

pinecone connector

The connector looks the index up by name on start, which resolves its host and validates it: the index's actual dimension is compared against the configured one, so a mismatched embedding model and index — the classic Pinecone failure mode — fails at startup rather than on the first upsert. It then opens the data-plane connection blocks call through.

env:
  - name: PINECONE_API_KEY
    required: true

connectors:
  - name: docs-index
    type: pinecone
    settings:
      apiKey: ${PINECONE_API_KEY}
      index: docs
      dimension: 1536

Skipping the startup lookup

The index's host is printed in the Pinecone console next to the index name. Configure it as host and the connector addresses the index directly: startup then makes no network call at all, which is what an air-gapped build — or a flow test, where the credentials are fake and every block that would call out is mocked — needs.

The trade is explicit: without the lookup there is nothing to compare dimension against, so it goes unchecked. Leave host unset in production unless you want that.

  - name: docs-index
    type: pinecone
    settings:
      apiKey: ${PINECONE_API_KEY}
      index: docs
      host: ${PINECONE_HOST}    # empty in production: look the index up and check it
      dimension: 1536

Results: the body, or a variable

pinecone-query, pinecone-fetch, and pinecone-upsert all follow one rule: the result becomes the message body, unless you name a resultVar, in which case it goes there and the body is left alone.

The body is the default because the result is usually the payload — an HTTP flow that ends in a query should answer with the matches, and an agent tool that ends in one returns them to the model as its tool result, with no glue block in between. Naming a variable is how you say "keep the body I came in with", which is the case when a later block still needs the request that arrived.

Namespaces

Namespaces are Pinecone's multi-tenancy mechanism, so every block exposes its own namespace as a CEL expression rather than a connector-wide constant — a flow serving multiple tenants can route body.tenantId (or similar) to a different namespace per message. An empty (or unset) namespace field uses the connector's default namespace.

pinecone-upsert block

Upsert vectors into the index. vectors evaluates to a list of {id, values, metadata} objects; a large batch is chunked automatically to stay under Pinecone's per-request vector limit — one vectors expression can cover an arbitrarily large batch without the flow author doing the chunking.

- type: pinecone-upsert
  name: index-chunks
  settings:
    connector: docs-index
    vectors: |
      body.chunks.map(c, {"id": c.id, "values": c.vector, "metadata": {"source": c.source}})
    namespace: body.tenantId

pinecone-query block

Query the index for the vectors most similar to a query vector, with an optional metadata filter. The matches are a list of {id, score, values?, metadata?}.

- type: pinecone-query
  name: find-similar
  settings:
    connector: docs-index
    vector: vars.queryVector
    topK: 5
    filter: '{"source": {"$eq": "handbook"}}'
    namespace: body.tenantId
    # No resultVar: the matches are the body, and the flow's answer.

pinecone-fetch block

Fetch vectors by id.

- type: pinecone-fetch
  name: get-vectors
  settings:
    connector: docs-index
    ids: body.ids

pinecone-delete block

Delete vectors: by id, by metadata filter, or the whole namespace. Set exactly one of ids, filter, or deleteAll — zero or more than one fails at startup.

- type: pinecone-delete
  name: wipe-tenant
  settings:
    connector: docs-index
    deleteAll: true
    namespace: body.tenantId