[ENH] Add support for default space in create coll config #5293

jairad26 · 2025-08-16T19:41:02Z

Description of changes

This PR adds support for using default space defined in the embedding function when populating collection config if not provided by the user. It also adds validation for supported space in ef in case the user defines a space that is not supported by the embedding function and/or model

Test plan

Added unit tests in js and

How are these changes tested?

Tests pass locally with pytest for python, yarn test for js, cargo test for rust

Migration plan

Are there any migrations, or any forwards/backwards compatibility changes needed in order to make sure this change deploys reliably?

No

Observability plan

What is the plan to instrument and monitor this change?

N/A

Documentation Changes

Are all docstrings for user-facing APIs updated if required? Do we need to make documentation changes in the docs section?

No changes needed

jairad26 · 2025-08-16T19:41:18Z

[ENH] Add support for default space in create coll config #5293 👈 (View in Graphite)
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

github-actions · 2025-08-16T19:41:20Z

propel-code-bot · 2025-08-16T20:20:52Z

Support Default Embedding Space in Collection Configuration, with Space Validation

This PR introduces enhanced logic for handling default vector spaces in collection configurations when creating collections in ChromaDB. If a user does not explicitly provide a distance space (e.g., 'cosine', 'l2') in the configuration or metadata, the system now sets it to the embedding function's defined default. Furthermore, the changes add validation to ensure that any user-provided space is supported by the relevant embedding function/model; unsupported combinations produce warnings (not errors) to adhere to robustness principles. Accompanying this feature are major test expansions for both Python and JavaScript, and updates to client, serialization, server/database, and embedding function logic across the stack.

Key Changes

• Collection configuration logic now uses the embedding functions default space if space isnt set in the HNSW/SPANN config or legacy metadata.
• Validation warns (rather than errors) if the requested space (from config or metadata) is not supported by the embedding functions ``supported_spaces' list.
• Explicit handling and prioritization between configuration, legacy metadata, and default space for setting the collection's distance metric.
• Updates to test suites in Python and TypeScript/Jest to cover default space selection, valid and invalid space combinations, prioritization logic, and warnings.
• Minor corrections in embedding function implementations to ensure supported_spaces and default_space methods exist where needed.
• Client, server (HTTP, gRPC, Rust, Segment), and system/database layers updated to pass metadata where needed and ensure space population/validation logic is preserved across APIs.
• pnpm lockfile and dependency adjustments for JS client compatibility.

Affected Areas

• chromadb/api/collection_configuration.py (core config logic and validation)
• chromadb/db/mixins/sysdb.py, chromadb/db/impl/grpc/client.py, chromadb/api/fastapi.py, chromadb/api/async_fastapi.py, chromadb/api/rust.py, chromadb/api/segment.py (all updated to handle/propagate metadata and config)
• utils/embedding_functions (baseten and cohere EF: add/adjust default_space and supported_spaces)
• clients/new-js/packages/chromadb/src/collection-configuration.ts (JS config logic and validation)
• clients/new-js/packages/chromadb/src/chroma-client.ts (propagating metadata to processCreateCollectionConfig)
• clients/new-js/packages/chromadb/test/collection.config.client.test.ts (comprehensive new and updated tests)
• chromadb/test/configurations/test_collection_configuration.py (comprehensive new and updated tests)
• clients/new-js/pnpm-lock.yaml (dependency update)

This summary was automatically generated by @propel-code-bot

propel-code-bot · 2025-08-16T20:25:49Z

chromadb/api/collection_configuration.py

+            if hnsw_config is not None and hnsw_config.get("space") is None:
+                hnsw_config["space"] = ef.default_space()
+            if spann_config is not None and spann_config.get("space") is None:
+                spann_config["space"] = ef.default_space()


[BestPractice]

The logic for handling hnsw_config and spann_config mutations can lead to unexpected side effects. When you modify these dictionaries with hnsw_config["space"] = ef.default_space(), you're potentially mutating the original input parameters, which could affect the caller's data.

Consider creating copies before modification:

Suggested change

if hnsw_config is not None and hnsw_config.get("space") is None:

hnsw_config["space"] = ef.default_space()

if spann_config is not None and spann_config.get("space") is None:

spann_config["space"] = ef.default_space()

# if hnsw config or spann config exists but space is not provided, populate it from ef

if hnsw_config is not None and hnsw_config.get("space") is None:

hnsw_config = dict(hnsw_config) # Create a copy to avoid mutation

hnsw_config["space"] = ef.default_space()

if spann_config is not None and spann_config.get("space") is None:

spann_config = dict(spann_config) # Create a copy to avoid mutation

spann_config["space"] = ef.default_space()

⚡ Committable suggestion

Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.

This is a valid point @jai, we shouldn't mutate callers. Suggest higher up in the code we copy or remove the mutation. Imagine I create many collections with the same config

