Faz Docs

Connect faz to a Weaviate vector database. Intent-based JSON queries — fetch, bm25, near_text, near_vector, hybrid.

Weaviate's connector uses the v4 client (gRPC + HTTP). Queries are JSON with an intent field that picks one of Weaviate's query modes.

Default port	Query language	Write support	Schema discovery	Driver
8080	Intent-based JSON	Yes (RBAC-gated)	`schema.get()`	`weaviate-client`

Quick example

faz.yaml

databases:
  - name: <database>          # used as --database <database> in queries
    type: weaviate
    host: localhost
    port: 8080
    username: ""
    password: ""              # API key in `extra.api_key` if your Weaviate requires it
    ssl: false

permissions:
  - database: <database>      # must match `name:` above
    access: R
    # access codes:
    # R    read only           — fetch, bm25, near_text, near_vector, hybrid
    # W    write only          — upsert, update, delete (no reads)
    # RW   read + write
    # RA   read + append       — reads + insert
    # RWA  read + write, no DELETE
    # A    admin (incl. collection DDL — but blocked at connector level)

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

faz query '{"intent":"near_text","query":"<search text>","limit":5}' --database <database> --table <Class> --language vector

uv run faz query '{"intent":"near_text","query":"<search text>","limit":5}' --database <database> --table <Class> --language vector

python -m faz query '{"intent":"near_text","query":"<search text>","limit":5}' --database <database> --table <Class> --language vector

Configuration

Field	Type	Default	Notes
`host`	string	`localhost`	Weaviate host.
`port`	integer	`8080`	HTTP/gRPC port (the v4 client opens both internally).
`database`	string	`""`	Not used. Weaviate's "table" is a class name — set in the IR step.
`username`	string	`""`	Reserved for username/password auth.
`password`	string	`""`	Reserved.
`ssl`	boolean	`false`	When `true`, uses HTTPS/secure gRPC.
`extra`	mapping	`{}`	API-key auth for managed Weaviate instances goes in `extra.api_key`.

Capabilities

Supported intents:

Intent	Op class	Notes
`fetch`	SELECT	Get objects by id or property filter.
`bm25`	SELECT	Sparse keyword search.
`near_text`	SELECT	Vector similarity using a text encoder configured on the class.
`near_vector`	SELECT	Vector similarity using a caller-supplied vector.
`hybrid`	SELECT	BM25 + vector combined.
`select`	SELECT	Generic GraphQL-style projection.

Schema discovery enumerates classes via schema.get(). Each class shows up as a table with its properties as fields.

Limitations

Collection ops are blocked at the connector level: create_collection, delete_collection, drop_collection, alter_collection. Weaviate's collection-level admin requires the A access level and a control-plane intent that the connector intentionally doesn't expose. Manage collections outside faz.
The connector exposes data-plane intents only. Cluster admin, multi-tenancy management, and module configuration aren't reachable through query_simple.
Hybrid scoring depends on Weaviate's vectoriser module configuration. faz doesn't validate the module is set up — if near_text errors with "no vectoriser configured", that's Weaviate's response, not ours.

Troubleshooting

ConnectError / unable to resolve host — Weaviate isn't reachable. curl http://host:port/v1/.well-known/ready should return 200.

AuthenticationFailedException — auth method mismatch. Managed Weaviate (Weaviate Cloud) uses API keys; set extra.api_key. Self-hosted with auth disabled doesn't need credentials.

Schema is empty — no classes are defined. Create classes via Weaviate's API outside faz.

Query times out on near_text — the configured vectoriser is slow or unavailable. Check the vectoriser module's logs in Weaviate.

For the broader troubleshooting flow, see Connection failed.

Databases overview — cross-connector basics.
Qdrant — sibling vector database with a different intent vocabulary.
Milvus — sibling vector database.
Pinecone — sibling, hosted-only by default.

Weaviate

Quick example

Configuration

Capabilities

Limitations

Troubleshooting

Related

On this page