Metadata-Version: 2.4
Name: chromie-tool
Version: 0.5.0
Summary: Chroma import/export tool.
License-Expression: GPL-3.0-or-later
Keywords: chroma,chromadb,cli,export,import,tool,vector database
Author: Raúl G. González
Author-email: raul@chromio.dev
Requires-Python: >=3.12.0, <3.14.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
Requires-Dist: chromadb (>=1.2.2,<2.0.0)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: jsonschema (>=4.25.1,<5.0.0)
Project-URL: Homepage, https://github.com/chromiodev/chromie
Project-URL: Repository, https://github.com/chromiodev/chromie
Description-Content-Type: text/markdown

# chromie-tool

**Chroma** ([https://trychroma.com](https://trychroma.com)) import/export tool.


## Install

```bash
# install
pip install chromie-tool

# check chromie tool
which chromie
```


## Commands

### Help

```bash
# chromie help
chromie -h

# exp command help
chromie exp -h
```

### Download prepared datasets

Prepared datasets: [https://github.com/chromiodev/datasets](https://github.com/chromiodev/datasets).

```bash
chromie dl -l es eurostat/prc_hicp_manr
```

### Export

```bash
chromie exp server://localhost:8000/tenant/db/collection file.json
```

### Check an export file

```bash
chromie check prc_hicp_manr-es.json
```

### Import

```bash
# import all the content of movies.json
chromie imp movies.json server://localhost:8000/tenant/db/collection

# import all the content of movies.json, skipping the cert and rating metadata
chromie imp movies.json -M cert,rating server://localhost:8000/tenant/db/collection

# import all the content of movies.json, setting the cert and dir metadata
# to the specified values
chromie imp movies.json -m cert:C,dir:D server://localhost:8000/tenant/db/collection
```

### Copy

```bash
chromie cp server://///coll1 server://///coll2
```

### Listing the database collections

```bash
# only names
chromie ls server:////

# names and counts
chromie ls -c server:////
```

### Metadata filters

The **`--metafilter`** or **`-f`** options allow to select records from metadata in the **`cp`** and **`exp`** commands.
Format:

```
predicate
predicate and predicate
predicate or predicate
```

Examples:

```
-f "director='Quentin Tarantino'"
-f "director='Quentin Tarantino' or director='Alfred Hitchcock'"
```

Operators: **`=`**, **`!=`**, **`>`**, **`>=`**, **`<`**, **`<=`**, **`and`** and **`or`**.

Boolean literals: **`true`**, **`True`**, **`false`** and **`False`**.

> **Constraint**.
> Right now, only one or two predicates are possible.
> In the future, it will be resolved and this note removed.


## URIs

### Server URI

Format:

```
server://host:port/tenant/database
server://host:port/tenant/database/collection
```

When a segment must take its value from the default value or an environment variable, this must be left blank.
Examples:

```
server://///
server:///tenant/db
```

Environment variables we can use for settings segments in server URIs:

- **`CHROMA_HOST`**

- **`CHROMA_PORT`**

- **`CHROMA_TENANT`**

- **`CHROMA_DATABASE`**

The default values in server URIs, when blank segments and environment variable unset, are these set in the **chromadb** package.
Right now:

- **Host**: ***localhost***

- **Port**: ***8000***

- **Tenant**: ***default_tenant***

- **Database**: ***default_database***

### Chroma Cloud URI

Format:

```
cloud:///tenant/db
cloud:///tenant/db/collection
```

Similar to the ***server*** schema but, with the ***cloud*** schema, the environment variables we can use are the following:

- **`CHROMA_TENANT`**

- **`CHROMA_DATABASE`**

Default values:

- **host:port** segment is always ***api.trychroma.com:8000***.

- Tenant and database don't have default values, these must be set explicitly or with environment variables.

### Checking and decomposing URIs

With **`chromie uri`**, we check and decompose a URI.
Examples:

```
$ chromie uri server:////
Schema: server
Host: localhost
Port: 8000
Tenant: default_tenant
Database: default_database

$ CHROMA_PORT=8888 chromie uri server:////
Schema: server
Host: localhost
Port: 8888
Tenant: default_tenant
Database: default_database

$ CHROMA_DATABASE=testdb chromie uri server://me//
Schema: server
Host: me
Port: 8000
Tenant: default_tenant
Database: testdb
```

### Pinging database instance and/or collection

Examples:

```
# database instance
chromie ping server:////

# database collection
chromie ping server://///movies
chromie ping cloud://///movies
```


## API key

When API key needed, **`--key`** or **`-k`** must be set.
We can use the **`CHROMA_API_KEY`** environment variable too.