propel-code-bot · 2025-08-17T19:04:22Z

clients/new-js/packages/chromadb/src/collection-configuration.ts

+  // Get the effective embedding function for space validation and defaults
+  const effectiveEmbeddingFunction = embeddingFunction || configuration?.embeddingFunction;
+
+  if (effectiveEmbeddingFunction && effectiveEmbeddingFunction.defaultSpace && effectiveEmbeddingFunction.supportedSpaces) {
+    // If no vector index config exists but we have an embedding function,
+    // create default HNSW config with space from embedding function
+    if (configuration?.hnsw === undefined && configuration?.spann === undefined) {
+      if (metadata === undefined || metadata?.["hnsw:space"] === undefined) {
+        // this populates space from ef if not provided in either config or metadata
+        if (!configuration) configuration = {};
+        configuration.hnsw = { space: effectiveEmbeddingFunction.defaultSpace() };
+      }
+    }
+
+    // If HNSW config exists but space is not provided, populate it from embedding function
+    if (configuration?.hnsw && !configuration.hnsw.space && effectiveEmbeddingFunction.defaultSpace) {
+      configuration.hnsw.space = effectiveEmbeddingFunction.defaultSpace();
+    }
+
+    // If SPANN config exists but space is not provided, populate it from embedding function
+    if (configuration?.spann && !configuration.spann.space && effectiveEmbeddingFunction.defaultSpace) {
+      configuration.spann.space = effectiveEmbeddingFunction.defaultSpace();
+    }
+
+    // Validate space compatibility with embedding function
+    if (effectiveEmbeddingFunction.supportedSpaces) {
+      const supportedSpaces = effectiveEmbeddingFunction.supportedSpaces();
+
+      if (configuration?.hnsw?.space && !supportedSpaces.includes(configuration.hnsw.space)) {
+        throw new ChromaValueError(
+          `Space '${configuration.hnsw.space}' is not supported by embedding function '${effectiveEmbeddingFunction.name || 'unknown'}'. ` +
+          `Supported spaces: ${supportedSpaces.join(', ')}`
+        );
+      }
+
+      if (configuration?.spann?.space && !supportedSpaces.includes(configuration.spann.space)) {
+        throw new ChromaValueError(
+          `Space '${configuration.spann.space}' is not supported by embedding function '${configuration.spann.space}'. ` +
+          `Supported spaces: ${supportedSpaces.join(', ')}`
+        );
+      }
+
+      // Validate space compatibility with metadata legacy space config
+      if (metadata && metadata["hnsw:space"] && !supportedSpaces.includes(metadata["hnsw:space"])) {
+        throw new ChromaValueError(
+          `Space '${metadata["hnsw:space"]}' from metadata is not supported by embedding function '${effectiveEmbeddingFunction.name || 'unknown'}'. ` +
+          `Supported spaces: ${supportedSpaces.join(', ')}`
+        );
+      }
+    }
+  }


[BestPractice]

Similar to the Python implementation, the logic here for validating the distance space (space) could lead to incorrect validation failures due to its handling of precedence. The code independently validates the space from the configuration object and the legacy metadata.

If a user provides a valid space in configuration.hnsw.space but also has an outdated, invalid hnsw:space in metadata, this function will throw an error, even though the metadata value would be correctly ignored in favor of the configuration value.

To improve this, the logic should first determine the single effective space value by checking configuration, then metadata, and finally the embedding function's default. Only this final, effective value should be validated. This would align with the principle that the configuration object is the primary source of truth and metadata is for backward compatibility.

chromadb/test/configurations/test_collection_configuration.py

chromadb/api/collection_configuration.py

clients/new-js/packages/chromadb/src/collection-configuration.ts

itaismith · 2025-08-18T01:08:10Z

