0
# Client Creation
1

2
ChromaDB provides multiple client types for different deployment scenarios, from in-memory testing to production cloud deployments. Each client type implements the same core API while optimizing for specific use cases.
3

4
## Capabilities
5

6
### EphemeralClient
7

8
Creates an in-memory ChromaDB instance ideal for testing and development. Data is not persisted and is lost when the process ends.
9

10
```python { .api }
11
def EphemeralClient(
12
    settings: Optional[Settings] = None,
13
    tenant: str = "default_tenant",
14
    database: str = "default_database"
15
) -> ClientAPI:
16
    """
17
    Creates an in-memory instance of Chroma.
18
    
19
    Args:
20
        settings: Optional Settings object for configuration
21
        tenant: The tenant to use for this client
22
        database: The database to use for this client
23
        
24
    Returns:
25
        ClientAPI: A client instance for interacting with ChromaDB
26
    """
27
```
28

29
**Usage Example:**
30

31
```python
32
import chromadb
33

34
client = chromadb.EphemeralClient()
35
collection = client.create_collection("test_collection")
36
```
37

38
### PersistentClient
39

40
Creates a ChromaDB instance that persists data to disk, suitable for local development and single-machine deployments.
41

42
```python { .api }
43
def PersistentClient(
44
    path: Union[str, Path] = "./chroma",
45
    settings: Optional[Settings] = None,
46
    tenant: str = "default_tenant",
47
    database: str = "default_database"
48
) -> ClientAPI:
49
    """
50
    Creates a persistent instance of Chroma that saves to disk.
51
    
52
    Args:
53
        path: The directory to save Chroma's data to
54
        settings: Optional Settings object for configuration
55
        tenant: The tenant to use for this client
56
        database: The database to use for this client
57
        
58
    Returns:
59
        ClientAPI: A client instance for interacting with ChromaDB
60
    """
61
```
62

63
**Usage Example:**
64

65
```python
66
import chromadb
67

68
client = chromadb.PersistentClient(path="/path/to/chroma/data")
69
collection = client.create_collection("my_collection")
70
```
71

72
### HttpClient
73

74
Creates a client that connects to a remote ChromaDB server over HTTP, supporting production deployments with multiple clients.
75

76
```python { .api }
77
def HttpClient(
78
    host: str = "localhost",
79
    port: int = 8000,
80
    ssl: bool = False,
81
    headers: Optional[Dict[str, str]] = None,
82
    settings: Optional[Settings] = None,
83
    tenant: str = "default_tenant",
84
    database: str = "default_database"
85
) -> ClientAPI:
86
    """
87
    Creates a client that connects to a remote Chroma server.
88
    
89
    Args:
90
        host: The hostname of the Chroma server
91
        port: The port of the Chroma server
92
        ssl: Whether to use SSL to connect to the server
93
        headers: A dictionary of headers to send to the server
94
        settings: Optional Settings object for configuration
95
        tenant: The tenant to use for this client
96
        database: The database to use for this client
97
        
98
    Returns:
99
        ClientAPI: A client instance for interacting with ChromaDB
100
    """
101
```
102

103
**Usage Example:**
104

105
```python
106
import chromadb
107

108
client = chromadb.HttpClient(
109
    host="my-chroma-server.com",
110
    port=8000,
111
    ssl=True,
112
    headers={"Authorization": "Bearer my-token"}
113
)
114
collection = client.get_collection("my_collection")
115
```
116

117
### AsyncHttpClient
118

119
Creates an async client for connecting to remote ChromaDB servers, enabling concurrent operations and integration with async Python frameworks.
120

121
```python { .api }
122
async def AsyncHttpClient(
123
    host: str = "localhost",
124
    port: int = 8000,
125
    ssl: bool = False,
126
    headers: Optional[Dict[str, str]] = None,
127
    settings: Optional[Settings] = None,
128
    tenant: str = "default_tenant",
129
    database: str = "default_database"
130
) -> AsyncClientAPI:
131
    """
132
    Creates an async client that connects to a remote Chroma server.
133
    
134
    Args:
135
        host: The hostname of the Chroma server
136
        port: The port of the Chroma server
137
        ssl: Whether to use SSL to connect to the server
138
        headers: A dictionary of headers to send to the server
139
        settings: Optional Settings object for configuration
140
        tenant: The tenant to use for this client
141
        database: The database to use for this client
142
        
143
    Returns:
144
        AsyncClientAPI: An async client instance for interacting with ChromaDB
145
    """
146
```
147

148
**Usage Example:**
149

150
```python
151
import chromadb
152
import asyncio
153

154
async def main():
155
    client = await chromadb.AsyncHttpClient(host="my-server.com", ssl=True)
156
    collection = await client.get_collection("my_collection")
157
    
158
asyncio.run(main())
159
```
160

161
### CloudClient
162

163
Creates a client for connecting to ChromaDB cloud service with built-in authentication and managed infrastructure.
164

165
```python { .api }
166
def CloudClient(
167
    tenant: Optional[str] = None,
168
    database: Optional[str] = None,
169
    api_key: Optional[str] = None,
170
    settings: Optional[Settings] = None,
171
    *,
172
    cloud_host: str = "api.trychroma.com",
173
    cloud_port: int = 443,
174
    enable_ssl: bool = True
175
) -> ClientAPI:
176
    """
177
    Creates a client to connect to a tenant and database on Chroma cloud.
178
    
179
    Args:
180
        tenant: The tenant to use (can be inferred from API key)
181
        database: The database to use (can be inferred from API key)
182
        api_key: The API key for authentication (or set CHROMA_API_KEY env var)
183
        settings: Optional Settings object for configuration
184
        cloud_host: The cloud service hostname
185
        cloud_port: The cloud service port
186
        enable_ssl: Whether to use SSL
187
        
188
    Returns:
189
        ClientAPI: A client instance for interacting with ChromaDB Cloud
190
    """
191
```
192

