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.

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

* New properties can be added; existing properties cannot be modified

** New named vectors can be added; some vector index settings are mutable

{
  "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)
}

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

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,
    ),
)

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]*$/.

A description of the collection. This is for your reference and can also provide additional information to the Query Agent.

{
  "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.
}

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

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 objectclient.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),    ],)

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

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

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.

You can customize how text data is tokenized and indexed in the inverted index. Tokenization influences the results returned by the bm25 and hybrid operators, and where filters.

Tokenization is a property-level configuration for text properties. See how to set the tokenization option using a client library

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

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

Behavior examples:

When to use:

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

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

Behavior examples:

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.

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

Behavior examples:

When to use:

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

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

Behavior examples:

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.

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.

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

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.

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.

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.

* See vector index mutable parameters ** New named vectors can be added after collection creation

If you don't explicitly define a named vector 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 section.

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

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),    ],)

import { vectors, dataType } from 'weaviate-client';

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(),
    },
  },
}

Collections can have multiple 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 or hybrid search queries.

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

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),    ],)

import { vectors, dataType } from 'weaviate-client';

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",
    },
  },
}

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 at a collection level.

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

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.

Replication configurations can be set using the definition, through the replicationConfig parameter.

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

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

from weaviate.classes.config import Configure, ReplicationDeletionStrategyclient.collections.create(    "Article",    replication_config=Configure.replication(        factor=3,        deletion_strategy=ReplicationDeletionStrategy.TIME_BASED_RESOLUTION,    ),)

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

  "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"
  }

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

from weaviate.classes.config import Configureclient.collections.create(    "Article",    sharding_config=Configure.sharding(        virtual_per_physical=128,        desired_count=1,        desired_virtual_count=128,    ),)

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.

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.

This code example shows how to configure the multi-tenancy parameters through a client library:

from weaviate.classes.config import Configuremulti_collection = client.collections.create(    name="MultiTenancyCollection",    # Enable multi-tenancy on the new collection    multi_tenancy_config=Configure.multi_tenancy(enabled=True))

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.

After you create a collection, you can add new properties. You cannot modify existing properties after you create the collection. You can also add new named vectors.

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 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).

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.

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 environment variable to adjust the collection count limit.

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 or by using the REST endpoints.

In order to manage collection aliases, you need to posses the right Collection aliases permissions. To manage the underlying collection the alias references, you also need the Collections 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

• Starter guides: Collection definition
• How to: Manage collections
• Concepts: Data structure
• REST API: Collection definition (schema)

Have a question or feedback? Here's how to reach us.