---
title: "Collection definition"
description: "Reference for Weaviate collection parameters."
url: https://docs.weaviate.io/weaviate/config-refs/collections
---

# Collection definition

A **collection definition** specifies how to store and index a set of data objects in Weaviate. This page discusses the available parameters for configuring a collection.

## Collection definition parameters

These are the top-level parameters you can set when creating a collection.

| Parameter | Type | Description | Default | Mutable |
| - | - | - | - | - |
| [`class`](https://docs.weaviate.io/weaviate/config-refs/collections#class) | String | The name of the collection. | (Required) | No |
| [`description`](https://docs.weaviate.io/weaviate/config-refs/collections#description) | String | A description of the collection. | `""` | Yes |
| [`properties`](https://docs.weaviate.io/weaviate/config-refs/collections#properties) | Array | An array of property objects defining the data schema. | `[]` | Partially\* |
| [`invertedIndexConfig`](https://docs.weaviate.io/weaviate/config-refs/collections#inverted-index) | Object | Configuration for the inverted index, affecting filtering and keyword search. | See [Inverted Index reference](https://docs.weaviate.io/weaviate/config-refs/indexing/inverted-index#inverted-index-parameters) | Yes |
| [`vectorConfig`](https://docs.weaviate.io/weaviate/config-refs/collections#vector-configuration) | Object | Configure multiple named vectors each with their own `vectorizer`, `vectorIndexType`, and `vectorIndexConfig` fields. | `null` | Partially\*\* |
| [`vectorizer`](https://docs.weaviate.io/weaviate/config-refs/collections#vector-configuration) | String | The vectorizer module to use. | `none` if any other top-level vector parameter is set. Otherwise unset: the collection has no vector (see [Collections without a vector](https://docs.weaviate.io/weaviate/config-refs/collections#no-vector)). See [Model provider](https://docs.weaviate.io/weaviate/model-providers) for module-specific config defaults | No |
| [`vectorIndexType`](https://docs.weaviate.io/weaviate/config-refs/collections#vector-configuration) | String | The type of vector index to use (`hnsw`, `flat`, `dynamic`, `hfresh`). | `hnsw` if any other top-level vector parameter is set. Otherwise unset: the collection has no vector (see [Collections without a vector](https://docs.weaviate.io/weaviate/config-refs/collections#no-vector)) | No |
| [`moduleConfig`](https://docs.weaviate.io/weaviate/config-refs/collections#module-configuration) | Object | Module-specific configuration settings. | See [Module configuration](https://docs.weaviate.io/weaviate/config-refs/collections#module-configuration) | Partially |
| [`vectorIndexConfig`](https://docs.weaviate.io/weaviate/config-refs/collections#vector-configuration) | Object | Configuration settings specific to the chosen `vectorIndexType`. | See [Vector index reference](https://docs.weaviate.io/weaviate/config-refs/indexing/vector-index) | Partially |
| [`shardingConfig`](https://docs.weaviate.io/weaviate/config-refs/collections#sharding) | Object | Controls sharding behavior in a multi-node cluster. | See [Sharding section](https://docs.weaviate.io/weaviate/config-refs/collections#sharding) | No |
| [`replicationConfig`](https://docs.weaviate.io/weaviate/config-refs/collections#replication) | Object | Controls data replication settings for fault tolerance. | See [Replication section](https://docs.weaviate.io/weaviate/config-refs/collections#replication) | Partially |
| [`multiTenancyConfig`](https://docs.weaviate.io/weaviate/config-refs/collections#multi-tenancy) | Object | Configuration to enable multi-tenancy for the collection. | See [Multi-tenancy section](https://docs.weaviate.io/weaviate/config-refs/collections#multi-tenancy) | Partially |
| [`objectTtlConfig`](https://docs.weaviate.io/weaviate/config-refs/collections#object-ttl) | Object | Sets a time to live (TTL) after which the collection's objects expire. | Disabled | Yes |

\* [New properties can be added](https://docs.weaviate.io/weaviate/manage-collections/collection-operations#add-a-property); existing properties cannot be modified\
\*\* [New named vectors can be added](https://docs.weaviate.io/weaviate/manage-collections/vector-config#add-new-named-vectors) and, from `v1.40`, [a named vector can be dropped](https://docs.weaviate.io/weaviate/manage-collections/vector-config#drop-a-named-vector); some vector index settings are mutable

**Example collection configuration - JSON object**

An example of a complete collection object including properties:

```json
{
  "class": "Article",                       // The name of the collection in string format
  "description": "An article",              // A description for your reference
  "vectorIndexType": "hnsw",                // Defaults to hnsw
  "vectorIndexConfig": {
    ...                                     // Vector index type specific settings, including distance metric
  },
  "vectorizer": "text2vec-contextionary",   // Vectorizer to use for data objects added to this collection
  "moduleConfig": {
    "text2vec-contextionary": {
      "vectorizeClassName": true            // Include the collection name in vector calculation (default true)
    }
  },
  "properties": [                           // An array of the properties you are adding, same as a Property Object
    {
      "name": "title",                     // The name of the property
      "description": "title of the article",              // A description for your reference
      "dataType": [                         // The data type of the object as described above. When
                                            //    creating cross-references, a property can have
                                            //    multiple data types, hence the array syntax.
        "text"
      ],
      "moduleConfig": {                     // Module-specific settings
        "text2vec-contextionary": {
          "skip": true,                     // If true, the whole property will NOT be included in
                                            //    vectorization. Default is false, meaning that the
                                            //    object will be NOT be skipped.
          "vectorizePropertyName": true,    // Whether the name of the property is used in the
                                            //    calculation for the vector position of data
                                            //    objects. Default false.
        }
      },
      "indexFilterable": true,              // Optional, default is true. By default each property
                                            //    is indexed with a roaring bitmap index where
                                            //     available for efficient filtering.
      "indexSearchable": true               // Optional, default is true. By default each property
                                            //    is indexed with a searchable index for
                                            //    BM25-suitable Map index for BM25 or hybrid
                                            //    searching.
    }
  ],
  "invertedIndexConfig": {                  // Optional, index configuration
    "stopwords": {
      ...                                   // Optional, controls which words should be ignored in the inverted index, see section below
    },
    "indexTimestamps": false,               // Optional, maintains inverted indexes for each object by its internal timestamps
    "indexNullState": false,                // Optional, maintains inverted indexes for each property regarding its null state
    "indexPropertyLength": false            // Optional, maintains inverted indexes for each property by its length
  },
  "shardingConfig": {
    ...                                     // Optional, controls behavior of the collection in a
                                            //    multi-node setting, see section below
  },
  "multiTenancyConfig": {"enabled": true}   // Optional, for enabling multi-tenancy for this
                                            //    collection (default: false)
}
```

#### Code example - How to create a collection

This code example shows how to configure the collection parameters through a client library:

**Python**

```py
from weaviate.classes.config import (
    Configure,
    DataType,
    Property,
    ReplicationDeletionStrategy,
    VectorDistances,
    VectorFilterStrategy,
)

client.collections.create(
    "Article",
    description="A collection of articles",
    properties=[
        Property(name="title", data_type=DataType.TEXT),
        Property(name="body", data_type=DataType.TEXT),
    ],
    vector_config=Configure.Vectors.text2vec_openai(
        name="default",
        source_properties=["title", "body"],
        vector_index_config=Configure.VectorIndex.hnsw(
            ef_construction=300,
            distance_metric=VectorDistances.COSINE,
            filter_strategy=VectorFilterStrategy.SWEEPING,
        ),
    ),
    multi_tenancy_config=Configure.multi_tenancy(False),
    sharding_config=Configure.sharding(
        virtual_per_physical=128,
        desired_count=1,
        desired_virtual_count=128,
    ),
    replication_config=Configure.replication(
        factor=1,
        deletion_strategy=ReplicationDeletionStrategy.TIME_BASED_RESOLUTION,
    ),
)
```

**JavaScript/TypeScript**

```ts
import { configure, dataType, vectorDistances, vectors } from '@weaviate/node';

await client.collections.create({
  name: 'Article',
  description: 'A collection of articles',
  properties: [
    { name: 'title', dataType: dataType.TEXT },
    { name: 'body', dataType: dataType.TEXT },
  ],
  vectorizers: vectors.text2VecOpenAI({
    name: 'default',
    sourceProperties: ['title', 'body'],
    vectorIndexConfig: configure.vectorIndex.hnsw({
      efConstruction: 300,
      distanceMetric: vectorDistances.COSINE,
      filterStrategy: 'sweeping',
    }),
  }),
  multiTenancy: configure.multiTenancy({ enabled: false }),
  sharding: configure.sharding({
    virtualPerPhysical: 128,
    desiredCount: 1,
    desiredVirtualCount: 128,
  }),
  replication: configure.replication({
    factor: 1,
    deletionStrategy: 'TimeBasedResolution',
  }),
})
```

**Go (v6)**

```go
_, err := client.Collections.Create(ctx, collections.Collection{
  Name:        "Article",
  Description: "A collection of articles",
  Properties: []collections.Property{
    {Name: "title", DataType: collections.DataTypeText},
    {Name: "body", DataType: collections.DataTypeText},
  },
  Vectors: map[string]collections.VectorConfig{
    "default": {
      Index: vectorindex.HNSW{
        EfConstruction: 300,
        Distance:       vectorindex.DistanceCosine,
        FilterStrategy: vectorindex.FilterStrategySweeping,
      },
      Vectorizer: selfprovided.Vectorizer,
    },
  },
  MultiTenancy: &collections.MultiTenancyConfig{Enabled: false},
  Sharding: &collections.ShardingConfig{
    VirtualPerPhysical:  128,
    DesiredCount:        1,
    DesiredVirtualCount: 128,
  },
  Replication: &collections.ReplicationConfig{
    Factor:           1,
    DeletionStrategy: collections.TimeBasedResolution,
  },
})
if err != nil {
  // handle error
  panic(err)
}
```

**Java**

```java
client.collections.create("Article",
    col -> col
        .description("A collection of articles")
        .properties(Property.text("title"), Property.text("body"))
        .vectorConfig(VectorConfig.text2vecTransformers("default",
            vec -> vec.sourceProperties("title", "body")
                .vectorIndex(Hnsw.of(hnsw -> hnsw.efConstruction(300)
                    .distance(Distance.COSINE)
                    .filterStrategy(Hnsw.FilterStrategy.SWEEPING)))))
        .multiTenancy(mt -> mt.enabled(false))
        .sharding(s -> s.virtualPerPhysical(128)
            .desiredCount(1)
            .desiredVirtualCount(128))
        .replication(rep -> rep.replicationFactor(1)
            .deletionStrategy(DeletionStrategy.TIME_BASED_RESOLUTION)));
```

**C#**

```csharp
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = "Article",
        Description = "A collection of articles",
        Properties = [Property.Text("title"), Property.Text("body")],
        VectorConfig = new VectorConfigList
        {
            Configure.Vector(
                "default",
                v => v.Text2VecTransformers(),
                sourceProperties: ["title", "body"],
                index: new VectorIndex.HNSW()
                {
                    EfConstruction = 300,
                    Distance = VectorDistance.Cosine,
                    FilterStrategy = VectorIndexFilterStrategy.Sweeping,
                }
            ),
        },
        MultiTenancyConfig = new MultiTenancyConfig { Enabled = false },
        ShardingConfig = new ShardingConfig
        {
            VirtualPerPhysical = 128,
            DesiredCount = 1,
            DesiredVirtualCount = 128,
        },
        ReplicationConfig = new ReplicationConfig
        {
            Factor = 1,
            DeletionStrategy = DeletionStrategy.TimeBasedResolution,
        },
    }
);
```

> [!TIP]
>
> **Further resources**
>
> For more code examples and configuration guides visit the [How-to: Manage collections](https://docs.weaviate.io/weaviate/manage-collections) section.

#### `class`

The `class` is the name of the collection.

The collection name starts with an upper case letter. The upper case letter distinguishes collection names from primitive data types when the name is used as a property value.

Consider these examples that use the `dataType` property:

- `dataType: ["text"]` is a `text` data type.
- `dataType: ["Text"]` is a cross-reference type to a collection named `Text`.

After the first letter, collection names may use any GraphQL-compatible characters.

The collection name validation regex is `/^[A-Z][_0-9A-Za-z]*$/`.

> [!NOTE]
>
> **Capitalization**
>
> Weaviate follows GraphQL naming conventions.
>
> - Start collection names with an upper case letter.
> - Start property names with a lower case letter.
>
> If you use an initial upper case letter to define a property name, Weaviate changes it to a lower case letter internally.

#### `description`

A description of the collection. This is for your reference and can also provide additional information to the [Query Agent](https://docs.weaviate.io/query-agent).

---

### Properties

| Parameter | Type | Description | Default | Mutable |
| - | - | - | - | - |
| [`name`](https://docs.weaviate.io/weaviate/config-refs/collections#name) | String | The name of the property. | (Required) | No |
| [`dataType`](https://docs.weaviate.io/weaviate/config-refs/datatypes) | Array | An array containing one or more data types. For cross-references, use the capitalized collection name (e.g., `["Article"]`). | (Required) | No |
| `description` | String | A description of the property for your reference. | `null` | Yes |
| [`tokenization`](https://docs.weaviate.io/weaviate/config-refs/collections#tokenization) | String | For `text` properties, specifies how the text is split into tokens for inverted indexing. | `word` | No |
| [`indexInverted`](https://docs.weaviate.io/weaviate/config-refs/collections#inverted-index) | Boolean | If `true`, inverted index is enabled for this property. | `true` | No |
| [`indexFilterable`](https://docs.weaviate.io/weaviate/config-refs/collections#inverted-index) | Boolean | If `true`, builds a roaring bitmap index for this property to allow for efficient filtering. | `true` | No |
| [`indexSearchable`](https://docs.weaviate.io/weaviate/config-refs/collections#inverted-index) | Boolean | If `true`, builds a searchable map index for this property, suitable for BM25 or hybrid search. | `true` | No |
| [`indexRangeFilters`](https://docs.weaviate.io/weaviate/config-refs/collections#inverted-index) | Boolean | If `true`, builds a roaring bitmap index for numerical range-based filtering. | `false` | No |
| `moduleConfig` | Object | Module-specific settings, such as skipping vectorization for this property. | `{}` | No |

**Example property configuration - JSON object**

An example of a complete property object:

```json
{
  "name": "title", // The name of the property
  "description": "title of the article", // A description for your reference
  "dataType": [
    // The data type of the object as described above. When creating cross-references, a property can have multiple dataTypes.
    "text"
  ],
  "tokenization": "word", // Split field contents into word-tokens when indexing into the inverted index. See "Property Tokenization" below for more detail.
  "moduleConfig": {
    // Module-specific settings
    "text2vec-contextionary": {
      "skip": true, // If true, the whole property is NOT included in vectorization. Default is false, meaning that the object will be NOT be skipped.
      "vectorizePropertyName": true // Whether the name of the property is used in the calculation for the vector position of data objects. Default false.
    }
  },
  "indexFilterable": true, // Optional, default is true. By default each property is indexed with a roaring bitmap index where available for efficient filtering.
  "indexSearchable": true // Optional, default is true. By default each property is indexed with a searchable index for BM25-suitable Map index for BM25 or hybrid searching.
}
```

#### Code example - How to configure collection properties

This code example shows how to configure the property parameters through a client library:

**Python**

```py
from weaviate.classes.config import DataType, Property, Tokenization

# Note that you can use `client.collections.create_from_dict()` to create a collection from a v3-client-style JSON object
client.collections.create(
    "Article",
    vector_config=Configure.Vectors.text2vec_openai(),
    properties=[  # properties configuration is optional
        Property(
            name="title",
            data_type=DataType.TEXT,
            description="The article headline",
            tokenization=Tokenization.WORD,  # How the text is split for the inverted index
        ),
        Property(
            name="description",
            data_type=DataType.TEXT,
            skip_vectorization=True,  # Exclude this property from the vector
            index_searchable=False,  # Exclude it from keyword search
        ),
        Property(
            name="rating",
            data_type=DataType.NUMBER,
            index_range_filters=True,  # Index for range-based filtering
        ),
    ],
)
```

**JavaScript/TypeScript**

```ts
import { dataType, tokenization, vectors } from '@weaviate/node';

await client.collections.create({
  name: 'Article',
  vectorizers: vectors.text2VecOpenAI(),
  properties: [
    {
      name: 'title',
      dataType: dataType.TEXT,
      description: 'The article headline',
      tokenization: tokenization.WORD,  // How the text is split for the inverted index
    },
    {
      name: 'description',
      dataType: dataType.TEXT,
      skipVectorization: true,  // Exclude this property from the vector
      indexSearchable: false,  // Exclude it from keyword search
    },
    {
      name: 'rating',
      dataType: dataType.NUMBER,
      indexRangeFilters: true,  // Index for range-based filtering
    },
  ],
})
```

**Go (v6)**

```go
_, err := client.Collections.Create(ctx, collections.Collection{
  Name: "Article",
  Properties: []collections.Property{
    {Name: "title", DataType: collections.DataTypeText},
    {Name: "body", DataType: collections.DataTypeText},
  },
})
if err != nil {
  // handle error
  panic(err)
}
```

**Java**

```java
client.collections.create("Article",
    col -> col
        .vectorConfig(VectorConfig.text2vecTransformers())
        .properties(
            Property.text("title",
                p -> p.description("The article headline")
                    .tokenization(Tokenization.WORD)), // How the text is split for the inverted index
            Property.text("description",
                p -> p.skipVectorization(true) // Exclude this property from the vector
                    .indexSearchable(false)), // Exclude it from keyword search
            Property.number("rating",
                p -> p.indexRangeFilters(true)))); // Index for range-based filtering
```

**C#**

```csharp
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = "Article",
        VectorConfig = new VectorConfigList
        {
            Configure.Vector("default", v => v.Text2VecTransformers()),
        },
        Properties =
        [
            Property.Text(
                "title",
                description: "The article headline",
                tokenization: PropertyTokenization.Word // How the text is split for the inverted index
            ),
            Property.Text("description", indexSearchable: false), // Exclude it from keyword search
            Property.Number("rating", indexRangeFilters: true), // Index for range-based filtering
        ],
    }
);
```

> [!TIP]
>
> **Further resources**
>
> For more code example and configuration guides visit the [How-to: Manage collections](https://docs.weaviate.io/weaviate/manage-collections) section.

#### `name`

Property names can contain the following characters: `/[_A-Za-z][_0-9A-Za-z]*/`.

##### Reserved words

The following words are reserved and cannot be used as property names:

- `_additional`
- `id`
- `_id`

Additionally, we strongly recommend that you do not use the following words as property names, due to potential conflicts with future reserved words:

- `vector`
- `_vector`

##### Reserved suffixes

A property name may also not *end* in one of the following suffixes, because each would collide with an internal index that Weaviate derives from another property:

- `_searchable`
- `_rangeable`
- `_temp`
- `__meta_count`
- `_propertyLength`
- `_nullState`

A property whose name ends in one of these suffixes, such as `comments_temp`, is rejected with a validation error: `'comments_temp' is not a valid property name: suffix '_temp' is reserved for internal indices`.

This check runs when you create a collection or add a property to an existing collection. It is not applied when an existing collection definition is loaded, so a collection created before the check was introduced continues to work, and a backup that contains such a property still restores.

The check was added in `v1.38.0`, and backported to `v1.35.20`, `v1.36.15`, and `v1.37.5`.

#### `tokenization`

You can customize how `text` data is tokenized and indexed in the inverted index. Tokenization influences the results returned by the [`bm25`](https://docs.weaviate.io/weaviate/api/graphql/search-operators#bm25) and [`hybrid`](https://docs.weaviate.io/weaviate/api/graphql/search-operators#hybrid) operators, and [`where` filters](https://docs.weaviate.io/weaviate/api/graphql/filters).

Tokenization is a property-level configuration for `text` properties. [See how to set the tokenization option using a client library](https://docs.weaviate.io/weaviate/manage-collections/vector-config#property-level-settings)

**Example property configuration - JSON object**

```json
{
  "classes": [
    {
      "class": "Question",
      "properties": [
        {
          "dataType": ["text"],
          "name": "question",
          "tokenization": "word"
        },
      ],
      ...
      "vectorizer": "text2vec-openai"
    }
  ]
}
```

##### Standard tokenization methods

###### `word` tokenization

**Description**: Splits text by any non-alphanumeric characters, then lowercases each token. This is the default setting.

**Behavior examples**:

| Text | Tokens |
| - | - |
| `"Why, hello there!"` | `["why", "hello", "there"]` |
| `"Lois & Clark: The New Adventures of Superman"` | `["lois", "clark", "the", "new", "adventures", "of", "superman"]` |
| `"variable_name"` | `["variable", "name"]` |
| `"Email: john.doe@example.com"` | `["email", "john", "doe", "example", "com"]` |

**When to use**:

- Recommended for most general text data (articles, descriptions).
- When case-insensitivity and ignoring punctuation is desired for more forgiving searches.

---

###### `lowercase` tokenization

**Description**: Splits text by whitespace only, then lowercases each token. It preserves symbols that `word` tokenization would remove.

**Behavior examples**:

| Text | Tokens |
| - | - |
| `"Why, hello there!"` | `["why,", "hello", "there!"]` |
| `"Lois & Clark: The New Adventures of Superman"` | `["lois", "&", "clark:", "the", "new", "adventures", "of", "superman"]` |
| `"variable_name"` | `["variable_name"]` |
| `"Email: john.doe@example.com"` | `["email:", "john.doe@example.com"]` |

**When to use**:

- For technical data where symbols like `&`, `@`, or `_` are meaningful (e.g., code snippets, email addresses).
- When you need case-insensitive matching but must preserve symbols.

---

###### `whitespace` tokenization

**Description**: Splits text by whitespace only, preserving both case and symbols.

**Behavior examples**:

| Text | Tokens |
| - | - |
| `"Why, hello there!"` | `["Why,", "hello", "there!"]` |
| `"Lois & Clark: The New Adventures of Superman"` | `["Lois", "&", "Clark:", "The", "New", "Adventures", "of", "Superman"]` |
| `"variable_name"` | `["variable_name"]` |
| `"Email: john.doe@example.com"` | `["Email:", "john.doe@example.com"]` |

**When to use**:

- When case-sensitivity is important (e.g., for proper nouns, acronyms, or specific codes).
- Requires careful query construction to match case.

---

###### `field` tokenization

**Description**: Treats the entire value of the property as a single token. No splitting occurs.

**Behavior examples**:

| Text | Tokens |
| - | - |
| `"Why, hello there!"` | `["Why, hello there!"]` |
| `"variable_name"` | `["variable_name"]` |
| `"Email: john.doe@example.com"` | `["Email: john.doe@example.com"]` |

**When to use**:

- When you need to match the entire field value exactly.
- For properties containing unique identifiers like URLs, UUIDs, or email addresses.
- Limited use for keyword searches but powerful for exact filtering.

---

##### Language-specific tokenization

The standard tokenization methods work well for English and other languages that use spaces to separate words. For languages like Chinese, Japanese, and Korean that don't rely on spaces, Weaviate provides specialized tokenization methods.

**`gse`, `gse_ch` and `trigram` tokenization methods**

For Japanese and Chinese text, we recommend use of the `gse` family or `trigram` tokenization methods. These methods work better with these languages than the other methods as these languages are not easily able to be tokenized using whitespaces.

There are two `gse` values, and they load different dictionaries:

- `gse` uses the Japanese dictionary. Set `ENABLE_TOKENIZER_GSE` to `true` to load it.
- `gse_ch` uses the Chinese dictionary. Set `ENABLE_TOKENIZER_GSE_CH` to `true` to load it.

Use `gse_ch` for Chinese text. `gse` segments Chinese text with the Japanese dictionary, which returns poor tokens without raising an error.

Neither tokenizer is loaded by default, to save resources.

`gse` tokenization examples:

- `"素早い茶色の狐が怠けた犬を飛び越えた"`: `["素早", "素早い", "早い", "茶色", "の", "狐", "が", "怠け", "けた", "犬", "を", "飛び", "飛び越え", "越え", "た", "素早い茶色の狐が怠けた犬を飛び越えた"]`
- `"すばやいちゃいろのきつねがなまけたいぬをとびこえた"`: `["すばや", "すばやい", "やい", "いち", "ちゃ", "ちゃい", "ちゃいろ", "いろ", "のき", "きつ", "きつね", "つね", "ねが", "がな", "なま", "なまけ", "まけ", "けた", "けたい", "たい", "いぬ", "を", "とび", "とびこえ", "こえ", "た", "すばやいちゃいろのきつねがなまけたいぬをとびこえた"]`

> [!NOTE]
>
> **`trigram` for fuzzy matching**
>
> While originally designed for Asian languages, `trigram` tokenization is also highly effective for fuzzy matching and typo tolerance in other languages.

**`kagome_ja` tokenization method**

For Japanese text, `kagome_ja` tokenization method is also available. This uses the [`Kagome` tokenizer](https://github.com/ikawaha/kagome?tab=readme-ov-file) with a Japanese [MeCab IPA](https://github.com/ikawaha/kagome-dict/) dictionary to split the property text.

The `kagome_ja` tokenizer is not loaded by default to save resources. To use it, set the environment variable `ENABLE_TOKENIZER_KAGOME_JA` to `true` on the Weaviate instance.

`kagome_ja` tokenization examples:

- `"春の夜の夢はうつつよりもかなしき 夏の夜の夢はうつつに似たり 秋の夜の夢はうつつを超え 冬の夜の夢は心に響く 山のあなたに小さな村が見える 川の音が静かに耳に届く 風が木々を通り抜ける音 星空の下、すべてが平和である"`:
  - \[`"春", "の", "夜", "の", "夢", "は", "うつつ", "より", "も", "かなしき", "\n\t", "夏", "の", "夜", "の", "夢", "は", "うつつ", "に", "似", "たり", "\n\t", "秋", "の", "夜", "の", "夢", "は", "うつつ", "を", "超え", "\n\t", "冬", "の", "夜", "の", "夢", "は", "心", "に", "響く", "\n\n\t", "山", "の", "あなた", "に", "小さな", "村", "が", "見える", "\n\t", "川", "の", "音", "が", "静か", "に", "耳", "に", "届く", "\n\t", "風", "が", "木々", "を", "通り抜ける", "音", "\n\t", "星空", "の", "下", "、", "すべて", "が", "平和", "で", "ある"`]
- `"素早い茶色の狐が怠けた犬を飛び越えた"`:
  - `["素早い", "茶色", "の", "狐", "が", "怠け", "た", "犬", "を", "飛び越え", "た"]`
- `"すばやいちゃいろのきつねがなまけたいぬをとびこえた"`:
  - `["すばやい", "ちゃ", "いろ", "の", "きつね", "が", "なまけ", "た", "いぬ", "を", "とびこえ", "た"]`

**`kagome_kr` tokenization method**

For Korean text, we recommend use of the `kagome_kr` tokenization method. This uses the [`Kagome` tokenizer](https://github.com/ikawaha/kagome?tab=readme-ov-file) with a Korean MeCab ([mecab-ko-dic](https://bitbucket.org/eunjeon/mecab-ko-dic/src/master/)) dictionary to split the property text.

The `kagome_kr` tokenizer is not loaded by default to save resources. To use it, set the environment variable `ENABLE_TOKENIZER_KAGOME_KR` to `true` on the Weaviate instance.

`kagome_kr` tokenization examples:

- `"아버지가방에들어가신다"`:
  - `["아버지", "가", "방", "에", "들어가", "신다"]`
- `"아버지가 방에 들어가신다"`:
  - `["아버지", "가", "방", "에", "들어가", "신다"]`
- `"결정하겠다"`:
  - `["결정", "하", "겠", "다"]`

**Limit the number of `gse` and `Kagome` tokenizers**

The `gse` and `Kagome` tokenizers can be resource intensive and affect Weaviate's performance. You can limit the combined number of `gse` and `Kagome` tokenizers running at the same time using the [`TOKENIZER_CONCURRENCY_COUNT` environment variable](https://docs.weaviate.io/deploy/configuration/env-vars).

**Fuzzy matching with `trigram` tokenization**

The `trigram` tokenization method provides fuzzy matching capabilities by breaking text into overlapping 3-character sequences. This enables BM25 searches to find matches even with spelling errors or variations.

**Use cases for trigram fuzzy matching:**

- **Typo tolerance**: Find matches despite spelling errors (e.g., "Reliace" matches "Reliance")
- **Name reconciliation**: Match entity names with variations across datasets
- **Search-as-you-type**: Build autocomplete functionality
- **Partial matching**: Find objects with partial string matches

**How it works:**

When text is tokenized with `trigram`, it's broken into all possible 3-character sequences:

- `"hello"` → `["hel", "ell", "llo"]`
- `"world"` → `["wor", "orl", "rld"]`

Similar strings share many trigrams, enabling fuzzy matching:

- `"Morgan Stanley"` and `"Stanley Morgn"` share trigrams like `"sta", "tan", "anl", "nle", "ley"`

**Performance considerations:**

- Filtering behavior will change significantly, as text filtering will be done based on trigram-tokenized text, instead of whole words
- Creates larger inverted indexes due to more tokens
- May impact query performance for large datasets

> [!TIP]
>
> Use trigram tokenization selectively on fields where fuzzy matching is preferred. Keep exact-match fields with `word` or `field` tokenization for precision.

##### Decision guide

Use this table to quickly identify the right tokenization method for your data.

| If your data is... | Consider | Because |
| - | - | - |
| General text (articles, descriptions) | `word` | Case-insensitive, ignores punctuation, forgiving |
| Code, technical IDs with `_` or `-` | `lowercase` | Preserves symbols, case-insensitive |
| Names, acronyms where case matters | `whitespace` | Case-sensitive, preserves symbols |
| Email addresses, URLs, unique IDs | `field` | Requires exact matches |
| Chinese text | `gse_ch` or `trigram` | Proper word segmentation |
| Japanese text | `kagome_ja` or `trigram` | Proper morphological analysis |
| Korean text | `kagome_kr` or `trigram` | Proper morphological analysis |

##### Performance considerations

**Indexing speed**

- `word`, `lowercase`, `whitespace`: Fast, with similar performance.
- `field`: Fastest, as no splitting is required.
- `gse`, `trigram`, `kagome_*`: Slower due to more complex segmentation algorithms.

**Query performance**

- Simple tokenization methods (`word`, `lowercase`, `whitespace`): Fast.
- `field` with wildcard filters: Can be slow and should be used judiciously.
- Language-specific methods: Performance is similar to simple methods for queries.

**Index size**

- More tokens result in a larger index.
- `field`: Creates the smallest index (one token per value).
- `trigram`: Creates the largest index due to many overlapping trigrams.

---

### Inverted index

Weaviate uses **inverted indexes** to enable fast and efficient filtering and searching. The inverted index maps values (like words or numbers) to the objects that contain them in order to speed-up all attribute-based filtering (`where` filters) and keyword searching (`bm25`, `hybrid`). Disabling indexing for properties you will never query can speed up data imports and reduce disk usage.

More details about the `indexFilterable`, `indexSearchable` and `indexRangeFilters` property parameters, and about the collection-level `invertedIndexConfig` object, can be found in [Reference: Inverted index](https://docs.weaviate.io/weaviate/config-refs/indexing/inverted-index).

---

### Vector configuration

Weaviate supports two approaches for vector configuration:

- **Single vector collections**: One vector space per object using top-level parameters (`vectorizer`, `vectorIndexType`, `vectorIndexConfig`)
- **Multiple named vectors**: Multiple vector spaces per object using the `vectorConfig` parameter (**recommended**)

You cannot combine both approaches in the same collection definition at creation time. A definition that uses neither creates a [collection without a vector](https://docs.weaviate.io/weaviate/config-refs/collections#no-vector).

> [!TIP]
>
> **We recommend using `vectorConfig`**
>
> Using the `vectorConfig` parameter allows you to start with one vector per collection and adding [new named vectors](https://docs.weaviate.io/weaviate/manage-collections/vector-config#add-new-named-vectors) afterward.

#### Vector configuration parameters

| Parameter | Type | Description | Default | Mutable |
| - | - | - | - | - |
| `vectorizer` | String | The vectorizer module to use (e.g., `text2vec-cohere`). Set to `none` to disable auto-vectorization. [Available model providers](https://docs.weaviate.io/weaviate/model-providers) | `none` if any other top-level vector parameter is set. Otherwise unset: the collection has no vector (see [Collections without a vector](https://docs.weaviate.io/weaviate/config-refs/collections#no-vector)) | No |
| [`vectorIndexType`](https://docs.weaviate.io/weaviate/config-refs/indexing/vector-index) | String | Vector index type: `hnsw` (default), `flat`, `dynamic`, or `hfresh` | `hnsw` if any other top-level vector parameter is set. Otherwise unset: the collection has no vector (see [Collections without a vector](https://docs.weaviate.io/weaviate/config-refs/collections#no-vector)) | No |
| [`vectorIndexConfig`](https://docs.weaviate.io/weaviate/config-refs/indexing/vector-index) | Object | Configuration settings for your chosen `vectorIndexType` | Index-specific defaults | Partially\* |
| `vectorConfig` | Object | **Alternative to above**: Define multiple named vector spaces | `null` | Partially\*\* |
| ↪ `vectorConfig.<name>.vectorizer` | Object | Vectorizer config for this named vector (e.g., `{"text2vec-openai": {"properties": ["title"]}}`) | (Required) | No |
| [↪ `vectorConfig.<name>.vectorIndexType`](https://docs.weaviate.io/weaviate/config-refs/indexing/vector-index) | String | Index type for this named vector | `hnsw` | No |
| [↪ `vectorConfig.<name>.vectorIndexConfig`](https://docs.weaviate.io/weaviate/config-refs/indexing/vector-index) | Object | Index configuration for this named vector | Index-specific defaults | Partially\* |

\* See [vector index mutable parameters](https://docs.weaviate.io/weaviate/config-refs/indexing/vector-index) \*\* [New named vectors can be added](https://docs.weaviate.io/weaviate/manage-collections/vector-config#add-new-named-vectors) after collection creation, and from `v1.40` [a named vector can be dropped](https://docs.weaviate.io/weaviate/manage-collections/vector-config#drop-a-named-vector)

#### Single vector collections

> [!WARNING]
>
> **Prefer named vectors for new collections**
>
> Configuring a single vector with the top-level parameters is the older approach. Use [named vectors](https://docs.weaviate.io/weaviate/config-refs/collections#named-vectors) for new collections. You can [add named vectors](https://docs.weaviate.io/weaviate/manage-collections/vector-config#add-new-named-vectors) to a single vector collection later, but the original vector keeps its top-level configuration.

A collection that sets any of the top-level `vectorizer`, `vectorIndexType` or `vectorIndexConfig` parameters is a single vector collection. Weaviate fills in the remaining top-level parameters:

- `vectorizer` becomes `none`. See [Vector configuration defaults](https://docs.weaviate.io/deploy/migration#vector-config-defaults).
- `vectorIndexType` becomes the value of [`DEFAULT_VECTOR_INDEX`](https://docs.weaviate.io/deploy/configuration/env-vars#DEFAULT_VECTOR_INDEX), or `hnsw` if that variable is unset.
- `vectorIndexConfig.distance` becomes the value of [`DEFAULT_VECTOR_DISTANCE_METRIC`](https://docs.weaviate.io/deploy/configuration/env-vars#DEFAULT_VECTOR_DISTANCE_METRIC), or [`cosine`](https://docs.weaviate.io/weaviate/config-refs/distances) if that variable is unset.

To learn which properties of your data are vectorized, refer to the [Configure semantic indexing](https://docs.weaviate.io/weaviate/config-refs/indexing/vector-index#configure-semantic-indexing) section.

##### Code example - How to create single vector collection

This code example shows how to configure the vectorizer parameters for a single vector collection through a client library:

**Python**

```py
from weaviate.classes.config import (
    Configure,
    DataType,
    Property,
    VectorDistances,
    VectorFilterStrategy,
)

client.collections.create(
    "Article",
    vector_config=Configure.Vectors.text2vec_openai(
        name="default",  # (Optional) Set the name of the vector, default name is "default"
        source_properties=["title", "body"],  # (Optional) Set the source property(ies)
        vector_index_config=Configure.VectorIndex.hnsw(
            ef_construction=300,
            distance_metric=VectorDistances.COSINE,
            filter_strategy=VectorFilterStrategy.SWEEPING,
        ),  # (Optional) Set vector index options
        vectorize_collection_name=True,  # (Optional) Set to True to vectorize the collection name
    ),
    properties=[  # properties configuration is optional
        Property(name="title", data_type=DataType.TEXT, vectorize_property_name=True),
        Property(name="body", data_type=DataType.TEXT),
    ],
)
```

**JavaScript/TypeScript**

```ts
import { vectors, dataType } from '@weaviate/node';

await client.collections.create({
  name: 'Article',
  vectorizers: vectors.text2VecOpenAI(),
  properties: [
    { name: 'title', dataType: dataType.TEXT },
    { name: 'body', dataType: dataType.TEXT },
  ],
})
```

**Java**

```java
client.collections.create("Article",
    col -> col
        .vectorConfig(VectorConfig.text2vecTransformers("default", // (Optional) Set the name of the vector, default name is "default"
            vec -> vec.sourceProperties("title", "body") // (Optional) Set the source property(ies)
                .vectorIndex(Hnsw.of(hnsw -> hnsw.efConstruction(300)
                    .distance(Distance.COSINE)
                    .filterStrategy(Hnsw.FilterStrategy.SWEEPING))))) // (Optional) Set vector index options
        .properties( // properties configuration is optional
            Property.text("title", p -> p.vectorizePropertyName(true)),
            Property.text("body")));
```

**C#**

```csharp
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = "Article",
        VectorConfig = new VectorConfigList
        {
            Configure.Vector(
                "default", // (Optional) Set the name of the vector, default name is "default"
                v => v.Text2VecTransformers(vectorizeCollectionName: true),
                sourceProperties: ["title", "body"], // (Optional) Set the source property(ies)
                index: new VectorIndex.HNSW() // (Optional) Set vector index options
                {
                    EfConstruction = 300,
                    Distance = VectorDistance.Cosine,
                    FilterStrategy = VectorIndexFilterStrategy.Sweeping,
                }
            ),
        },
        // properties configuration is optional
        Properties = [Property.Text("title"), Property.Text("body")],
    }
);
```

**Go (v5)**

```go
  articleClass := &models.Class{
    Class:       "Article",
    Description: "Collection of articles",
    Vectorizer:  "text2vec-openai",
    Properties: []*models.Property{
      {
        Name:     "title",
        DataType: schema.DataTypeText.PropString(),
      },
      {
        Name:     "body",
        DataType: schema.DataTypeText.PropString(),
      },
    },
  }
```

**Go (v6)**

```go
_, err := client.Collections.Create(ctx, collections.Collection{
  Name: "Article",
  Properties: []collections.Property{
    {Name: "title", DataType: collections.DataTypeText},
    {Name: "body", DataType: collections.DataTypeText},
  },
  Vectors: map[string]collections.VectorConfig{
    "default": {Vectorizer: openai.Text2Vec{}},
  },
})
if err != nil {
  // handle error
  panic(err)
}
```

> [!TIP]
>
> **Further resources**
>
> For more code example and configuration guides visit the [How-to: Vectorizer and vector index config](https://docs.weaviate.io/weaviate/manage-collections/vector-config) guide.

#### Multiple vector embeddings (named vectors)

Collections can have multiple [named vectors](https://docs.weaviate.io/weaviate/config-refs/collections#named-vectors).

The vectors in a collection can have their own configurations. Each vector space can set its own index, its own compression algorithm, and its own vectorizer. This means you can use different vectorization models, and apply different distance metrics, to the same object.

To work with named vectors, adjust your queries to specify a target vector for [vector search](https://docs.weaviate.io/weaviate/search/similarity#named-vectors) or [hybrid search](https://docs.weaviate.io/weaviate/search/hybrid#named-vectors) queries.

##### Code example - How to create multiple named vectors

This code example shows how to configure multiple named vectors through a client library:

**Python**

```py
from weaviate.classes.config import (
    Configure,
    DataType,
    Property,
    VectorDistances,
    VectorFilterStrategy,
)

client.collections.create(
    "Article",
    vector_config=[
        Configure.Vectors.text2vec_openai(
            name="default",  # (Optional) Set the name of the vector, default name is "default"
            source_properties=[
                "title",
                "body",
            ],  # (Optional) Set the source property(ies)
            vector_index_config=Configure.VectorIndex.hnsw(
                ef_construction=300,
                distance_metric=VectorDistances.COSINE,
                filter_strategy=VectorFilterStrategy.SWEEPING,
            ),  # (Optional) Set vector index options
            vectorize_collection_name=True,  # (Optional) Set to True to vectorize the collection name
        ),
        Configure.Vectors.text2vec_openai(
            name="body_vectors",
            source_properties=["body"],
            vector_index_config=Configure.VectorIndex.flat(),
        ),
    ],
    properties=[  # properties configuration is optional
        Property(name="title", data_type=DataType.TEXT, vectorize_property_name=True),
        Property(name="body", data_type=DataType.TEXT),
    ],
)
```

**JavaScript/TypeScript**

```ts
import { vectors, dataType } from '@weaviate/node';

await client.collections.create({
  name: 'ArticleNV',

  vectorizers: [
    // Set a named vector with the "text2vec-cohere" vectorizer
    vectors.text2VecCohere({
      name: 'title',
      sourceProperties: ['title'],                      // (Optional) Set the source property(ies)
      vectorIndexConfig: configure.vectorIndex.hnsw()   // (Optional) Set the vector index configuration
    }),
    // Set a named vector with the "text2vec-openai" vectorizer
    vectors.text2VecOpenAI({
      name: 'title_country',
      sourceProperties: ['title', 'country'],            // (Optional) Set the source property(ies)
      vectorIndexConfig: configure.vectorIndex.hnsw()   // (Optional) Set the vector index configuration
    }),
    // Set a named vector for your own uploaded vectors
    vectors.selfProvided({
      name: 'custom_vector',
      vectorIndexConfig: configure.vectorIndex.hnsw()   // (Optional) Set the vector index configuration
    })
  ],

  properties: [
    { name: 'title', dataType: dataType.TEXT },
    { name: 'country', dataType: dataType.TEXT },
  ],
})
```

**Java**

```java
client.collections.create("Article",
    col -> col
        .vectorConfig(
            VectorConfig.text2vecTransformers("default",
                vec -> vec.sourceProperties("title", "body")
                    .vectorIndex(Hnsw.of(hnsw -> hnsw.efConstruction(300)
                        .distance(Distance.COSINE)
                        .filterStrategy(Hnsw.FilterStrategy.SWEEPING)))),
            VectorConfig.text2vecTransformers("body_vectors",
                vec -> vec.sourceProperties("body")
                    .vectorIndex(Flat.of())))
        .properties( // properties configuration is optional
            Property.text("title", p -> p.vectorizePropertyName(true)),
            Property.text("body")));
```

**C#**

```csharp
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = "Article",
        VectorConfig = new VectorConfigList
        {
            Configure.Vector(
                "default",
                v => v.Text2VecTransformers(vectorizeCollectionName: true),
                sourceProperties: ["title", "body"],
                index: new VectorIndex.HNSW()
                {
                    EfConstruction = 300,
                    Distance = VectorDistance.Cosine,
                    FilterStrategy = VectorIndexFilterStrategy.Sweeping,
                }
            ),
            Configure.Vector(
                "body_vectors",
                v => v.Text2VecTransformers(),
                sourceProperties: ["body"],
                index: new VectorIndex.Flat()
            ),
        },
        // properties configuration is optional
        Properties = [Property.Text("title"), Property.Text("body")],
    }
);
```

**Go (v5)**

```go
  articleClass := &models.Class{
    Class:       "ArticleNV",
    Description: "Collection of articles with named vectors",
    Properties: []*models.Property{
      {
        Name:     "title",
        DataType: schema.DataTypeText.PropString(),
      },
      {
        Name:     "country",
        DataType: schema.DataTypeText.PropString(),
      },
    },
    VectorConfig: map[string]models.VectorConfig{
      "title": {
        Vectorizer: map[string]interface{}{
          "text2vec-openai": map[string]interface{}{
            "properties": []string{"title"},
          },
        },
        VectorIndexType: "hnsw",
      },
      "title_country": {
        Vectorizer: map[string]interface{}{
          "text2vec-openai": map[string]interface{}{
            "properties": []string{"title", "country"},
          },
        },
        VectorIndexType: "hnsw",
      },
      "custom_vector": {
        Vectorizer: map[string]interface{}{
          "none": map[string]interface{}{},
        },
        VectorIndexType: "hnsw",
      },
    },
  }
```

**Go (v6)**

```go
_, err := client.Collections.Create(ctx, collections.Collection{
  Name: "Article",
  Properties: []collections.Property{
    {Name: "title", DataType: collections.DataTypeText},
    {Name: "body", DataType: collections.DataTypeText},
  },
  Vectors: map[string]collections.VectorConfig{
    // A vector generated from the title only.
    "title": {Vectorizer: model2vec.Text2Vec{Properties: []string{"title"}}},
    // A vector you supply yourself at import time.
    "custom": {Vectorizer: selfprovided.Vectorizer},
  },
})
if err != nil {
  // handle error
  panic(err)
}
```

> [!TIP]
>
> **Further resources**
>
> For more code example and configuration guides visit the [How-to: Vectorizer and vector index config](https://docs.weaviate.io/weaviate/manage-collections/vector-config) guide.

#### The `default` vector name

`default` is a reserved vector name, and it means different things in the two approaches.

**Single vector collections.** `default` is an alias for the collection's top-level vector. A write that sends `vectors: {"default": [...]}` is stored there. On searches the alias is only partly supported: GraphQL accepts `default` as an explicit target, while gRPC search and aggregate and the REST Search API reject it. Omit the target on a single vector collection to use the top-level vector.

The alias is not part of the collection definition, so `GET /v1/schema` returns the top-level parameters and no `vectorConfig` entry, unless named vectors were added later. You can add named vectors to such a collection, but not one called `default`, because that name is already taken by the top-level vector.

**Collections that use `vectorConfig`.** `default` is an ordinary named vector with no special behavior. It is the name Weaviate gives the vector that [auto-schema](https://docs.weaviate.io/weaviate/config-refs/collections#auto-schema) creates.

#### Collections without a vector

> [!NOTE]
>
> **Changed in `v1.40`**

A collection definition that sets none of `vectorizer`, `vectorIndexType`, `vectorIndexConfig` or `vectorConfig` creates a collection without a vector. Before `v1.40`, the server defaults filled in the top-level parameters, so such a definition produced a single vector collection.

You can [add a named vector](https://docs.weaviate.io/weaviate/manage-collections/vector-config#add-new-named-vectors) later. You cannot add the top-level parameters later. An update that sets them is rejected with a `422` error:

```text
a class-level vectorizer or vector index cannot be added through an update, add a named vector instead
```

---

### Module configuration

The `moduleConfig` parameter allows you to specify if the vectorizers will include or exclude the collection name in vector calculations (default `true`). It is also used to specify reranker and generative [model providers](https://docs.weaviate.io/weaviate/model-providers) at a collection level.

**Example module configuration - JSON object**

An example of a complete `moduleConfig` object:

```json
  "moduleConfig": {
    "text2vec-contextionary": {
      "vectorizeClassName": true  // Include the collection name in vector calculation (default true)
    }
  },
```

---

### Vector index

Vector indexing organizes vector data to make similarity searches fast and efficient. Instead of comparing a query to every vector, an index builds a structure that rapidly narrows the search to the most relevant candidates.

More details about the `vectorIndexType` and `vectorIndexConfig` parameters can be found in [Reference: Vector index](https://docs.weaviate.io/weaviate/config-refs/indexing/vector-index).

---

### Replication

> [!WARNING]
>
> **Replication factor change**
>
> The replication factor of a collection cannot be updated by updating the collection's definition.
>
> From `v1.32` by using [replica movement](https://docs.weaviate.io/deploy/configuration/replica-movement), the [replication factor](https://docs.weaviate.io/weaviate/config-refs/collections#replication) of a shard can be changed.

[Replication](https://docs.weaviate.io/deploy/configuration/replication) configurations can be set using the definition, through the `replicationConfig` parameter.

| Parameter | Type | Description | Default | Mutable |
| - | - | - | - | - |
| `factor` | Integer | The number of copies (replicas) to maintain for each shard. A factor of `3` means one primary and two replicas. | `1` | No |
| `deletionStrategy` | String | Strategy for handling deletions in replication. Can be `NoAutomatedResolution`, `DeleteOnConflict` or `TimeBasedResolution`. | `"TimeBasedResolution"` | Yes |
| `asyncConfig` | Object | Configuration for async replication tuning. See [`asyncConfig` parameters](https://docs.weaviate.io/weaviate/config-refs/collections#async-config) below. Added in `v1.36` | See below | Yes |

> [!NOTE]
>
> **Async replication is on by default (`v1.38`)**
>
> The `asyncEnabled` flag has been removed. As of Weaviate `v1.38`, async replication runs automatically for any collection with a `factor` greater than `1`. To turn it off, set the [`ASYNC_REPLICATION_DISABLED`](https://docs.weaviate.io/deploy/configuration/env-vars#async-replication) environment variable to `true`.

**Example replication configuration - JSON object**

An example of a complete `replicationConfig` object:

```json
{
  "class": "Article",
  "vectorizer": "text2vec-openai",
  "replicationConfig": {
    "factor": 3,
    "deletionStrategy": "TimeBasedResolution",
    "asyncConfig": {
      "hashtreeHeight": 16,
      "frequency": 30000
    }
  }
}
```

#### `asyncConfig` parameters

> [!NOTE]
>
> **Added in `v1.36`**
>
> The corresponding cluster-wide [environment variables](https://docs.weaviate.io/deploy/configuration/async-rep) override these per-collection parameters.

> [!NOTE]
>
> **Multi-tenant vs single-tenant defaults**
>
> Some `asyncConfig` parameters have different defaults depending on whether the collection uses multi-tenancy. These differences are noted in the table below.

| Parameter | Type | Description | Default (single-tenant) | Default (multi-tenant) |
| - | - | - | - | - |
| `hashtreeHeight` | Integer | Height of the hash tree used for data comparison between nodes. Min: `0`, Max: `20` | `16` | `10` |
| `frequency` | Integer | Frequency of periodic data comparison between nodes, in milliseconds. | `30000` | `30000` |
| `frequencyWhilePropagating` | Integer | Frequency of data comparison while propagation is active, in milliseconds. | `5000` | `5000` |
| `loggingFrequency` | Integer | How often the async replication process logs its activity, in seconds. | `60` | `60` |
| `diffBatchSize` | Integer | Number of object keys fetched per request during comparison. Min: `1`, Max: `10000` | `1000` | `1000` |
| `diffPerNodeTimeout` | Integer | Timeout for a comparison response from a remote node, in seconds. | `10` | `10` |
| `prePropagationTimeout` | Integer | Overall timeout for the pre-propagation phase, in seconds. | `300` | `300` |
| `propagationTimeout` | Integer | Timeout for a propagation request to a remote node, in seconds. | `60` | `60` |
| `propagationLimit` | Integer | Maximum number of objects propagated in a single iteration. Min: `1`, Max: `100000` | `1000` | `1000` |
| `propagationDelay` | Integer | Delay before considering an object for propagation, in milliseconds. | `30000` | `30000` |
| `propagationConcurrency` | Integer | Number of concurrent workers for propagation. Min: `1`, Max: `20` | `1` | `1` |
| `propagationBatchSize` | Integer | Maximum number of objects per propagation batch. Min: `1`, Max: `1000` | `100` | `100` |

> [!NOTE]
>
> **Values changed in `v1.34.19`, `v1.35.14`, `v1.36.4` and `v1.37.0`**
>
> Three of the defaults above were changed in the patch releases `v1.34.19`, `v1.35.14` and `v1.36.4`, and apply to every release from `v1.37.0` onwards. On earlier releases of each of those lines, `frequencyWhilePropagating` defaults to `3000`, `propagationLimit` defaults to `10000`, and `propagationConcurrency` defaults to `5`.
>
> The maximum value for `propagationLimit` was lowered from `1000000` to `100000` one patch later, in `v1.34.20`, `v1.35.15` and `v1.36.6`.

#### Code example - How to configure replication

This code example shows how to configure the replication parameters through a client library:

**Python**

```py
from weaviate.classes.config import Configure, ReplicationDeletionStrategy

client.collections.create(
    "Article",
    replication_config=Configure.replication(
        factor=3,
        deletion_strategy=ReplicationDeletionStrategy.TIME_BASED_RESOLUTION,
        async_enabled=True,
        async_config=Configure.Replication.async_config(
            hashtree_height=16,
            frequency=30,
        ),
    ),
)
```

**JavaScript/TypeScript**

```ts
import { configure } from '@weaviate/node';

await replicationClient.collections.create({
  name: 'Article',
  replication: configure.replication({
    factor: 3,
    deletionStrategy: 'TimeBasedResolution',
    asyncConfig: {
      hashtreeHeight: 16,
      frequency: 30,
    },
  }),
})
```

**Go (v6)**

```go
_, err := client.Collections.Create(ctx, collections.Collection{
  Name: "Article",
  Replication: &collections.ReplicationConfig{
    Factor:           3,
    DeletionStrategy: collections.TimeBasedResolution,
    AsyncReplication: &collections.AsyncReplicationConfig{
      HashTreeHeight:       16,
      ReplicationFrequency: 30 * time.Millisecond,
    },
  },
})
if err != nil {
  // handle error
  panic(err)
}
```

**Java**

```java
threeNodeClient.collections.create("Article",
    col -> col.replication(Replication.of(rep -> rep.replicationFactor(3)
        .deletionStrategy(DeletionStrategy.TIME_BASED_RESOLUTION)
        .asyncReplication(AsyncReplicationConfig.of(async -> async
            .propagationConcurrency(5)
            .hashTreeHeight(16)
            .frequencyMillis(30))))));
```

**C#**

```csharp
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = "Article",
        ReplicationConfig = new ReplicationConfig
        {
            Factor = 1,
            DeletionStrategy = DeletionStrategy.TimeBasedResolution,
            AsyncEnabled = true,
            AsyncConfig = new ReplicationAsyncConfig
            {
                HashtreeHeight = 16,
                Frequency = 30,
            },
        },
    }
);
```

> [!TIP]
>
> **Further resources**
>
> For more code example and configuration guides visit the [How-to: Manage collections](https://docs.weaviate.io/weaviate/manage-collections) section.

---

### Sharding

Sharding is configured via the `shardingConfig` object in the collection definition. These parameters are immutable and cannot be changed after the collection is created.

| Parameter | Type | Description | Default | Mutable |
| - | - | - | - | - |
| `desiredCount` | Integer | The desired number of physical shards for the collection. If this value is larger than the number of cluster nodes, some nodes will host multiple shards. | Number of nodes | No |
| `virtualPerPhysical` | Integer | The number of virtual shards per physical shard. Virtual shards aid in reducing data movement during rebalancing. | `128` | No |
| `strategy` | String | The strategy for determining which shard an object belongs to. Only `"hash"` is currently supported. The hash is based on the `key` property. | `"hash"` | No |
| `key` | String | The property used for hashing to determine the target shard. Currently, only the object's internal UUID (`_id`) can be used. | `"_id"` | No |
| `function` | String | The hashing function used on the `key`. Only `"murmur3"` is supported, which creates a 64-bit hash, making collisions highly unlikely. | `"murmur3"` | No |
| `actualCount` | Integer | **(Read-only)** The actual number of physical shards created. This typically matches `desiredCount` unless an issue occurred during creation. | `1` | No |
| `desiredVirtualCount` | Integer | **(Read-only)** A calculated value representing `desiredCount * virtualPerPhysical`. | `128` | No |
| `actualVirtualCount` | Integer | **(Read-only)** The actual number of virtual shards that were created. | `128` | No |

**Example sharding configuration - JSON object**

An example of a complete `shardingConfig` object:

```json
  "shardingConfig": {
    "virtualPerPhysical": 128,
    "desiredCount": 1,           // defaults to the amount of Weaviate nodes in the cluster
    "actualCount": 1,
    "desiredVirtualCount": 128,
    "actualVirtualCount": 128,
    "key": "_id",
    "strategy": "hash",
    "function": "murmur3"
  }
```

#### Code example - How to configure sharding

This code example shows how to configure the sharding parameters through a client library:

**Python**

```py
from weaviate.classes.config import Configure

client.collections.create(
    "Article",
    sharding_config=Configure.sharding(
        virtual_per_physical=128,
        desired_count=1,
        desired_virtual_count=128,
    ),
)
```

**JavaScript/TypeScript**

```ts
import { configure } from '@weaviate/node';

await client.collections.create({
  name: 'Article',
  sharding: configure.sharding({
    virtualPerPhysical: 128,
    desiredCount: 1,
    desiredVirtualCount: 128,
  })
})
```

**Go (v6)**

```go
_, err := client.Collections.Create(ctx, collections.Collection{
  Name: "Article",
  Sharding: &collections.ShardingConfig{
    VirtualPerPhysical:  128,
    DesiredCount:        1,
    DesiredVirtualCount: 128,
  },
})
if err != nil {
  // handle error
  panic(err)
}
```

**Java**

```java
client.collections.create("Article",
    col -> col.sharding(Sharding.of(s -> s.virtualPerPhysical(128)
        .desiredCount(1)
        .desiredVirtualCount(128))));
```

**C#**

```csharp
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = "Article",
        ShardingConfig = new ShardingConfig
        {
            VirtualPerPhysical = 128,
            DesiredCount = 1,
            DesiredVirtualCount = 128,
        },
    }
);
```

> [!TIP]
>
> **Further resources**
>
> For more code example and configuration guides visit the [How-to: Manage collections](https://docs.weaviate.io/weaviate/manage-collections) section.

---

### Multi-tenancy

Multi-tenancy allows you to isolate data within a single collection, where objects are associated with specific tenants. This is a useful feature for building SaaS applications or any system requiring strict data partitioning.

> [!NOTE]
>
> **Why use multi-tenancy?**
>
> It provides data isolation at a lower overhead than creating a separate collection for each tenant, making it more scalable when you have a large number of tenants.

To enable multi-tenancy, set the `enabled` key to `true` in the `multiTenancyConfig` object. This parameter is immutable and must be set at creation time.

| Parameter | Type | Description | Default | Mutable |
| - | - | - | - | - |
| `enabled` | Boolean | If `true`, enables multi-tenancy for the collection. | `false` | No |
| `autoTenantCreation` | Boolean | If `true`, a new tenant is created if you try to insert an object into a non-existent tenant. | `false` | Yes |
| `autoTenantActivation` | Boolean | If `true`, automatically activate `INACTIVE` or `OFFLOADED` tenants if a search, read, update, or delete operation is performed on them. | `false` | Yes |

#### Code example - How to configure multi-tenancy

This code example enables multi-tenancy on a new collection. `autoTenantCreation` and `autoTenantActivation` are set the same way, and can also be changed later. For worked examples of both, see [How-to: Multi-tenancy operations](https://docs.weaviate.io/weaviate/manage-collections/multi-tenancy#automatically-add-new-tenants).

**Python**

```py
from weaviate.classes.config import Configure

multi_collection = client.collections.create(
    name="MultiTenancyCollection",
    # Enable multi-tenancy on the new collection
    multi_tenancy_config=Configure.multi_tenancy(enabled=True)
)
```

**JavaScript/TypeScript**

```ts
const result = await client.collections.create({
  name: collectionName,
  multiTenancy: weaviate.configure.multiTenancy({ enabled: true })
})
```

**Go (v6)**

```go
_, err := client.Collections.Create(ctx, collections.Collection{
  Name: "MultiTenancyCollection",
  MultiTenancy: &collections.MultiTenancyConfig{
    Enabled: true,
  },
})
if err != nil {
  // handle error
  panic(err)
}
```

**Java**

```java
client.collections.create("MultiTenancyCollection", col -> col
    .multiTenancy(mt -> mt.enabled(true).autoTenantCreation(true)));
```

**C#**

```csharp
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = "MultiTenancyCollection",
        MultiTenancyConfig = new MultiTenancyConfig { Enabled = true },
    }
);
```

> [!TIP]
>
> **Further resources**
>
> For more code example and configuration guides visit the [How-to: Manage collections](https://docs.weaviate.io/weaviate/manage-collections) section.

### Object TTL

`objectTtlConfig` sets an expiration time for the collection's objects. The expiry is measured from the object's creation time, its last update time, or a `date` property that you name.

| Parameter | Type | Description | Default | Mutable |
| - | - | - | - | - |
| `enabled` | Boolean | If `true`, objects in this collection expire. | `false` | Yes |
| `deleteOn` | String | The base time for the expiry: `_creationTimeUnix`, `_lastUpdateTimeUnix`, or the name of a `date` property. | - | Yes |
| `defaultTtl` | Integer | Seconds added to the `deleteOn` value to get the expiration time. Must be positive for `_creationTimeUnix` and `_lastUpdateTimeUnix`. | `0` | Yes |
| `filterExpiredObjects` | Boolean | If `true`, expired objects that the background process has not deleted yet are excluded from query results. | `false` | Yes |

Expired objects are only deleted if the [`OBJECTS_TTL_DELETE_SCHEDULE`](https://docs.weaviate.io/deploy/configuration/env-vars#OBJECTS_TTL_DELETE_SCHEDULE) environment variable is set on the instance. It is empty by default, which disables the deletion process.

For code examples, see [How-to: Time to live (TTL)](https://docs.weaviate.io/weaviate/manage-collections/time-to-live).

## Mutability

Some, but not all, parameters are mutable after you create your collection. To modify immutable parameters, export your data, create a new collection, and import your data into it.

| Parameter | Mutable after creation? | How | If immutable |
| - | - | - | - |
| `class` (the collection name) | No | - | Create a new collection and [migrate the data](https://docs.weaviate.io/weaviate/manage-collections/migrate). To serve an existing collection under another name, use a [collection alias](https://docs.weaviate.io/weaviate/config-refs/collections#collection-aliases). |
| `description` | Yes | [Update the collection definition](https://docs.weaviate.io/weaviate/manage-collections/collection-operations#update-a-collection-definition) | - |
| `properties` | New properties only | [Add a property](https://docs.weaviate.io/weaviate/manage-collections/collection-operations#add-a-property) | To change an existing property, create a new collection and [migrate the data](https://docs.weaviate.io/weaviate/manage-collections/migrate). |
| `invertedIndexConfig` | Yes | [Update the collection definition](https://docs.weaviate.io/weaviate/manage-collections/collection-operations#update-a-collection-definition) | Changing [`tokenizerUserDict`](https://docs.weaviate.io/weaviate/config-refs/indexing/inverted-index#tokenizeruserdict) is allowed, but existing objects keep the old tokenization until they are re-imported. |
| `objectTtlConfig` | Yes | [Update the collection definition](https://docs.weaviate.io/weaviate/manage-collections/collection-operations#update-a-collection-definition) | - |
| `vectorConfig` (named vectors) | New named vectors, and dropping a named vector from `v1.40` | [Add new named vectors](https://docs.weaviate.io/weaviate/manage-collections/vector-config#add-new-named-vectors), [Drop a named vector](https://docs.weaviate.io/weaviate/manage-collections/vector-config#drop-a-named-vector) | To change an existing named vector, create a new collection and [migrate the data](https://docs.weaviate.io/weaviate/manage-collections/migrate). |
| `vectorizer` | No | - | Create a new collection and [migrate the data](https://docs.weaviate.io/weaviate/manage-collections/migrate). |
| `vectorIndexType` | No | - | Create a new collection and [migrate the data](https://docs.weaviate.io/weaviate/manage-collections/migrate). |
| `vectorIndexConfig` | Some settings. See the mutability column in the [vector index reference](https://docs.weaviate.io/weaviate/config-refs/indexing/vector-index). | [Update the collection definition](https://docs.weaviate.io/weaviate/manage-collections/collection-operations#update-a-collection-definition) | For an immutable setting such as `distance` or `efConstruction`, create a new collection and [migrate the data](https://docs.weaviate.io/weaviate/manage-collections/migrate). |
| `moduleConfig` | Generative and reranker modules only, from `v1.26.8` and `v1.27.1` | [Update the collection definition](https://docs.weaviate.io/weaviate/manage-collections/collection-operations#update-a-collection-definition) | For other module settings, create a new collection and [migrate the data](https://docs.weaviate.io/weaviate/manage-collections/migrate). |
| `replicationConfig.factor` | No, from `v1.25` | - | See the [replication section](https://docs.weaviate.io/weaviate/config-refs/collections#replication). |
| `replicationConfig.deletionStrategy` | Yes, from `v1.27.0` | [Update the collection definition](https://docs.weaviate.io/weaviate/manage-collections/collection-operations#update-a-collection-definition) | - |
| `multiTenancyConfig.enabled` | No | - | Create a new collection with multi-tenancy enabled and [migrate the data](https://docs.weaviate.io/weaviate/manage-collections/migrate). |
| `multiTenancyConfig.autoTenantCreation`, `multiTenancyConfig.autoTenantActivation` | Yes | [Update the collection definition](https://docs.weaviate.io/weaviate/manage-collections/collection-operations#update-a-collection-definition) | - |
| `shardingConfig` | No | - | Create a new collection and [migrate the data](https://docs.weaviate.io/weaviate/manage-collections/migrate). |

**Mutable parameters**

> [!WARNING]
>
> **Replication factor change**
>
> The replication factor of a collection cannot be updated by updating the collection's definition.
>
> From `v1.32` by using [replica movement](https://docs.weaviate.io/deploy/configuration/replica-movement), the [replication factor](https://docs.weaviate.io/weaviate/config-refs/collections#replication) of a shard can be changed.

- `description`

- `properties description`

- `invertedIndexConfig`

  - `bm25`

    - `b`
    - `k1`

  - `cleanupIntervalSeconds`

  - `stopwords`

    - `additions`
    - `preset`
    - `removals`

- `moduleConfig` (generative & reranker modules only, from `1.26.8` and `v1.27.1`)

- `multiTenancyConfig`

  - `autoTenantCreation` (introduced in `v1.25.0`)
  - `autoTenantActivation` (introduced in `v1.25.2`)

- `replicationConfig`

  - `factor` (not mutable in `v1.25` or higher)
  - `deletionStrategy` (introduced in `v1.27.0`)

- `vectorIndexConfig`

  - `ef`

  - `dynamicEfFactor`

  - `dynamicEfMin`

  - `dynamicEfMax`

  - `filterStrategy` (introduced in `v1.27.0`, applicable for HNSW)

  - `flatSearchCutoff`

  - `bq`
    - `rescoreLimit`

  - `pq`

    - `centroids`

    - `enabled`

    - `segments`

    - `trainingLimit`

    - `encoder`

      - `type`
      - `distribution`

  - `rq`
    - `rescoreLimit`

  - `sq`

    - `enabled`
    - `rescoreLimit`
    - `trainingLimit`

  - `vectorCacheMaxObjects`

After you create a collection, you can [add new properties](https://docs.weaviate.io/weaviate/manage-collections/collection-operations#add-a-property). You cannot modify existing properties after you create the collection. You can also [add new named vectors](https://docs.weaviate.io/weaviate/concepts/data#adding-a-named-vector-after-collection-creation).

## Auto-schema

> [!NOTE]
>
> **Changed in `v1.39.1`**

The "Auto-schema" feature generates a collection definition automatically by inferring parameters from data being added. It is enabled by default, and can be disabled (e.g. in `docker-compose.yml`) by setting the environment variable [`AUTOSCHEMA_ENABLED`](https://docs.weaviate.io/deploy/configuration/env-vars#AUTOSCHEMA_ENABLED) to `'false'`.

It will:

- Create a collection if an object is added to a non-existent collection.
- Create a single [named vector](https://docs.weaviate.io/weaviate/config-refs/collections#named-vectors) called `default` for that collection, with the vectorizer set to `none` and the index type taken from [`DEFAULT_VECTOR_INDEX`](https://docs.weaviate.io/deploy/configuration/env-vars#DEFAULT_VECTOR_INDEX), or `hnsw` if that variable is unset. Before `v1.39.1`, it created a [single vector collection](https://docs.weaviate.io/weaviate/config-refs/collections#single-vector-collections) instead.
- Add any missing property from an object being added.
- Infer array data types, such as `int[]`, `text[]`, `number[]`, `boolean[]`, `date[]` and `object[]`.
- Infer nested properties for `object` and `object[]` data types.
- Throw an error if an object being added contains a property that conflicts with an existing schema type. (e.g. trying to import text into a field that exists in the schema as `int`).

Supply the vectors yourself for auto-created collections, or define the collection before you import.

> [!TIP]
>
> **Define the collection manually for production use**
>
> Generally speaking, we recommend that you disable auto-schema for production use.
>
> - A manual collection definition will provide more precise control.
> - There is a performance penalty associated with inferring the data structure at import time. This may be a costly operation in some cases, such as complex nested properties.

#### Auto-schema data types

Additional configurations are available to help the auto-schema infer properties to suit your needs.

- `AUTOSCHEMA_DEFAULT_NUMBER=number` - create `number` columns for any numerical values (as opposed to `int`, etc).
- `AUTOSCHEMA_DEFAULT_DATE=date` - create `date` columns for any date-like values.

The following are not allowed:

- Any map type is forbidden, unless it clearly matches one of the two supported types `phoneNumber` or `geoCoordinates`.
- Any array type is forbidden, unless it is clearly a reference-type. In this case, Weaviate needs to resolve the beacon and see what collection the resolved beacon is from, since it needs the collection name to be able to alter the schema.

## Collections count limit

> [!NOTE]
>
> **Added in `v1.30`**

Each collection adds overhead in terms of indexing, definition management, and storage. It is possible to **limit the number of collections per instance**. This helps maintain optimal performance and resource utilization.

- **Default limit**: `-1` (no limit).
- **Modify the limit**: Use the [`MAXIMUM_ALLOWED_COLLECTIONS_COUNT`](https://docs.weaviate.io/deploy/configuration/env-vars#MAXIMUM_ALLOWED_COLLECTIONS_COUNT) environment variable to adjust the collection count limit.

> [!NOTE]
>
> If your instance already exceeds the limit, Weaviate will not allow the creation of any new collections. Existing collections will not be deleted.

> [!TIP]
>
> **Instead of raising the collections count limit, consider rethinking your architecture**. For more details, see [Starter Guides: Scaling limits with collections](https://docs.weaviate.io/weaviate/starter-guides/managing-collections/collections-scaling-limits).

## Collection aliases

> [!NOTE]
>
> **Added in `v1.32`**

Collection aliases are alternative names for Weaviate collections that allow you to reference a collection by an alternative name.

Alias names must be unique (can't match existing collections or other aliases) and multiple aliases can point to the same collection. You can set up collection aliases [programmatically through client libraries](https://docs.weaviate.io/weaviate/manage-collections/collection-aliases) or by using the [REST endpoints](https://docs.weaviate.io/weaviate/api/rest#tag/aliases).

In order to manage collection aliases, you need to posses the right [`Collection aliases`](https://docs.weaviate.io/weaviate/configuration/rbac#available-permissions) permissions. To manage the underlying collection the alias references, you also need the [`Collections`](https://docs.weaviate.io/weaviate/configuration/rbac#available-permissions) permissions for that specific collection.

**Collection aliases cannot be used to update collection definitions**, including:

- Updating and adding properties
- Updating vector and inverted indexes
- Configuring sharding and multi-tenancy
- Modifying vectorizer, generative and reranker configurations

> [!NOTE]
>
> **Collection alias usage**
>
> Weaviate automatically routes alias requests to the target collection for **object-related operations**. You can use aliases wherever collection names are required for:
>
> - **[Managing objects](https://docs.weaviate.io/weaviate/manage-objects)**: [Create](https://docs.weaviate.io/weaviate/manage-objects/create), [batch import](https://docs.weaviate.io/weaviate/manage-objects/import), [read](https://docs.weaviate.io/weaviate/manage-objects/read), [update](https://docs.weaviate.io/weaviate/manage-objects/update) and [delete](https://docs.weaviate.io/weaviate/manage-objects/delete) objects through collection aliases.
> - **[Querying objects](https://docs.weaviate.io/weaviate/search)**: [Fetch](https://docs.weaviate.io/weaviate/search/basics) objects and perform searches ([vector](https://docs.weaviate.io/weaviate/search/similarity), [keyword](https://docs.weaviate.io/weaviate/search/bm25), [hybrid](https://docs.weaviate.io/weaviate/search/hybrid), [image](https://docs.weaviate.io/weaviate/search/image), [generative/RAG](https://docs.weaviate.io/weaviate/search/generative)) and [aggregations](https://docs.weaviate.io/weaviate/search/aggregate) through aliases.

## Further resources

- [Starter guides: Collection definition](https://docs.weaviate.io/weaviate/starter-guides/managing-collections)

- [How to: Manage collections](https://docs.weaviate.io/weaviate/manage-collections)

- [Concepts: Data structure](https://docs.weaviate.io/weaviate/concepts/data)

- [REST API: Collection definition (schema)](https://docs.weaviate.io/weaviate/api/rest#tag/schema)
