> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema Basics

> Learn how to create and use Schema to configure indexes on your Chroma collections.

export const Callout = ({title, children}) => <div className="my-6">
    <div className="relative pr-1.5 pb-1.5">
      <div className="absolute top-1.5 left-1.5 right-0 bottom-0 bg-blue-500 dark:bg-blue-600" />
      <div className="relative border border-black dark:border-gray-500 px-5 py-4 bg-white dark:bg-neutral-900">
        {title && <p className="block mb-2"><strong>{title}</strong></p>}
        {children}
      </div>
    </div>
  </div>;

## Schema Structure

A Schema has two main components that work together to control indexing behavior:

### Defaults

Defaults define index configuration for **all keys** of a given data type. When you add metadata to your collection, Chroma looks at the value type (string, int, float, etc.) and applies the default index configuration for that type.

For example, if you disable string inverted indexes globally, no string metadata fields will be indexed unless you create a key-specific override.

### Keys

Keys define index configuration for **specific metadata fields**. These override the defaults for individual fields, giving you fine-grained control.

For example, you might disable string indexing globally but enable it specifically for a "category" field that you frequently filter on.

### How They Work Together

When determining whether to index a field, Chroma follows this precedence:

1. **Key-specific configuration** (if exists) - highest priority
2. **Default configuration** (for that value type) - fallback
3. **Built-in defaults** (if no Schema provided) - final fallback

This means you can set broad defaults and then override them for specific fields as needed.

## Default Index Behavior

