Faz Docs

Connect faz to a Pinecone vector database. Intent-based JSON queries — query, fetch, list. Local container or managed cloud.

Pinecone is a managed vector database. faz's connector supports both the local pinecone-index container (for development) and the managed cloud service (for production).

Default port	Query language	Write support	Schema discovery	Driver
5081*	Intent-based JSON	Yes (RBAC-gated)	Index info	`pinecone`

* Default port for the local container. Managed cloud uses the index hostname (e.g. my-index-xxxx.svc.us-east-1-aws.pinecone.io) over HTTPS — port is ignored when host is a Pinecone-cloud DNS name.

Quick example (local container)

faz.yaml — local

databases:
  - name: <database>          # used as --database <database> in queries
    type: pinecone
    host: localhost
    port: 5081
    ssl: false
    extra:
      api_key: ""              # not required for the local container

Quick example (managed cloud)

faz.yaml — managed cloud

databases:
  - name: <database>          # used as --database <database> in queries
    type: pinecone
    host: <index-hostname>    # e.g. my-index-xxxx.svc.us-east-1-aws.pinecone.io
    ssl: true
    password: <api-key>       # API key (alternative: extra.api_key)

permissions:
  - database: <database>      # must match `name:` above
    access: R
    # access codes:
    # R    read only           — query, fetch, list
    # W    write only          — upsert, update, delete (no reads — blocked at connector)
    # RW   read + write
    # RA   read + append       — reads + upsert
    # RWA  read + write, no DELETE
    # A    admin (control-plane ops — intentionally absent in connector)

See Permissions for the full model, per-table overrides, and the operation matrix.

faz query '{"intent":"query","vector":[<your-vector>],"top_k":5}' --database <database> --table <namespace> --language vector

uv run faz query '{"intent":"query","vector":[<your-vector>],"top_k":5}' --database <database> --table <namespace> --language vector

python -m faz query '{"intent":"query","vector":[<your-vector>],"top_k":5}' --database <database> --table <namespace> --language vector

Configuration

Field	Type	Default	Notes
`host`	string	`localhost`	Local hostname or the index's DNS name on managed Pinecone.
`port`	integer	`5081`	Local container port. Ignored for managed cloud (HTTPS on 443).
`database`	string	`""`	Not used. The "table" is a namespace.
`username`	string	`""`	Not used.
`password`	string	`""`	API key. `extra.api_key` is the alternative slot.
`ssl`	boolean	`false`	`true` for managed cloud (HTTPS); `false` for the local container (HTTP).
`extra`	mapping	`{}`	`api_key` for managed Pinecone if you don't want to put it in `password`.

Capabilities

Supported intents:

Intent	Op class	Notes
`query`	SELECT	Vector similarity. `vector`, `top_k`, optional `filter`, `namespace`.
`fetch`	SELECT	Fetch points by id list.
`list`	SELECT	Enumerate ids in a namespace.

Filters use Pinecone's metadata-filter language (e.g. {"genre": {"$eq": "rock"}}). The connector passes them through.

For managed Pinecone, faz expects each databases: entry to point at one index. To talk to multiple indexes, register them as separate databases: entries with different names.

Limitations

Write intents are blocked: upsert, update, delete. Use Pinecone's own client for ingestion.
Control-plane operations are intentionally absent — create_index, list_indexes, delete_index. This keeps the connector compatible with the local container, which doesn't speak the same control-plane API as managed cloud. Manage indexes via pinecone SDK or the Pinecone web console outside faz.
No batch query. Each query is one vector.

Troubleshooting

PineconeException: API key required — set password or extra.api_key.

HTTP 404 against managed cloud — your host is wrong, or the index has been deleted. List indexes via the Pinecone console or pinecone list-indexes.

HTTP 403 — your API key is for a different project than the index belongs to.

Local container connection refused — the pinecone-index container isn't running. Pull and run: docker run -p 5081:5081 ghcr.io/pinecone-io/pinecone-index:latest.

For the broader troubleshooting flow, see Connection failed.

Databases overview — cross-connector basics.
Weaviate, Qdrant, Milvus — sibling vector databases (self-hostable).

Pinecone