clients/new-js/packages/chromadb/src/collection-configuration.ts

 }: {
  configuration?: CreateCollectionConfiguration;
  embeddingFunction?: EmbeddingFunction | null;
+  metadata?: Record<string, any>;


I think there should be a Metadata type

HammadB · 2025-08-18T03:40:06Z

chromadb/api/collection_configuration.py

+            # Validate space compatibility with embedding function
+            if hnsw_config is not None:
+                if hnsw_config.get("space") not in ef.supported_spaces():
+                    raise InvalidSpaceError(


I don't think this should error, if you override, we should just warn, you may know what you are doing.

In spirit of https://en.wikipedia.org/wiki/Robustness_principle

HammadB · 2025-08-18T03:41:59Z

chromadb/api/collection_configuration.py

@@ -383,12 +386,47 @@ def create_collection_configuration_to_json(
        if ef.is_legacy():
            ef_config = {"type": "legacy"}
        else:
+            if hnsw_config is None and spann_config is None:


A comment a the top level explaining the intended fallback strategy would be helpful

HammadB · 2025-08-18T03:42:26Z

chromadb/api/collection_configuration.py

@@ -383,12 +386,47 @@ def create_collection_configuration_to_json(
        if ef.is_legacy():
            ef_config = {"type": "legacy"}
        else:
+            if hnsw_config is None and spann_config is None:


What happens if you set both? Should we error?

thats handled earlier in the client, itll error saying you can only set one

chroma/chromadb/api/collection_configuration.py

Line 369 in 163133a

if hnsw_config is not None and spann_config is not None:

HammadB · 2025-08-18T04:03:09Z

chromadb/api/collection_configuration.py

+                        UserWarning,
+                        stacklevel=2,
+                    )
+            if (


I don't fully understand this last branch

a user couldve set the config with some values but also the space in the metadata. in that case, we've determined to ignore the metadata, so we should only validate and warn if we're going to use the space (which would only happen if neither hnsw nor spann were specified

jairad26 force-pushed the jai/default-space branch from 1afbb8b to 118338e Compare August 16, 2025 20:19

jairad26 marked this pull request as ready for review August 16, 2025 20:20

propel-code-bot bot reviewed Aug 16, 2025

View reviewed changes

blacksmith-sh bot deleted a comment from jairad26 Aug 16, 2025

jairad26 force-pushed the jai/default-space branch from 118338e to dea4784 Compare August 17, 2025 19:00

propel-code-bot bot reviewed Aug 17, 2025

View reviewed changes

jairad26 force-pushed the jai/default-space branch from dea4784 to 30be1d5 Compare August 17, 2025 19:16

propel-code-bot bot reviewed Aug 17, 2025

View reviewed changes

chromadb/test/configurations/test_collection_configuration.py Outdated Show resolved Hide resolved

jairad26 force-pushed the jai/default-space branch 2 times, most recently from 12bdb8b to 5cdede2 Compare August 17, 2025 19:25

propel-code-bot bot reviewed Aug 17, 2025

View reviewed changes

chromadb/api/collection_configuration.py Outdated Show resolved Hide resolved

blacksmith-sh bot deleted a comment from jairad26 Aug 17, 2025

jairad26 force-pushed the jai/default-space branch from 5cdede2 to 77ade2c Compare August 17, 2025 22:54

propel-code-bot bot reviewed Aug 17, 2025

View reviewed changes

chromadb/api/collection_configuration.py Outdated Show resolved Hide resolved

propel-code-bot bot reviewed Aug 17, 2025

View reviewed changes

clients/new-js/packages/chromadb/src/collection-configuration.ts Outdated Show resolved Hide resolved

blacksmith-sh bot deleted a comment from jairad26 Aug 17, 2025

jairad26 force-pushed the jai/default-space branch from 77ade2c to b147d4d Compare August 17, 2025 23:36

itaismith approved these changes Aug 18, 2025

View reviewed changes

jairad26 force-pushed the jai/default-space branch 4 times, most recently from 28c7e00 to 1ae0a5b Compare August 18, 2025 01:39

HammadB reviewed Aug 18, 2025

View reviewed changes

jairad26 force-pushed the jai/default-space branch from 1ae0a5b to 65ec09a Compare August 18, 2025 04:00

HammadB reviewed Aug 18, 2025

View reviewed changes

[ENH] Add support for default space in create coll config

1e04570

jairad26 force-pushed the jai/default-space branch from 65ec09a to 1e04570 Compare August 18, 2025 04:05

HammadB approved these changes Aug 18, 2025

View reviewed changes

jairad26 enabled auto-merge (squash) August 18, 2025 04:24

jairad26 merged commit 51a7d16 into main Aug 18, 2025
61 checks passed

[ENH] Add support for default space in create coll config #5293

[ENH] Add support for default space in create coll config #5293

Uh oh!

Conversation

jairad26 commented Aug 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of changes

Test plan

Migration plan

Observability plan

Documentation Changes

Uh oh!

jairad26 commented Aug 16, 2025

Uh oh!

github-actions bot commented Aug 16, 2025

Reviewer Checklist

Testing, Bugs, Errors, Logs, Documentation

System Compatibility

Quality

Uh oh!

propel-code-bot bot commented Aug 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

propel-code-bot bot Aug 16, 2025

Choose a reason for hiding this comment

Uh oh!

HammadB Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

propel-code-bot bot Aug 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

itaismith Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

HammadB Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HammadB Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

jairad26 Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

HammadB Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

jairad26 Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

HammadB Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jairad26 Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HammadB Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

jairad26 Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jairad26 commented Aug 16, 2025 •

edited

Loading

propel-code-bot bot commented Aug 16, 2025 •

edited

Loading

HammadB Aug 18, 2025 •

edited

Loading

HammadB Aug 18, 2025 •

edited

Loading

jairad26 Aug 18, 2025 •

edited

Loading

jairad26 Aug 18, 2025 •

edited

Loading