Without providing a Schema, collections use built-in defaults for indexing. For a complete overview of all value types, index types, and their defaults, see the [Index Configuration Reference](./index-reference#index-types-overview).

### Special Keys

Chroma uses two reserved key names:

**`K.DOCUMENT`** (`#document`) stores document text content with FTS enabled and String Inverted Index disabled. This allows full-text search while avoiding redundant indexing.

**`K.EMBEDDING`** (`#embedding`) stores dense vector embeddings with Vector Index enabled, sourcing from `K.DOCUMENT`. This enables semantic similarity search.

<Callout>
  Use `K.DOCUMENT` and `K.EMBEDDING` in your code (they correspond to internal keys `#document` and `#embedding`). These special keys are automatically configured and cannot be manually modified. See the [Search API field reference](../search-api/pagination-selection#available-fields) for more details.
</Callout>

### Example: Using Defaults

<CodeGroup>
  ```python Python theme={null}
  # Without Schema - uses defaults from table above
  collection = client.create_collection(name="my_collection")

  collection.add(
      ids=["id1"],
      documents=["Some text"],    # FTS index
      embeddings=[[1.0, 2.0]],    # Vector index
      metadatas=[{
          "category": "science",  # String inverted index
          "year": 2024,           # Int inverted index
          "score": 0.95,          # Float inverted index
          "published": True       # Bool inverted index
      }]
  )
  ```

  ```typescript TypeScript theme={null}
  // Without Schema - uses defaults from table above
  const collection = await client.createCollection({ name: "my_collection" });

  await collection.add({
    ids: ["id1"],
    documents: ["Some text"],
    metadatas: [{
      category: "science",  // String inverted index
      year: 2024,           // Int inverted index
      score: 0.95,          // Float inverted index
      published: true       // Bool inverted index
    }]
  });
  ```
</CodeGroup>

## Creating Schema Objects

Create a Schema object to customize index configuration:

<CodeGroup>
  ```python Python theme={null}
  from chromadb import Schema

  # Create an empty schema (starts with defaults)
  schema = Schema()

  # The schema is now ready to be configured
  ```

  ```typescript TypeScript theme={null}
  import { Schema } from 'chromadb';

  // Create an empty schema (starts with defaults)
  const schema = new Schema();

  // The schema is now ready to be configured
  ```
</CodeGroup>

## Creating Indexes

### The create\_index() Method

Use `create_index()` to enable or configure indexes. The method takes:

* `config`: An index configuration object (or `None` to enable all indexes for a key)
* `key`: Optional - specify a metadata field name for key-specific configuration

The method returns the Schema object, enabling method chaining.

### Creating Global Indexes

Create indexes that apply globally. This example shows configuring the vector index with custom settings:

<CodeGroup>
  ```python Python theme={null}
  from chromadb import Schema, VectorIndexConfig
  from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction

  schema = Schema()

  # Configure vector index with custom embedding function
  embedding_function = OpenAIEmbeddingFunction(
      api_key_env_var="OPENAI_API_KEY",
      model_name="text-embedding-3-small"
  )

  schema.create_index(config=VectorIndexConfig(
      space="cosine",
      embedding_function=embedding_function
  ))
  ```

  ```typescript TypeScript theme={null}
  import { Schema, VectorIndexConfig } from 'chromadb';
  import { OpenAIEmbeddingFunction } from '@chroma-core/openai';

  const schema = new Schema();

  // Configure vector index with custom embedding function
  const embeddingFunction = new OpenAIEmbeddingFunction({
    apiKeyEnvVar: "OPENAI_API_KEY",
    modelName: "text-embedding-3-small"
  });

  schema.createIndex(new VectorIndexConfig({
    space: "cosine",
    embeddingFunction: embeddingFunction
  }));
  ```
</CodeGroup>

### Creating Key-Specific Indexes

Configure indexes for specific metadata fields. This example shows configuring the sparse vector index with custom settings:

<CodeGroup>
  ```python Python theme={null}
  from chromadb import Schema, SparseVectorIndexConfig, K
  from chromadb.utils.embedding_functions import ChromaCloudSpladeEmbeddingFunction

  schema = Schema()

  # Add sparse vector index for a specific key (required for hybrid search)
  sparse_ef = ChromaCloudSpladeEmbeddingFunction()
  schema.create_index(
      config=SparseVectorIndexConfig(
          source_key=K.DOCUMENT,
          embedding_function=sparse_ef
      ),
      key="sparse_embedding"
  )
  ```

  ```typescript TypeScript theme={null}
  import { Schema, SparseVectorIndexConfig, K } from 'chromadb';
  import { ChromaCloudSpladeEmbeddingFunction } from '@chroma-core/chroma-cloud-splade';

  const schema = new Schema();

  // Add sparse vector index for a specific key (required for hybrid search)
  const sparseEf = new ChromaCloudSpladeEmbeddingFunction({
    apiKeyEnvVar: "CHROMA_API_KEY"
  });

  schema.createIndex(
    new SparseVectorIndexConfig({
      sourceKey: K.DOCUMENT,
      embeddingFunction: sparseEf
    }),
    "sparse_embedding"
  );
  ```
</CodeGroup>

<Callout>
  This example uses `ChromaCloudSpladeEmbeddingFunction`, but you can use other sparse embedding functions like `HuggingFaceSparseEmbeddingFunction` or `FastembedSparseEmbeddingFunction` depending on your needs.
</Callout>

## Disabling Indexes

### The delete\_index() Method

Use `delete_index()` to disable indexes. Like `create_index()`, it takes:

* `config`: An index configuration object (or `None` to disable all indexes for a key)
* `key`: Optional - specify a metadata field name for key-specific configuration

Returns the Schema object for method chaining.

### Examples

<CodeGroup>
  ```python Python theme={null}
  from chromadb import Schema, StringInvertedIndexConfig, IntInvertedIndexConfig

  schema = Schema()

  # Disable string inverted index globally
  schema.delete_index(config=StringInvertedIndexConfig())

  # Disable int inverted index for a specific key
  schema.delete_index(config=IntInvertedIndexConfig(), key="unimportant_count")

  # Disable all indexes for a specific key
  schema.delete_index(key="temporary_field")
  ```

  ```typescript TypeScript theme={null}
  import { Schema, StringInvertedIndexConfig, IntInvertedIndexConfig } from 'chromadb';

  const schema = new Schema();

  // Disable string inverted index globally
  schema.deleteIndex(new StringInvertedIndexConfig());

  // Disable int inverted index for a specific key
  schema.deleteIndex(new IntInvertedIndexConfig(), "unimportant_count");

  // Disable all indexes for a specific key
  schema.deleteIndex(undefined, "temporary_field");
  ```
</CodeGroup>

<Callout>
  **Note:** Not all indexes can be deleted. Vector indexes currently cannot be disabled.
</Callout>

<Callout>
  **Array metadata and indexes:** Array metadata (e.g. `[1, 2, 3]` or `["action", "comedy"]`) shares the same inverted index as its scalar counterpart. Disabling `IntInvertedIndexConfig` will also prevent `$contains` and `$not_contains` queries on integer arrays, and similarly for other types.
</Callout>

## Method Chaining

Both `create_index()` and `delete_index()` return the Schema object, enabling fluent method chaining:

<CodeGroup>
  ```python Python theme={null}
  from chromadb import Schema, StringInvertedIndexConfig, IntInvertedIndexConfig

  schema = (Schema()
      .delete_index(config=StringInvertedIndexConfig())  # Disable globally
      .create_index(config=StringInvertedIndexConfig(), key="category")  # Enable for category
      .create_index(config=StringInvertedIndexConfig(), key="tags")  # Enable for tags
      .delete_index(config=IntInvertedIndexConfig()))  # Disable int indexing
  ```

  ```typescript TypeScript theme={null}
  import { Schema, StringInvertedIndexConfig, IntInvertedIndexConfig } from 'chromadb';

  const schema = new Schema()
    .deleteIndex(new StringInvertedIndexConfig())  // Disable globally
    .createIndex(new StringInvertedIndexConfig(), "category")  // Enable for category
    .createIndex(new StringInvertedIndexConfig(), "tags")  // Enable for tags
    .deleteIndex(new IntInvertedIndexConfig());  // Disable int indexing
  ```
</CodeGroup>

## Using Schema with Collections

Pass the configured schema to `create_collection()` or `get_or_create_collection()`:

<CodeGroup>
  ```python Python theme={null}
  # Create collection with schema
  collection = client.create_collection(
      name="my_collection",
      schema=schema
  )

  # Or use get_or_create_collection
  collection = client.get_or_create_collection(
      name="my_collection",
      schema=schema
  )
  ```

  ```typescript TypeScript theme={null}
  // Create collection with schema
  const collection = await client.createCollection({
    name: "my_collection",
    schema: schema
  });

  // Or use getOrCreateCollection
  const collection = await client.getOrCreateCollection({
    name: "my_collection",
    schema: schema
  });
  ```
</CodeGroup>

### Schema Persistence

Schema configuration is automatically saved with the collection. When you retrieve a collection with `get_collection()` or `get_or_create_collection()`, the schema is loaded automatically. You don't need to provide the schema again.

## Next Steps

* Set up [sparse vector search](./sparse-vector-search) with sparse vectors
* Browse the complete [index configuration reference](./index-reference)