weaviate-python-client

weaviate-client is the official Python client for Weaviate, the open-source vector database. It wraps Weaviate’s gRPC and REST APIs in a fully typed, Pythonic interface so applications can create collections, insert and batch-import objects, and run vector, hybrid, and keyword search queries without hand-building requests.

The v4 client is built around a single executor pattern: every namespace (collections, backup, cluster, rbac, users, debug) is generated once and exposed through both a synchronous WeaviateClient and an WeaviateAsyncClient, so sync and async code share one implementation instead of two parallel codebases. Object and query APIs use Pydantic models and Python generics to give IDE autocomplete and static type checking across collection schemas, filters, and return types.

Beyond basic CRUD and search, the client covers the operational surface of running Weaviate in production: authentication (API key, OIDC, custom auth flows via authlib), multi-tenancy, RBAC role and permission management, cluster and node introspection, backups, and an embedded-Weaviate mode for local development without a separate server process. An optional agents extra adds Weaviate’s agent-building primitives on top of the core client.

What You Get

• A single WeaviateClient (sync) and WeaviateAsyncClient (async) generated from one executor implementation, so both flavors stay behaviorally identical
• gRPC-backed query and batch-insert paths for low-latency vector, hybrid, and keyword search plus high-throughput object imports
• Pydantic-typed collection, query, and filter models with IDE autocomplete and static type checking (ships py.typed, checked with mypy)
• Built-in auth flows (API key, OIDC/OAuth via authlib), multi-tenancy, and RBAC role/permission management as first-class APIs
• Cluster, node, and backup management namespaces for operating Weaviate in production, plus an embedded-Weaviate mode for local dev
• An optional agents extra that layers Weaviate’s agent-building primitives on top of the core client

Common Use Cases

• Building retrieval-augmented generation (RAG) pipelines that need fast vector and hybrid search over embedded documents
• Standing up semantic search or recommendation features backed by a self-hosted or Weaviate Cloud instance
• Batch-importing large datasets into Weaviate collections with the client’s gRPC batch API for throughput
• Managing multi-tenant Weaviate deployments, including per-tenant collections, RBAC roles, and access control
• Running Weaviate locally via the embedded client during development or CI without provisioning a separate server

Under The Hood

Architecture The client is organized around a single _WeaviateClientExecutor base (weaviate/client_executor.py) that is code-generated into both WeaviateClient and WeaviateAsyncClient via the @executor.wrap("sync"/"async") decorator in weaviate/connect/executor.py — every namespace (collections, backup, cluster, rbac, users, debug, export, groups, aliases) is written once against this executor and automatically produces matching sync and async surfaces, avoiding the maintenance burden of two hand-written client trees. Connection handling lives in weaviate/connect/, with a REST/gRPC dual transport (ConnectionSync/ConnectionAsync) that dispatches queries over gRPC (weaviate/proto/v1) for performance and falls back to REST for management operations. Collection- and query-specific logic is layered under weaviate/collections/ (aggregate, batch, filters, generate, query, tenants), keeping data-plane operations separate from admin-plane modules like rbac/, cluster/, and backup/.

Tech Stack Written for Python 3.10+, the client depends on httpx for the REST transport, grpcio/protobuf for the gRPC query and batch paths, pydantic v2 for typed request/response models, authlib for OIDC/OAuth auth flows, and validators/packaging for input and version validation. Build tooling is setuptools with setuptools_scm for version derivation from git tags, and the package ships an agents extra (weaviate-agents) as an optional add-on. Distribution is standard PyPI (weaviate-client), with parallel Sphinx-based docs published to Read the Docs.

Code Quality The repository has an extensive test suite split into test/ (unit), integration/ and integration_embedded/ (live-server integration), journey_tests/, mock_tests/, and proto_test/, run with pytest plus pytest-asyncio, pytest-xdist, and pytest-benchmark. Type safety is enforced with mypy (run-mypy.sh) against the shipped py.typed marker, and ruff handles linting/formatting with a 100-character line length. GitHub Actions workflows (main.yaml, pr-security-lint.yaml) run CI and security/lint checks on every PR, and the codebase uses typed exceptions (weaviate/exceptions.py) and structured warnings (weaviate/warnings.py) rather than silent failure.

What Makes It Unique The generate-once, expose-twice executor pattern is the client’s distinguishing design choice — instead of maintaining separate sync and async implementations (a common source of drift in Python SDKs), every namespace is written against a protocol-agnostic executor and mechanically produces both client variants, keeping behavior identical across sync and async call sites. Combined with gRPC as the primary query transport (rather than REST-only), this gives the client both API-surface consistency and low query latency, which is unusual among database/vector-store Python clients that typically pick one paradigm and one transport.