193
**Usage Example:**
194

195
```python
196
import chromadb
197

198
client = chromadb.CloudClient(api_key="your-api-key")  # or set CHROMA_API_KEY
199
collection = client.get_collection("my_collection")
200
```
201

202
### RustClient
203

204
Creates a client using the Rust-based implementation for improved performance, supporting both ephemeral and persistent modes.
205

206
```python { .api }
207
def RustClient(
208
    path: Optional[str] = None,
209
    settings: Optional[Settings] = None,
210
    tenant: str = "default_tenant",
211
    database: str = "default_database"
212
) -> ClientAPI:
213
    """
214
    Creates a Rust-backed Chroma client instance.
215
    
216
    Args:
217
        path: Optional directory to save data (ephemeral if None)
218
        settings: Optional Settings object for configuration
219
        tenant: The tenant to use for this client
220
        database: The database to use for this client
221
        
222
    Returns:
223
        ClientAPI: A client instance using Rust implementation
224
    """
225
```
226

227
**Usage Example:**
228

229
```python
230
import chromadb
231

232
# Ephemeral Rust client
233
client = chromadb.RustClient()
234

235
# Persistent Rust client
236
client = chromadb.RustClient(path="/path/to/data")
237
```
238

239
### Generic Client
240

241
Creates a client using the current global settings, providing a flexible factory method.
242

243
```python { .api }
244
def Client(
245
    settings: Settings = None,
246
    tenant: str = "default_tenant",
247
    database: str = "default_database"
248
) -> ClientAPI:
249
    """
250
    Return a running chroma.API instance using current settings.
251
    
252
    Args:
253
        settings: Settings object (uses global settings if None)
254
        tenant: The tenant to use for this client
255
        database: The database to use for this client
256
        
257
    Returns:
258
        ClientAPI: A client instance based on current configuration
259
    """
260
```
261

262
### AdminClient
263

264
Creates an admin client for managing tenants and databases, providing elevated privileges for system administration.
265

266
```python { .api }
267
def AdminClient(settings: Settings = None) -> AdminAPI:
268
    """
269
    Creates an admin client for tenant and database management.
270
    
271
    Args:
272
        settings: Settings object for configuration
273
        
274
    Returns:
275
        AdminAPI: An admin client for system management operations
276
    """
277
```
278

279
**Usage Example:**
280

281
```python
282
import chromadb
283

284
admin = chromadb.AdminClient()
285
admin.create_tenant("new_tenant")
286
admin.create_database("new_database", tenant="new_tenant")
287
```
288

289
### AdminAPI Methods
290

291
The AdminAPI provides database and tenant management capabilities for system administration.
292

293
```python { .api }
294
class AdminAPI:
295
    def create_database(
296
        self, 
297
        name: str, 
298
        tenant: str = "default_tenant"
299
    ) -> None:
300
        """
301
        Create a new database.
302
        
303
        Args:
304
            name: The name of the database to create
305
            tenant: The tenant to create the database in
306
        """
307
    
308
    def get_database(
309
        self, 
310
        name: str, 
311
        tenant: str = "default_tenant"
312
    ) -> Database:
313
        """
314
        Get information about a database.
315
        
316
        Args:
317
            name: The name of the database
318
            tenant: The tenant the database belongs to
319
            
320
        Returns:
321
            Database: Database information
322
        """
323
    
324
    def delete_database(
325
        self, 
326
        name: str, 
327
        tenant: str = "default_tenant"
328
    ) -> None:
329
        """
330
        Delete a database.
331
        
332
        Args:
333
            name: The name of the database to delete
334
            tenant: The tenant the database belongs to
335
        """
336
    
337
    def list_databases(
338
        self, 
339
        limit: Optional[int] = None, 
340
        offset: Optional[int] = None, 
341
        tenant: str = "default_tenant"
342
    ) -> Sequence[Database]:
343
        """
344
        List databases in a tenant.
345
        
346
        Args:
347
            limit: Maximum number of databases to return
348
            offset: Number of databases to skip
349
            tenant: The tenant to list databases for
350
            
351
        Returns:
352
            Sequence[Database]: List of databases
353
        """
354
    
355
    def create_tenant(self, name: str) -> None:
356
        """
357
        Create a new tenant.
358
        
359
        Args:
360
            name: The name of the tenant to create
361
        """
362
    
363
    def get_tenant(self, name: str) -> Tenant:
364
        """
365
        Get information about a tenant.
366
        
367
        Args:
368
            name: The name of the tenant
369
            
370
        Returns:
371
            Tenant: Tenant information
372
        """
373
```
374

375
**AdminAPI Usage Example:**
376

377
```python
378
import chromadb
379

380
# Create admin client
381
admin = chromadb.AdminClient()
382

383
# Manage tenants
384
admin.create_tenant("my_organization")
385
tenant = admin.get_tenant("my_organization")
386

387
# Manage databases
388
admin.create_database("production_db", tenant="my_organization")
389
admin.create_database("staging_db", tenant="my_organization")
390

391
databases = admin.list_databases(tenant="my_organization")
392
print(f"Found {len(databases)} databases")
393

394
# Clean up
395
admin.delete_database("staging_db", tenant="my_organization")
396
```
397

398
## Types
399

400
```python { .api }
401
from pathlib import Path
402
from typing import Dict, Optional, Union
403

404
Settings = chromadb.config.Settings
405
ClientAPI = chromadb.api.ClientAPI
406
AsyncClientAPI = chromadb.api.AsyncClientAPI
407
AdminAPI = chromadb.api.AdminAPI
408
```