# weaviate/weaviate-python-client architecture

> Architecture diagram of the GitHub repository weaviate/weaviate-python-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/weaviate/weaviate-python-client
- Repository: https://github.com/weaviate/weaviate-python-client

## Overview

The Weaviate Python client lets applications connect to a Weaviate instance, manage collections and objects, and retrieve results through synchronous or asynchronous APIs. The principal workflow is to create a client, define or select a collection, then write or query data; the client connection layer handles transport and authentication. Separate API branches expose batching, backups, exports, cluster operations, and administration. The README establishes the product purpose; component links use the supplied source index and excerpts, so some unsampled subsystem internals are not detailed.

Main entry points: [`weaviate/client.py`](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/client.py) (Client API), [`weaviate/client_executor.py`](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/client_executor.py) (Client runtime), [`weaviate/connect/v4.py`](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/connect/v4.py) (Connection), [`weaviate/collections/collection/base.py`](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/collection/base.py) (Collection API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and transport"]
  node_client_api["Client API<br/>[client.py]"]
  node_client_runtime["Client runtime<br/>[client_executor.py]"]
  node_connection["Connection<br/>[v4.py]"]
  node_transport_executor["Sync/async executor<br/>[executor.py]"]
  node_auth["Authentication<br/>[authentication.py]"]
end

subgraph group_collections["Collections and data"]
  node_collection_api["Collection API<br/>[base.py]"]
  node_collection_management["Collection management<br/>[base.py]"]
  node_collection_config["Collection configuration<br/>[executor.py]"]
end

subgraph group_operations["Data operations"]
  node_data_operations["Object data<br/>[executor.py]"]
  node_query_api["Query API<br/>[query.py]"]
  node_grpc_query["gRPC query<br/>[query.py]"]
  node_batching["Batching<br/>[client.py]"]
  node_backups["Backups<br/>[executor.py]"]
  node_exports["Exports<br/>[executor.py]"]
end

subgraph group_admin["Administration"]
  node_cluster["Cluster operations<br/>[base.py]"]
  node_rbac["Roles and permissions<br/>[executor.py]"]
  node_users["User management<br/>[base.py]"]
  node_groups_api["Group management<br/>[base.py]"]
  node_tokenization["Tokenization<br/>[executor.py]"]
end

node_application(("Application"))
node_weaviate_server(("Weaviate instance"))

node_application -->|"creates client"| node_client_api
node_client_api -->|"inherits runtime"| node_client_runtime
node_client_runtime -->|"uses connection"| node_connection
node_client_runtime -->|"dispatches calls"| node_transport_executor
node_connection -->|"uses auth"| node_auth
node_connection -.->|"sends requests"| node_weaviate_server
node_client_api -->|"exposes collections"| node_collection_api
node_client_api -->|"exposes management"| node_collection_management
node_client_api -->|"exposes batching"| node_batching
node_client_api -->|"exposes backups"| node_backups
node_client_api -->|"exposes exports"| node_exports
node_client_api -->|"exposes cluster"| node_cluster
node_client_api -->|"exposes roles"| node_rbac
node_client_api -->|"exposes users"| node_users
node_client_api -->|"exposes groups"| node_groups_api
node_client_api -.->|"exposes configuration"| node_collection_config
node_collection_api -.->|"accesses objects"| node_data_operations
node_collection_api -.->|"offers queries"| node_query_api
node_query_api -.->|"executes queries"| node_grpc_query
node_client_api -.->|"exposes tokenization"| node_tokenization

click node_client_api "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/client.py"
click node_client_runtime "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/client_executor.py"
click node_connection "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/connect/v4.py"
click node_transport_executor "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/connect/executor.py"
click node_auth "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/connect/authentication.py"
click node_collection_api "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/collection/base.py"
click node_collection_management "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/collections/base.py"
click node_collection_config "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/config/executor.py"
click node_data_operations "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/data/executor.py"
click node_query_api "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/query.py"
click node_grpc_query "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/grpc/query.py"
click node_batching "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/batch/client.py"
click node_backups "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/backup/executor.py"
click node_exports "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/export/executor.py"
click node_cluster "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/cluster/base.py"
click node_rbac "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/rbac/executor.py"
click node_users "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/users/base.py"
click node_groups_api "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/groups/base.py"
click node_tokenization "https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/tokenization/executor.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_api,node_client_runtime,node_connection,node_transport_executor,node_auth toneBlue
class node_collection_api,node_collection_management,node_collection_config toneAmber
class node_data_operations,node_query_api,node_grpc_query,node_batching,node_backups,node_exports toneMint
class node_cluster,node_rbac,node_users,node_groups_api,node_tokenization toneRose
class node_application,node_weaviate_server toneIndigo
```

## Components

### Client and transport

- [Client API](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/client.py): `weaviate/client.py`
- [Client runtime](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/client_executor.py): `weaviate/client_executor.py`
- [Connection](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/connect/v4.py): `weaviate/connect/v4.py`
- [Sync/async executor](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/connect/executor.py): `weaviate/connect/executor.py`
- [Authentication](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/connect/authentication.py): `weaviate/connect/authentication.py`

### Collections and data

- [Collection API](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/collection/base.py): `weaviate/collections/collection/base.py`
- [Collection management](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/collections/base.py): `weaviate/collections/collections/base.py`
- [Collection configuration](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/config/executor.py): `weaviate/collections/config/executor.py`

### Data operations

- [Object data](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/data/executor.py): `weaviate/collections/data/executor.py`
- [Query API](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/query.py): `weaviate/collections/query.py`
- [gRPC query](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/grpc/query.py): `weaviate/collections/grpc/query.py`
- [Batching](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/collections/batch/client.py): `weaviate/collections/batch/client.py`
- [Backups](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/backup/executor.py): `weaviate/backup/executor.py`
- [Exports](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/export/executor.py): `weaviate/export/executor.py`

### Administration

- [Cluster operations](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/cluster/base.py): `weaviate/cluster/base.py`
- [Roles and permissions](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/rbac/executor.py): `weaviate/rbac/executor.py`
- [User management](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/users/base.py): `weaviate/users/base.py`
- [Group management](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/groups/base.py): `weaviate/groups/base.py`
- [Tokenization](https://github.com/weaviate/weaviate-python-client/blob/main/weaviate/tokenization/executor.py): `weaviate/tokenization/executor.py`

### Other components

- **Application**
- **Weaviate instance**

## Connections

- Application → Client API: creates client (evidence: `weaviate/client.py`)
- Client API → Client runtime: inherits runtime (evidence: `weaviate/client.py`)
- Client runtime → Connection: uses connection (evidence: `weaviate/client_executor.py`)
- Client runtime → Sync/async executor: dispatches calls (evidence: `weaviate/client_executor.py`)
- Connection → Authentication: uses auth (evidence: `weaviate/connect/v4.py`)
- Connection → Weaviate instance: sends requests
- Client API → Collection API: exposes collections (evidence: `weaviate/client.py`)
- Client API → Collection management: exposes management (evidence: `weaviate/client.py`)
- Client API → Batching: exposes batching (evidence: `weaviate/client.py`)
- Client API → Backups: exposes backups (evidence: `weaviate/client.py`)
- Client API → Exports: exposes exports (evidence: `weaviate/client.py`)
- Client API → Cluster operations: exposes cluster (evidence: `weaviate/client.py`)
- Client API → Roles and permissions: exposes roles (evidence: `weaviate/client.py`)
- Client API → User management: exposes users (evidence: `weaviate/client.py`)
- Client API → Group management: exposes groups (evidence: `weaviate/client.py`)
- Client API → Collection configuration: exposes configuration
- Collection API → Object data: accesses objects
- Collection API → Query API: offers queries
- Query API → gRPC query: executes queries
- Client API → Tokenization: exposes tokenization
