Configuration

Configuration

Work in Progress

This page is a work in progress and may not be complete.

Common Configurations Options

Server Configuration

Core

`IS_PERSISTENT`

Defines whether Chroma should persist data or not.

Possible values:

TRUE
FALSE

Default: FALSE

`PERSIST_DIRECTORY`

Defines the directory where Chroma should persist data. This can be relative or absolute path. The directory must be writeable to Chroma process.

Default: ./chroma

`ALLOW_RESET`

Defines whether Chroma should allow resetting the index (delete all data).

Possible values:

TRUE
FALSE

Default: FALSE

`CHROMA_MEMORY_LIMIT_BYTES`

`CHROMA_SEGMENT_CACHE_POLICY`

Telemetry and Observability

`CHROMA_OTEL_COLLECTION_ENDPOINT`

`CHROMA_OTEL_SERVICE_NAME`

`CHROMA_OTEL_COLLECTION_HEADERS`

`CHROMA_OTEL_GRANULARITY`

`CHROMA_PRODUCT_TELEMETRY_IMPL`

`CHROMA_TELEMETRY_IMPL`

`ANONYMIZED_TELEMETRY`

Enables or disables anonymized product telemetry.

Possible values:

TRUE - Enables anonymized telemetry.
FALSE - Disables anonymized telemetry.

Default: TRUE (enabled)

Read more about how Chroma uses telemetry here.

Maintenance

`MIGRATIONS`

Defines how schema migrations are handled in Chroma.

Possible values:

none - No migrations are applied.
validate - Existing schema is validated.
apply - Migrations are applied.

Default: apply

`MIGRATIONS_HASH_ALGORITHM`

Operations and Distributed

`CHROMA_SYSDB_IMPL`

`CHROMA_PRODUCER_IMPL`

`CHROMA_CONSUMER_IMPL`

`CHROMA_SEGMENT_MANAGER_IMPL`

`CHROMA_SEGMENT_DIRECTORY_IMPL`

`CHROMA_MEMBERLIST_PROVIDER_IMPL`

`WORKER_MEMBERLIST_NAME`

`CHROMA_COORDINATOR_HOST`

`CHROMA_SERVER_GRPC_PORT`

`CHROMA_LOGSERVICE_HOST`

`CHROMA_LOGSERVICE_PORT`

`CHROMA_QUOTA_PROVIDER_IMPL`

`CHROMA_RATE_LIMITING_PROVIDER_IMPL`

Authentication

`CHROMA_AUTH_TOKEN_TRANSPORT_HEADER`

`CHROMA_CLIENT_AUTH_PROVIDER`

`CHROMA_CLIENT_AUTH_CREDENTIALS`

`CHROMA_SERVER_AUTH_IGNORE_PATHS`

`CHROMA_OVERWRITE_SINGLETON_TENANT_DATABASE_ACCESS_FROM_AUTH`

`CHROMA_SERVER_AUTHN_PROVIDER`

`CHROMA_SERVER_AUTHN_CREDENTIALS`

`CHROMA_SERVER_AUTHN_CREDENTIALS_FILE`

Authorization

`CHROMA_SERVER_AUTHZ_PROVIDER`

`CHROMA_SERVER_AUTHZ_CONFIG`

`CHROMA_SERVER_AUTHZ_CONFIG_FILE`

Client Configuration

Authentication

HNSW Configuration

HNSW is the underlying library for Chroma vector indexing and search. Chroma exposes a number of parameters to configure HNSW for your use case. All HNSW parameters are configured as metadata for a collection.

Changing HNSW parameters

Some HNSW parameters cannot be changed after index creation via the standard method shown below. If you which to change these parameters, you will need to clone the collection see an example here.

`hnsw:space`

Description: Controls the distance metric of the HNSW index. The space cannot be changed after index creation.

Default: l2

Constraints:

Possible values: l2, cosine, ip
Parameter cannot be changed after index creation.

`hnsw:construction_ef`

Description: Controls the number of neighbours in the HNSW graph to explore when adding new vectors. The more neighbours HNSW explores the better and more exhaustive the results will be. Increasing the value will also increase memory consumption.

Default: 100

Constraints:

Values must be positive integers.
Parameter cannot be changed after index creation.

`hnsw:M`

Description: Controls the maximum number of neighbour connections (M), a newly inserted vector. A higher value results in a mode densely connected graph. The impact on this is slower but more accurate searches with increased memory consumption.

Default: 16

Constraints:

Values must be positive integers.
Parameter cannot be changed after index creation.

`hnsw:search_ef`

Description: Controls the number of neighbours in the HNSW graph to explore when searching. Increasing this requires more memory for the HNSW algo to explore the nodes during knn search.

Default: 10

Constraints:

Values must be positive integers.
Parameter can be changed after index creation.

`hnsw:num_threads`

Description: Controls how many threads HNSW algo use.

Default: <number of CPU cores>

Constraints:

Values must be positive integers.
Parameter can be changed after index creation.

`hnsw:resize_factor`

Description: Controls the rate of growth of the graph (e.g. how many node capacity will be added) whenever the current graph capacity is reached.

Default: 1.2

Constraints:

Values must be positive floating point numbers.
Parameter can be changed after index creation.

`hnsw:batch_size`

Description: Controls the size of the Bruteforce (in-memory) index. Once this threshold is crossed vectors from BF gets transferred to HNSW index. This value can be changed after index creation. The value must be less than hnsw:sync_threshold.

Default: 100

Constraints:

Values must be positive integers.
Parameter can be changed after index creation.

`hnsw:sync_threshold`

Description: Controls the threshold when using HNSW index is written to disk.

Default: 1000

Constraints:

Values must be positive integers.
Parameter can be changed after index creation.

Examples

Configuring HNSW parameters at creation time

import chromadb
client = chromadb.HttpClient()  # Adjust as per your client
res = client.create_collection("my_collection", metadata={
    "hnsw:space": "cosine",
    "hnsw:construction_ef": 100,
    "hnsw:M": 16,
    "hnsw:search_ef": 10,
    "hnsw:num_threads": 4,
    "hnsw:resize_factor": 1.2,
    "hnsw:batch_size": 100,
    "hnsw:sync_threshold": 1000,
})

Updating HNSW parameters after creation

import chromadb
client = chromadb.HttpClient()  # Adjust as per your client
res = client.get_or_create_collection("my_collection", metadata={
    "hnsw:search_ef": 200,
    "hnsw:num_threads": 8,
    "hnsw:resize_factor": 2,
    "hnsw:batch_size": 10000,
    "hnsw:sync_threshold": 1000000,
})

get_or_create_collection overrides

When using get_or_create_collection() with metadata parameter, existing metadata will be overridden with the new values.

July 31, 2024