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`](#class) | String | The name of the collection. | (Required) | No | | [`description`](#description) | String | A description of the collection. | `""` | Yes | | [`properties`](#properties) | Array | An array of property objects defining the data schema. | `[]` | Partially\* | | [`invertedIndexConfig`](#inverted-index) | Object | Configuration for the inverted index, affecting filtering and keyword search. | See [Inverted Index reference](indexing-inverted-index.md#inverted-index-parameters) | Yes | | [`vectorConfig`](#vector-configuration) | Object | Configure multiple named vectors each with their own `vectorizer`, `vectorIndexType`, and `vectorIndexConfig` fields. | `null` | Partially\*\* | | [`vectorizer`](#vector-configuration) | String | The vectorizer module to use. | Default vectorizer defined by [environment variable](../database-configuration/overview.md#DEFAULT_VECTORIZER_MODULE). See [Model provider](../model-provider-integrations/index.md) for module-specific config defaults | No | | [`vectorIndexType`](#vector-configuration) | String | The type of vector index to use (`hnsw`, `flat`, `dynamic`, `hfresh`). | `hnsw` | No | | [`moduleConfig`](#module-configuration) | Object | Module-specific configuration settings. | See [Module configuration](#module-configuration) | Partially | | [`vectorIndexConfig`](#vector-configuration) | Object | Configuration settings specific to the chosen `vectorIndexType`. | See [Vector index reference](indexing-vector-index.md) | Partially | | [`shardingConfig`](#sharding) | Object | Controls sharding behavior in a multi-node cluster. | See [Sharding section](#sharding) | No | | [`replicationConfig`](#replication) | Object | Controls data replication settings for fault tolerance. | See [Replication section](#replication) | Partially | | [`multiTenancyConfig`](#multi-tenancy) | Object | Configuration to enable multi-tenancy for the collection. | See [Multi-tenancy section](#multi-tenancy) | Partially | \* [New properties can be added](../how-to-manage-collections/collection-operations.md#add-a-property); existing properties cannot be modified \*\* [New named vectors can be added](../how-to-manage-collections/vector-config.md#add-new-named-vectors); some vector index settings are mutable :::accordion{title="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: ::::tabs{sync="languages"} :::tab{title="Python"} ```python 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, ), ) ``` ::: :::: :::callout{intent="tip" title="Further resources"} For more code examples and configuration guides visit the [How-to: Manage collections](../how-to-manage-collections/index.md) 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]*$/`. :::callout{intent="note" title="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](../agents/overview.md). *** ### Properties | Parameter | Type | Description | Default | Mutable | | :--------------------------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------- | :--------- | :------ | | [`name`](#name) | String | The name of the property. | (Required) | No | | [`dataType`](datatypes.md) | 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`](#tokenization) | String | For `text` properties, specifies how the text is split into tokens for inverted indexing. | `word` | No | | [`indexInverted`](#inverted-index) | Boolean | If `true`, inverted index is enabled for this property. | `true` | No | | [`indexFilterable`](#inverted-index) | Boolean | If `true`, builds a roaring bitmap index for this property to allow for efficient filtering. | `true` | No | | [`indexSearchable`](#inverted-index) | Boolean | If `true`, builds a searchable map index for this property, suitable for BM25 or hybrid search. | `true` | No | | [`indexRangeFilters`](#inverted-index) | Boolean | If `true`, builds a roaring bitmap index for numerical range-based filtering. | `false` | No | | [`invertedIndexConfig`](#inverted-index) | Object | Property-level overrides for inverted index settings, such as `bm25` parameters. | `{}` | No | | `moduleConfig` | Object | Module-specific settings, such as skipping vectorization for this property. | `{}` | No | :::accordion{title="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: ::::tabs{sync="languages"} :::tab{title="Python"} ```python {6} from weaviate.classes.config import Property, DataType # 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), Property(name="description", data_type=DataType.TEXT, skip_vectorization=True), Property(name="rating", data_type=DataType.NUMBER), ], ) ``` ::: :::: :::callout{intent="tip" title="Further resources"} For more code example and configuration guides visit the [How-to: Manage collections](../how-to-manage-collections/index.md) 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`](../apis/graphql-search-operators.md#bm25) and [`hybrid`](../apis/graphql-search-operators.md#hybrid) operators, and [`where` filters](../apis/graphql-filters.md). Tokenization is a property-level configuration for `text` properties. [See how to set the tokenization option using a client library](../how-to-manage-collections/vector-config.md#property-level-settings) :::accordion{title="Example property configuration - JSON object"} ```json {9} { "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. ::::accordion{title="gse and trigram tokenization methods"} For Japanese and Chinese text, we recommend use of `gse` 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. The `gse` tokenizer is not loaded by default to save resources. To use it, set the environment variable `ENABLE_TOKENIZER_GSE` to `true` on the Weaviate instance. `gse` tokenization examples: - `"素早い茶色の狐が怠けた犬を飛び越えた"`: `["素早", "素早い", "早い", "茶色", "の", "狐", "が", "怠け", "けた", "犬", "を", "飛び", "飛び越え", "越え", "た", "素早い茶色の狐が怠けた犬を飛び越えた"]` - `"すばやいちゃいろのきつねがなまけたいぬをとびこえた"`: `["すばや", "すばやい", "やい", "いち", "ちゃ", "ちゃい", "ちゃいろ", "いろ", "のき", "きつ", "きつね", "つね", "ねが", "がな", "なま", "なまけ", "まけ", "けた", "けたい", "たい", "いぬ", "を", "とび", "とびこえ", "こえ", "た", "すばやいちゃいろのきつねがなまけたいぬをとびこえた"]` :::callout{intent="note" title="`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. ::: :::: :::accordion{title="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", "星空", "の", "下", "、", "すべて", "が", "平和", "で", "ある"`] - `"素早い茶色の狐が怠けた犬を飛び越えた"`: - `["素早い", "茶色", "の", "狐", "が", "怠け", "た", "犬", "を", "飛び越え", "た"]` - `"すばやいちゃいろのきつねがなまけたいぬをとびこえた"`: - `["すばやい", "ちゃ", "いろ", "の", "きつね", "が", "なまけ", "た", "いぬ", "を", "とびこえ", "た"]` ::: :::accordion{title="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: - `"아버지가방에들어가신다"`: - `["아버지", "가", "방", "에", "들어가", "신다"]` - `"아버지가 방에 들어가신다"`: - `["아버지", "가", "방", "에", "들어가", "신다"]` - `"결정하겠다"`: - `["결정", "하", "겠", "다"]` ::: :::accordion{title="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](../database-configuration/overview.md). ::: ::::accordion{title="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 :::callout{intent="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` 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`, `indexRangeFilters` and `invertedIndexConfig` parameters can be found in [Reference: Inverted index](indexing-inverted-index.md). *** ### 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. :::callout{intent="tip" title="We recommend using `vectorConfig`"} Using the `vectorConfig` parameter allows you to start with one vector per collection and adding [new named vectors](../how-to-manage-collections/vector-config.md#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](../model-provider-integrations/index.md) | Module-specific default | No | | [`vectorIndexType`](indexing-vector-index.md) | String | Vector index type: `hnsw` (default), `flat`, `dynamic`, or `hfresh` | `hnsw` | No | | [`vectorIndexConfig`](indexing-vector-index.md) | Object | Configuration settings for your chosen `vectorIndexType` | Index-specific defaults | Partially\* | | `vectorConfig` | Object | **Alternative to above**: Define multiple named vector spaces | `null` | Partially\*\* | | ↪ `vectorConfig..vectorizer` | Object | Vectorizer config for this named vector (e.g., `{"text2vec-openai": {"properties": ["title"]}}`) | (Required) | No | | [↪ `vectorConfig..vectorIndexType`](indexing-vector-index.md) | String | Index type for this named vector | `hnsw` | No | | [↪ `vectorConfig..vectorIndexConfig`](indexing-vector-index.md) | Object | Index configuration for this named vector | Index-specific defaults | Partially\* | \* See [vector index mutable parameters](indexing-vector-index.md) \*\* [New named vectors can be added](../how-to-manage-collections/vector-config.md#add-new-named-vectors) after collection creation #### Single vector collections If you don't explicitly define a [named vector](#multiple-vector-embeddings-named-vectors) in your collection definition, Weaviate automatically creates what's known as a _single vector_ collection. These vectors are stored internally under the named vector `default` (which is a reserved vector name). To learn which properties of your data are vectorized, refer to the [Configure semantic indexing](indexing-vector-index.md#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: :::code-group{sync="languages"} ```python title="Python" {11-20} 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), ], ) ``` ```typescript title="JavaScript/TypeScript" import { vectors, dataType } from 'weaviate-client'; ``` ```go title="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(), }, }, } ``` ::: :::callout{intent="tip" title="Further resources"} For more code example and configuration guides visit the [How-to: Vectorizer and vector index config](../how-to-manage-collections/vector-config.md) guide. ::: #### Multiple vector embeddings (named vectors) Collections can have multiple [named vectors](collections.md#multiple-vector-embeddings-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](../how-to-query-search/similarity.md#named-vectors) or [hybrid search](../how-to-query-search/hybrid.md#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: :::code-group{sync="languages"} ```python title="Python" {11-30} 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), ], ) ``` ```typescript title="JavaScript/TypeScript" import { vectors, dataType } from 'weaviate-client'; ``` ```go title="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", }, }, } ``` ::: :::callout{intent="tip" title="Further resources"} For more code example and configuration guides visit the [How-to: Vectorizer and vector index config](../how-to-manage-collections/vector-config.md) guide. ::: *** ### 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](../model-provider-integrations/index.md) at a collection level. :::accordion{title="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](indexing-vector-index.md). *** ### Replication :::callout{intent="warning" title="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](../replication-and-scaling/replica-movement.md), the [replication factor](collections.md#replication) of a shard can be changed. ::: [Replication](../replication-and-scaling/replication.md) 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](#asyncconfig-parameters) below. Added in `v1.36` | See below | Yes | :::callout{intent="note" title="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`](../database-configuration/overview.md#async-replication) environment variable to `true`. ::: :::accordion{title="Example replication configuration - JSON object"} An example of a complete `replicationConfig` object: ```json {4-11} { "class": "Article", "vectorizer": "text2vec-openai", "replicationConfig": { "factor": 3, "deletionStrategy": "TimeBasedResolution", "asyncConfig": { "hashtreeHeight": 16, "frequency": 30000 } } } ``` ::: #### `asyncConfig` parameters :::callout{intent="info" title="Added in `v1.36`"} The corresponding cluster-wide [environment variables](../replication-and-scaling/async-rep.md) override these per-collection parameters. ::: :::callout{intent="note" title="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` | :::callout{intent="note" title="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: ::::tabs{sync="languages"} :::tab{title="Python"} ```python {5-8} from weaviate.classes.config import Configure, ReplicationDeletionStrategy client.collections.create( "Article", replication_config=Configure.replication( factor=3, deletion_strategy=ReplicationDeletionStrategy.TIME_BASED_RESOLUTION, ), ) ``` ::: :::: :::callout{intent="tip" title="Further resources"} For more code example and configuration guides visit the [How-to: Manage collections](../how-to-manage-collections/index.md) 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 | :::accordion{title="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: ::::tabs{sync="languages"} :::tab{title="Python"} ```python {5-9} 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, ), ) ``` ::: :::: :::callout{intent="tip" title="Further resources"} For more code example and configuration guides visit the [How-to: Manage collections](../how-to-manage-collections/index.md) 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. :::callout{intent="note" title="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 shows how to configure the multi-tenancy parameters through a client library: ::::tabs{sync="languages"} :::tab{title="Python"} ```python {6} 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) ) ``` ::: :::: :::callout{intent="tip" title="Further resources"} For more code example and configuration guides visit the [How-to: Manage collections](../how-to-manage-collections/index.md) section. ::: ## 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. ::::accordion{title="Mutable parameters"} :::callout{intent="warning" title="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](../replication-and-scaling/replica-movement.md), the [replication factor](collections.md#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` - `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` - `skip` - `vectorCacheMaxObjects` :::: After you create a collection, you can [add new properties](../how-to-manage-collections/collection-operations.md#add-a-property). You cannot modify existing properties after you create the collection. You can also [add new named vectors](../concepts/data.md#adding-a-named-vector-after-collection-creation). ## Auto-schema 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`](../database-configuration/overview.md#AUTOSCHEMA_ENABLED) to `'false'`. It will: - Create a collection if an object is added to a non-existent collection. - 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`). :::callout{intent="tip" title="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 :::callout{intent="info" title="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`](../database-configuration/overview.md#MAXIMUM_ALLOWED_COLLECTIONS_COUNT) environment variable to adjust the collection count limit. :::callout{intent="note"} If your instance already exceeds the limit, Weaviate will not allow the creation of any new collections. Existing collections will not be deleted. ::: :::callout{intent="tip"} **Instead of raising the collections count limit, consider rethinking your architecture**. For more details, see [Starter Guides: Scaling limits with collections](../starter-guides/managing-collections-collections-scaling-limits.md). ::: ## Collection aliases :::callout{intent="info" title="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](../how-to-manage-collections/collection-aliases.md) or by using the [REST endpoints](/weaviate/api/rest#tag/aliases). In order to manage collection aliases, you need to posses the right [`Collection aliases`](../authorization-and-authentication/weaviate-configuration-rbac.md#available-permissions) permissions. To manage the underlying collection the alias references, you also need the [`Collections`](../authorization-and-authentication/weaviate-configuration-rbac.md#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 :::callout{intent="info" title="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](../how-to-manage-objects/index.md)**: [Create](../how-to-manage-objects/create.md), [batch import](../how-to-manage-objects/import.md), [read](../how-to-manage-objects/read.md), [update](../how-to-manage-objects/update.md) and [delete](../how-to-manage-objects/delete.md) objects through collection aliases. - **[Querying objects](../how-to-query-search/index.md)**: [Fetch](../how-to-query-search/basics.md) objects and perform searches ([vector](../how-to-query-search/similarity.md), [keyword](../how-to-query-search/bm25.md), [hybrid](../how-to-query-search/hybrid.md), [image](../how-to-query-search/image.md), [generative/RAG](../how-to-query-search/generative.md)) and [aggregations](../how-to-query-search/aggregate.md) through aliases. ::: ## Further resources - [Starter guides: Collection definition](../starter-guides/managing-collections.md) - [How to: Manage collections](../how-to-manage-collections/index.md) - [Concepts: Data structure](../concepts/data.md) - [REST API: Collection definition (schema)](/weaviate/api/rest#tag/schema) ## Questions and feedback Have a question or feedback? Here's how to reach us. ::::card-grid :::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"} Ask questions and connect with other developers on our **Community forum**. ::: :::card{title="Support" href="/guides/support-overview" icon="life-buoy"} Weaviate Cloud user or customer? Find the right channel on the **Support page**. ::: :::: ## Related pages - [Agents](./agents-index.md) - [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md) - [APIs](./apis-index.md) - [Authorization and authentication](./authorization-and-authentication-index.md) - [Benchmarks](./benchmarks-index.md) - [Best practices](./best-practices-index.md) - [Client libraries](./clients-index.md) - [Client Libraries / SDKs](./client-libraries-index.md) - [Cloud](./cloud-index.md) - [Cloud account management](./cloud-account-management-index.md) # Agent Instructions This portal answers questions programmatically. To receive a synthesized, source-cited answer instead of crawling page by page, append the `?ask=` query parameter to any page URL on this site: /guides/quickstart?ask=how+do+I+authenticate Optional parameters: - `&goal=` steers the answer toward your objective (e.g. `&goal=write+a+python+client`). - `&version=