Manage collections

Every object in Weaviate belongs to exactly one collection. Use the examples on this page to manage your collections.

Terminology

Newer Weaviate documentation discuses "collections." Older Weaviate documentation refers to "classes" instead. Expect to see both terms throughout the documentation.

Create a collection

To create a collection, specify at least the collection name. If you don't specify any properties, auto-schema creates them.

Python (v4)

client.collections.create("Article")

Python (v3)

class_name = "Article"

class_obj = {"class": class_name}

client.schema.create_class(class_obj)  # returns null on success

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article'
})
// The returned value is the full collection definition, showing all defaults
console.log(JSON.stringify(newCollection, null, 2));

JS/TS

const className = 'Article';

const emptyClassDefinition = {
  class: className,
};

// Add the class to the schema
let result = await client.schema
  .classCreator()
  .withClass(emptyClassDefinition)
  .do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Java

String className = "Article";

WeaviateClass emptyClass = WeaviateClass.builder()
  .className(className)
  .build();

// Add the class to the schema
Result<Boolean> result = client.schema().classCreator()
  .withClass(emptyClass)
  .run();

Go

className := "Article"

emptyClass := &models.Class{
  Class: className,
}

// Add the class to the schema
err := client.Schema().ClassCreator().
  WithClass(emptyClass).
  Do(ctx)

Create a collection and define properties

Properties are the data fields in your collection. Each property has a name and a data type.

Additional information

Use properties to configure additional parameters such as data type, index characteristics, or tokenization.

For details, see:

• References: Configuration: Schema
• API References: REST: Schema
• Available data types

Python (v4)

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",
    properties=[
        Property(name="title", data_type=DataType.TEXT),
        Property(name="body", data_type=DataType.TEXT),
    ]
)

Python (v3)

class_obj = {
    "class": "Article",
    "properties": [
        {
            "name": "title",
            "dataType": ["text"],
        },
        {
            "name": "body",
            "dataType": ["text"],
        },
    ],
}

client.schema.create_class(class_obj)  # returns null on success

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article',
  properties: [
    {
      name: 'title',
      dataType: weaviate.configure.dataType.TEXT,
      vectorizePropertyName: true,
      tokenization: 'lowercase' ,
    },
    {
      name: 'body',
      dataType: weaviate.configure.dataType.TEXT,
      tokenization: 'whitespace',
      skipVectorisation: true
    },
  ],
})
// The returned value is the full collection definition, showing all defaults
console.log(JSON.stringify(newCollection, null, 2));

JS/TS

const classWithProps = {
  class: 'Article',
  properties: [
    {
      name: 'title',
      dataType: ['text'],
    },
    {
      name: 'body',
      dataType: ['text'],
    },
  ],
};

// Add the class to the schema
result = await client.schema.classCreator().withClass(classWithProps).do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Disable auto-schema

By default, Weaviate creates missing collections and missing properties. When you configure collections manually, you have more precise control of the collection settings.

To disable auto-schema set AUTOSCHEMA_ENABLED: 'false' in your system configuration file.

Specify a vectorizer

Specify a vectorizer for a collection.

Additional information

Collection level settings override default values and general configuration parameters such as environment variables.

• Available vectorizers
• Vectorizer configuration references

Python (v4)

from weaviate.classes.config import Configure, Property, DataType

client.collections.create(
    "Article",
    vectorizer_config=Configure.Vectorizer.text2vec_openai(),
    properties=[  # properties configuration is optional
        Property(name="title", data_type=DataType.TEXT),
        Property(name="body", data_type=DataType.TEXT),
    ]
)

Python (v3)

class_obj = {
    "class": "Article",
    "properties": [
        {
            "name": "title",
            "dataType": ["text"],
        },
    ],
    "vectorizer": "text2vec-openai"  # this could be any vectorizer
}

client.schema.create_class(class_obj)

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article',
  properties: [
    {
      name: 'title',
      dataType: weaviate.configure.dataType.TEXT,
      vectorizePropertyName: true,
      tokenization: 'lowercase' as const ,
    },
    {
      name: 'body',
      dataType: weaviate.configure.dataType.TEXT,
      tokenization: 'whitespace' as const,
      skipVectorisation: true
    },
  ],
  vectorizer: weaviate.configure.vectorizer.text2VecCohere(),
})
// The returned value is the full collection definition, showing all defaults
console.log(JSON.stringify(newCollection, null, 2));

JS/TS

const classWithVectorizer = {
  class: 'Article',
  properties: [
    {
      name: 'title',
      dataType: ['text'],
    },
  ],
  vectorizer: 'text2vec-openai', // this could be any vectorizer
};

// Add the class to the schema
result = await client.schema.classCreator().withClass(classWithVectorizer).do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Define multiple (named) vectors

Added in v1.24

You can define multiple named vectors per collection. This allows each object to be represented by multiple vectors, such as a text vector and an image vector, or a title vector and a body vector.

Python (v4)

from weaviate.classes.config import Configure, Property, DataType

client.collections.create(
    "ArticleNV",
    properties=[  # Define properties
        Property(name="title", data_type=DataType.TEXT),
        Property(name="body", data_type=DataType.TEXT),
    ],
    vectorizer_config=[
        # Set a named vector
        Configure.NamedVectors.text2vec_cohere(  # Use the "text2vec-cohere" vectorizer
            name="title", source_properties=["title"]       # Set the source property(ies)
        ),
        # Set another named vector
        Configure.NamedVectors.text2vec_openai(  # Use the "text2vec-openai" vectorizer
            name="body", source_properties=["body"]         # Set the source property(ies)
        )
    ],
)

Python (v3)

# Unfortunately, named vectors are not suppored in the v3 API / Python client.
# Please upgrade to the v4 API / Python client to use named vectors.

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'ArticleNV',
  properties: [
    {
      name: 'title',
      dataType: weaviate.configure.dataType.TEXT,
    },
    {
      name: 'body',
      dataType: weaviate.configure.dataType.TEXT,
    },
  ],
  vectorizer: [
    weaviate.configure.namedVectorizer('title', {
      properties: ['title'],
      vectorizerConfig: weaviate.configure.vectorizer.text2VecOpenAI(),
      vectorIndexConfig: weaviate.configure.vectorIndex.hnsw()
    }),
    weaviate.configure.namedVectorizer('body', {
      properties: ['body'],
      vectorizerConfig: weaviate.configure.vectorizer.text2VecCohere(),
      vectorIndexConfig: weaviate.configure.vectorIndex.hnsw(),
 })],
})
// The returned value is the full collection definition, showing all defaults
console.log(JSON.stringify(newCollection, null, 2));

JS/TS

const classWithNamedVectors = {
  class: 'ArticleNV',
  properties: [
    {
      name: 'title',
      dataType: ['text'],
    },
    {
      name: 'body',
      dataType: ['text'],
    },
  ],
  vectorConfig: {
    // Set a named vector
    title: {
      vectorIndexType: 'hnsw', // Set the index type
      vectorizer: {
        'text2vec-cohere': {
          properties: ['title'], // Set the source property(ies)
        },
      },
    },
    // Set another named vector
    body: {
      vectorIndexType: 'hnsw', // Set the index type
      vectorizer: {
        'text2vec-openai': {
          properties: ['body'], // Set the source property(ies)
        },
      },
    },
  },
};

// Add the class to the schema
result = await client.schema
  .classCreator()
  .withClass(classWithNamedVectors)
  .do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Specify vectorizer settings

To configure how a vectorizer works (i.e. what model to use) with a specific collection, set the vectorizer parameters.

Python (v4)

from weaviate.classes.config import Configure

client.collections.create(
    "Article",
    vectorizer_config=Configure.Vectorizer.text2vec_cohere(
        model="embed-multilingual-v2.0",
        vectorize_collection_name=True
    ),
)

Python (v3)

class_obj = {
    "class": "Article",
    "properties": [
        {
            "name": "title",
            "dataType": ["text"],
        },
    ],
    "vectorizer": "text2vec-cohere",  # this could be any vectorizer
    "moduleConfig": {
        "text2vec-cohere": {  # this must match the vectorizer used
            "vectorizeClassName": True,
            "model": "embed-multilingual-v2.0",
        }
    }
}

client.schema.create_class(class_obj)

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article',
  vectorizer: weaviate.configure.vectorizer.text2VecCohere({
    model: 'embed-multilingual-v2.0',
    vectorizeClassName: true,
  }),
})
// The returned value is the full collection definition, showing all defaults
console.log(JSON.stringify(await newCollection.config.get(), null, 2));

JS/TS

const classWithModuleSettings = {
  class: 'Article',
  properties: [
    {
      name: 'title',
      dataType: ['text'],
    },
  ],
  vectorizer: 'text2vec-cohere', // this could be any vectorizer
  moduleConfig: {
    'text2vec-cohere': {
      // this must match the vectorizer used
      vectorizeClassName: true,
      model: 'embed-multilingual-v2.0',
    },
  },
};

// Add the class to the schema
result = await client.schema
  .classCreator()
  .withClass(classWithModuleSettings)
  .do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Set vector index type

The vector index type can be set for each collection between hnsw and flat index types.

Python (v4)

from weaviate.classes.config import Configure, Property, DataType

client.collections.create(
    "Article",
    vectorizer_config=Configure.Vectorizer.text2vec_openai(),
    vector_index_config=Configure.VectorIndex.hnsw(),
    properties=[
        Property(name="title", data_type=DataType.TEXT),
        Property(name="body", data_type=DataType.TEXT),
    ]
)

Python (v3)

class_obj = {
    'class': 'Article',
    'properties': [
        {
            'name': 'title',
            'dataType': ['text'],
        },
    ],
    'vectorizer': 'text2vec-openai',  # this could be any vectorizer
    "vectorIndexType": "flat",
}

client.schema.create_class(class_obj)

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article',
  properties: [
    {
      name: 'title',
      dataType: weaviate.configure.dataType.TEXT,
    },
    {
      name: 'body',
      dataType: weaviate.configure.dataType.TEXT,
    },
  ],
  vectorizer: weaviate.configure.vectorizer.text2VecOpenAI(),
  vectorIndex: weaviate.configure.vectorIndex.hnsw()
})
// The returned value is the full collection definition, showing all defaults
console.log(JSON.stringify(await newCollection.config.get(), null, 2));

JS/TS

const classWithIndexType = {
  class: 'Article',
  properties: [
    {
      name: 'title',
      dataType: ['text'],
    },
  ],
  vectorizer: 'text2vec-openai', // this could be any vectorizer
  vectorIndexType: 'flat', // or `hnsw`
  vectorIndexConfig: {
    bq: {
      enabled: true, // Enable BQ compression. Default: False
      rescoreLimit: 200, // The minimum number of candidates to fetch before rescoring. Default: -1 (No limit)
      cache: true, // Enable use of vector cache. Default: False
    },
    vectorCacheMaxObjects: 100000, // Cache size if `cache` enabled. Default: 1000000000000
  },
};

// Add the class to the schema
result = await client.schema.classCreator().withClass(classWithIndexType).do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Additional information

• Read more about index types & compression in Concepts: Vector index.

Set vector index parameters

Various vector index parameters are configurable at collection creation time, including compression.

Python (v4)

from weaviate.classes.config import Configure, Property, DataType

client.collections.create(
    "Article",
    # Additional configuration not shown
    vector_index_config=Configure.VectorIndex.flat(
        quantizer=Configure.VectorIndex.Quantizer.bq(
            rescore_limit=200,
            cache=True
        ),
        vector_cache_max_objects=100000
    ),
)

Python (v3)

class_obj = {
    'class': 'Article',
    # Additional configuration not shown
    "vectorIndexType": "flat",
    "vectorIndexConfig": {
        "bq": {
            "enabled": True,  # Enable BQ compression. Default: False
            "rescoreLimit": 200,  # The minimum number of candidates to fetch before rescoring. Default: -1 (No limit)
            "cache": True,  # Enable use of vector cache. Default: False
        },
        "vectorCacheMaxObjects": 100000,  # Cache size if `cache` enabled. Default: 1000000000000
    }
}

client.schema.create_class(class_obj)

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article',
  // Additional configuration not shown
  vectorIndex: weaviate.configure.vectorIndex.flat({
    quantizer: weaviate.configure.vectorIndex.quantizer.bq({
      rescoreLimit: 200,
      cache: true
    }),
    vectorCacheMaxObjects: 100000
  })
})
// The returned value is the full collection definition, showing all defaults
console.log(JSON.stringify(await newCollection.config.get(), null, 2));

JS/TS

const classWithIndexParams = {
  class: 'Article',
  // Additional configuration not shown
  vectorIndexType: 'flat', // or `hnsw`
  vectorIndexConfig: {
    bq: {
      enabled: true, // Enable BQ compression. Default: False
      rescoreLimit: 200, // The minimum number of candidates to fetch before rescoring. Default: -1 (No limit)
      cache: true, // Enable use of vector cache. Default: False
    },
    vectorCacheMaxObjects: 100000, // Cache size if `cache` enabled. Default: 1000000000000
  },
};

// Add the class to the schema
result = await client.schema.classCreator().withClass(classWithIndexType).do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Additional information

• Read more about index types & compression in Concepts: Vector index.

Property-level settings

Configure each property to choose whether to vectorize property name, include property in vectorization, and choose tokenization type.

Python (v4)

from weaviate.classes.config import Configure, Property, DataType, Tokenization

client.collections.create(
    "Article",
    vectorizer_config=Configure.Vectorizer.text2vec_huggingface(),

    properties=[
        Property(
            name="title",
            data_type=DataType.TEXT,
            vectorize_property_name=True,  # Use "title" as part of the value to vectorize
            tokenization=Tokenization.LOWERCASE  # Use "lowecase" tokenization
        ),
        Property(
            name="body",
            data_type=DataType.TEXT,
            skip_vectorization=True,  # Don't vectorize this property
            tokenization=Tokenization.WHITESPACE  # Use "whitespace" tokenization
        ),
    ]
)

Python (v3)

class_obj = {
    "class": "Article",
    "vectorizer": "text2vec-huggingface",  # this could be any vectorizer
    "properties": [
        {
            "name": "title",
            "dataType": ["text"],
            "moduleConfig": {
                "text2vec-huggingface": {  # this must match the vectorizer used
                    "vectorizePropertyName": True,
                    "tokenization": "lowercase"
                }
            }
        },
        {
            "name": "body",
            "dataType": ["text"],
            "moduleConfig": {
                "text2vec-huggingface": {  # this must match the vectorizer used
                    "skip": True,  # Don't vectorize body
                    "tokenization": "whitespace"
                }
            }
        },
    ],
}

client.schema.create_class(class_obj)

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article',
  properties: [
    {
      name: 'title',
      dataType: weaviate.configure.dataType.TEXT,
      vectorizePropertyName: true,
      tokenization: 'lowercase'
    },
    {
      name: 'body',
      dataType: weaviate.configure.dataType.TEXT,
      skipVectorisation: true,
      tokenization: 'whitespace'
    },],
  vectorizer: weaviate.configure.vectorizer.text2VecCohere(),
})
// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(newCollection, null, 2));

JS/TS

const classWithPropModuleSettings = {
  class: 'Article',
  vectorizer: 'text2vec-huggingface', // this could be any vectorizer
  properties: [
    {
      name: 'title',
      dataType: ['text'],
      moduleConfig: {
        'text2vec-huggingface': {
          // this must match the vectorizer used
          vectorizePropertyName: true,
          tokenization: 'lowercase', // Use "lowercase" tokenization
        },
      },
    },
    {
      name: 'body',
      dataType: ['text'],
      moduleConfig: {
        'text2vec-huggingface': {
          // this must match the vectorizer used
          skip: true, // Don't vectorize this property
          tokenization: 'whitespace', // Use "whitespace" tokenization
        },
      },
    },
  ],
};

// Add the class to the schema
result = await client.schema
  .classCreator()
  .withClass(classWithPropModuleSettings)
  .do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Specify a distance metric

If you choose to bring your own vectors, you should specify the distance metric.

Python (v4)

from weaviate.classes.config import Configure, VectorDistances

client.collections.create(
    "Article",
    vector_index_config=Configure.VectorIndex.hnsw(
        distance_metric=VectorDistances.COSINE
    ),
)

Python (v3)

class_obj = {
    "class": "Article",
    "vectorIndexConfig": {
        "distance": "cosine",
    },
}

client.schema.create_class(class_obj)

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article',
  vectorIndex: weaviate.configure.vectorIndex.hnsw({
    distanceMetric: 'cosine'
  })
})
// The returned value is the full collection definition, showing all defaults
console.log(JSON.stringify(await newCollection.config.get(), null, 2));

JS/TS

const classWithDistance = {
  class: 'Article',
  vectorIndexConfig: {
    distance: 'cosine',
  },
};

// Add the class to the schema
result = await client.schema.classCreator().withClass(classWithDistance).do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Additional information

For details on the configuration parameters, see the following:

• Distances
• Vector indexes

Set inverted index parameters

Various inverted index parameters are configurable for each collection. Some parameters are set at the collection level, while others are set at the property level.

Python (v4)

from weaviate.classes.config import Configure, Property, DataType

client.collections.create(
    "Article",
    # Additional settings not shown
    properties=[ # properties configuration is optional
        Property(
            name="title",
            data_type=DataType.TEXT,
            index_filterable=True,
            index_searchable=True,
        ),
    ],
    inverted_index_config=Configure.inverted_index(  # Optional
        bm25_b=0.7,
        bm25_k1=1.25,
        index_null_state=True,
        index_property_length=True,
        index_timestamps=True
    )
)

Python (v3)

class_obj = {
    "class": "Article",
    "vectorizer": "text2vec-huggingface",  # this could be any vectorizer
    "properties": [
        {
            "name": "title",
            "dataType": ["text"],
            "moduleConfig": {
                "text2vec-huggingface": {  # this must match the vectorizer used
                    "indexFilterable": True,
                    "indexSearchable": True,
                }
            }
        },
    ],
    "invertedIndexConfig": {
        "bm25": {
            "b": 0.7,
            "k1": 1.25
        },
        "indexTimestamps": True,
        "indexNullState": True,
        "indexPropertyLength": True
    }
}

client.schema.create_class(class_obj)

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article',
  properties: [
    {
      name: 'body',
      dataType: weaviate.configure.dataType.TEXT,
      indexFilterable: true,
      indexSearchable: true,
    },
  ],
  invertedIndex: {
    bm25: {
      b: 0.7,
      k1: 1.25
    },
    indexNullState: true,
    indexPropertyLength: true,
    indexTimestamps: true
  }
})

console.log(JSON.stringify(newCollection, null, 2));

JS/TS

const classWithInvIndexSettings = {
  class: 'Article',
  vectorizer: 'text2vec-huggingface', // this could be any vectorizer
  properties: [
    {
      name: 'title',
      dataType: ['text'],
      moduleConfig: {
        'text2vec-huggingface': {
          indexFilterable: true,
          indexSearchable: true,
        },
      },
    },
  ],
  invertedIndexConfig: {
    bm25: {
        b: 0.7,
        k1: 1.25
    },
    indexTimestamps: true,
    indexNullState: true,
    indexPropertyLength: true
  }
};

// Add the class to the schema
result = await client.schema
  .classCreator()
  .withClass(classWithPropModuleSettings)
  .do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Specify a generative module

Specify a generative module for a collection (for RAG).

Additional information

• Available generative modules

Python (v4)

from weaviate.classes.config import Configure, Property, DataType

client.collections.create(
    "Article",
    vectorizer_config=Configure.Vectorizer.text2vec_openai(),
    generative_config=Configure.Generative.openai(),
    properties=[ # properties configuration is optional
        Property(name="title", data_type=DataType.TEXT),
        Property(name="body", data_type=DataType.TEXT),
    ]
)

Python (v3)

class_obj = {
    "class": "Article",
    "properties": [
        {
            "name": "title",
            "dataType": ["text"],
        },
    ],
    "vectorizer": "text2vec-openai",  # set your vectorizer module
    "moduleConfig": {
        "generative-openai": {}  # set your generative module
    }
}

client.schema.create_class(class_obj)

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article',
  properties: [
    {
      name: 'title',
      dataType: weaviate.configure.dataType.TEXT,
    },
  ],
  vectorizer: weaviate.configure.vectorizer.text2VecOpenAI(),
})
// The returned value is the full collection definition, showing all defaults
console.log(JSON.stringify(await newCollection.config.get(), null, 2));

JS/TS

const classWithGenerative = {
  class: 'Article',
  properties: [
    {
      name: 'title',
      dataType: ['text'],
    },
  ],
  vectorizer: 'text2vec-openai', // this could be any vectorizer
  moduleConfig: {
    'generative-openai': {}, // set your generative module
  },
};

// Add the class to the schema
result = await client.schema.classCreator().withClass(classWithGenerative).do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Replication settings

Configure replication per collection.

Python (v4)

from weaviate.classes.config import Configure

client.collections.create(
    "Article",
    replication_config=Configure.replication(
        factor=3
    )
)

Python (v3)

class_obj = {
    "class": "Article",
    "replicationConfig": {
        "factor": 3,
    },
}

client.schema.create_class(class_obj)

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article',
  replication: weaviate.configure.replication({
    factor: 3
  }),
})
// The returned value is the full collection definition, showing all defaults
console.log(JSON.stringify(await newCollection.config.get(), null, 2));

JS/TS

const classWithReplication = {
  class: 'Article',
  replicationConfig: {
    factor: 3,
  },
};

// Add the class to the schema
result = await client.schema
  .classCreator()
  .withClass(classWithReplication)
  .do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Additional information

To use replication factors greater than one, use a multi-node deployment.

For details on the configuration parameters, see the following:

• Replication

Sharding settings

Configure sharding per collection.

Python (v4)

from weaviate.classes.config import Configure

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

Python (v3)

class_obj = {
    "class": "Article",
    "shardingConfig": {
        "virtualPerPhysical": 128,
        "desiredCount": 1,
        "actual_actualCountcount": 1,
        "desiredVirtualCount": 128,
        "actualVirtualCount": 128,
    },
}

client.schema.create_class(class_obj)

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article',
  sharding: weaviate.configure.sharding({
    virtualPerPhysical: 128,
    desiredCount: 1,
    actualCount: 1,
    desiredVirtualCount: 128,
    actualVirtualCount: 128
  })
})
// The returned value is the full collection definition, showing all defaults
console.log(JSON.stringify(await newCollection.config.get(), null, 2));

JS/TS

const classWithSharding = {
  class: 'Article',
  vectorIndexConfig: {
    distance: 'cosine',
  },
  shardingConfig: {
    virtualPerPhysical: 128,
    desiredCount: 1,
    actualCount: 1,
    desiredVirtualCount: 128,
    actualVirtualCount: 128,
  },
};

// Add the class to the schema
result = await client.schema.classCreator().withClass(classWithSharding).do();

// The returned value is the full class definition, showing all defaults
console.log(JSON.stringify(result, null, 2));

Additional information

For details on the configuration parameters, see the following:

• Sharding

Multi-tenancy

Added in v1.20

Create a collection with multi-tenancy enabled.

Python (v4)

from weaviate.classes.config import Configure

client.collections.create(
    "Article",
    multi_tenancy_config=Configure.multi_tenancy(True)
)

Python (v3)

class_obj = {
    "class": "Article",
    "multiTenancyConfig": {"enabled": True}
}

client.schema.create_class(class_obj)  # returns null on success

JS/TS (Beta)

const newCollection = await client.collections.create({
  name: 'Article',
  multiTenancy: weaviate.configure.multiTenancy({
    enabled: true,
  })
})
// The returned value is the full collection definition, showing all defaults
console.log(JSON.stringify(await newCollection.config.get(), null, 2));

JS/TS

await client.schema
  .classCreator()
  .withClass({
    class: 'Article',
    multiTenancyConfig: { enabled: true },
  })
  .do();

Read a single collection definition

Retrieve a collection definition from the schema.

Python (v4)

articles = client.collections.get("Article")
articles_config = articles.config.get()

print(articles_config)

Python (v3)

class_name = "Article"

response = client.schema.get(class_name)

print(json.dumps(response, indent=2))

JS/TS (Beta)

const collectionDefinition = await client.collections.get('Article')
console.log(await collectionDefinition.config.get())

JS/TS

const className = 'Article';

let classDefinition = await client.schema
  .classGetter()
  .withClassName(className)
  .do();

console.log(JSON.stringify(classDefinition, null, 2));

Java

String className = "Article";

Result<WeaviateClass> result = client.schema().classGetter()
  .withClassName(className)
  .run();

String json = new GsonBuilder().setPrettyPrinting().create().toJson(result.getResult());
System.out.println(json);

Go

className := "Article"

class, err := client.Schema().ClassGetter().
  WithClassName(className).
  Do(ctx)

b, err := json.MarshalIndent(class, "", "  ")
fmt.Println(string(b))

Sample configuration: Text objects

This configuration for text objects defines the following:

• The collection name (Article)
• The vectorizer module (text2vec-cohere) and model (embed-multilingual-v2.0)
• A set of properties (title, body) with text data types.

{
    "class": "Article",
    "vectorizer": "text2vec-cohere",
    "moduleConfig": {
        "text2vec-cohere": {
            "model": "embed-multilingual-v2.0",
        },
    },
    "properties": [
        {
            "name": "title",
            "dataType": ["text"]
        },
        {
            "name": "body",
            "dataType": ["text"]
        },
    ],
}

Sample configuration: Nested objects

Added in v1.22

This configuration for nested objects defines the following:

• The collection name (Person)

• The vectorizer module (text2vec-huggingface)

• A set of properties (last_name, address)

  • last_name has text data type
  • address has object data type

• The address property has two nested properties (street and city)

{
    "class": "Person",
    "vectorizer": "text2vec-huggingface",
    "properties": [
        {
            "dataType": ["text"],
            "name": "last_name",
        },
        {
            "dataType": ["object"],
            "name": "address",
            "nestedProperties": [
                {"dataType": ["text"], "name": "street"},
                {"dataType": ["text"], "name": "city"}
            ],
        }
    ],
}

Sample configuration: Generative search

This configuration for generative search defines the following:

• The collection name (Article)
• The default vectorizer module (text2vec-openai)
• The generative module (generative-openai)
• A set of properties (title, chunk, chunk_no and url)
• The tokenization option for the url property
• The vectorization option (skip vectorization) for the url property

{
    "class": "Article",
    "vectorizer": "text2vec-openai",
    "vectorIndexConfig": {
        "distance": "cosine",
    },
    "moduleConfig": {
        "generative-openai": {}
    },
    "properties": [
        {
            "name": "title",
            "dataType": ["text"]
        },
        {
            "name": "chunk",
            "dataType": ["text"]
        },
        {
            "name": "chunk_no",
            "dataType": ["int"]
        },
        {
            "name": "url",
            "dataType": ["text"],
            "tokenization": "field",
            "moduleConfig": {
                "text2vec-openai": {
                    "skip": true
                },
            }
        },
    ],
}

Sample configuration: Images

This configuration for image search defines the following:

• The collection name (Image)

• The vectorizer module (img2vec-neural)

  • The image property configures collection to store image data.

• The vector index distance metric (cosine)

• A set of properties (image), with the image property set as blob.

For image searches, see Image search.

{
    "class": "Image",
    "vectorizer": "img2vec-neural",
    "vectorIndexConfig": {
        "distance": "cosine",
    },
    "moduleConfig": {
        "img2vec-neural": {
            "imageFields": [
                "image"
            ]
        }
    },
    "properties": [
        {
            "name": "image",
            "dataType": ["blob"]
        },
    ],
}

Read all collection definitions

Fetch the database schema to retrieve all of the collection definitions.

Python (v4)

response = client.collections.list_all()

print(response)

Python (v3)

response = client.schema.get()

print(json.dumps(response, indent=2))

JS/TS (Beta)

await client.collections.listAll()

JS/TS

let allClassDefinitions = await client.schema.getter().do();

console.log(JSON.stringify(allClassDefinitions, null, 2));

Java

Result<Schema> result = client.schema().getter()
  .run();

String json = new GsonBuilder().setPrettyPrinting().create().toJson(result.getResult());
System.out.println(json);

Go

schema, err := client.Schema().Getter().
  Do(ctx)

b, err := json.MarshalIndent(schema, "", "  ")
fmt.Println(string(b))

Update a collection definition

Some definitions cannot be modified after you create your collection.

Python (v4)

from weaviate.classes.config import Reconfigure

articles = client.collections.get("Article")

# Update the collection definition
articles.config.update(
    inverted_index_config=Reconfigure.inverted_index(
        bm25_k1=1.5
    )
)
# Coming soon :)

Python (v3)

class_name = "Article"

# Define and create a class
original_class_obj = {
    "class": class_name,
    "invertedIndexConfig": {
        "bm25": {
            "k1": 1.2  # Note the k1 parameter
        }
    }
}

client.schema.create_class(original_class_obj)

# Update the class definition
changed_class_obj = {
    "class": class_name,
    "invertedIndexConfig": {
        "bm25": {
            "k1": 1.5  # Change the k1 parameter from 1.2
        }
    }
}

client.schema.update_config("Article", changed_class_obj)

JS/TS

// This feature is under development

Java

// This feature is under development

Go

// This feature is under development

Update a parameter

Some parameters cannot be modified after you create your collection.

Python (v4)

from weaviate.classes.config import Reconfigure

# Get the Article collection object
articles = client.collections.get("Article")

# Update the collection configuration
articles.config.update(
    # Note, use Reconfigure here (not Configure)
    inverted_index_config=Reconfigure.inverted_index(
        stopwords_removals=["a", "the"]
    )
)

Python (v3)

class_obj = {
    "invertedIndexConfig": {
      "stopwords": {
        "preset": "en",
        "removals": ["a", "the"]
      },
    },
}

client.schema.update_config("Article", class_obj)
class_obj = {
    "invertedIndexConfig": {
      "stopwords": {
        "preset": "en",
        "removals": ["a", "the"]
      },
    },
}

client.schema.update_config("Article", class_obj)

JS/TS

(Vote for the feature request.)

Delete a collection

You can delete any unwanted collection(s), along with the data that they contain.

Deleting a collection also deletes its objects

When you delete a collection, you delete all associated objects!

Be very careful with deletes on a production database and anywhere else that you have important data.

This code deletes a collection and its objects.

Python (v4)

# delete collection "Article" - THIS WILL DELETE THE COLLECTION AND ALL ITS DATA
client.collections.delete("Article")  # Replace with your collection name

Python (v3)

# delete class "Article" - THIS WILL DELETE ALL DATA IN THIS CLASS
client.schema.delete_class("Article")  # Replace with your class name

JS/TS (Beta)

await client.collections.delete('Article')

JS/TS

const className: string = 'YourClassName';  // Replace with your class name

await client.schema
  .classDeleter()
  .withClassName(className)
  .do();

Go

className := "YourClassName"

// delete the class
if err := client.Schema().ClassDeleter().WithClassName(className).Do(context.Background()); err != nil {
  // Weaviate will return a 400 if the class does not exist, so this is allowed, only return an error if it's not a 400
  if status, ok := err.(*fault.WeaviateClientError); ok && status.StatusCode != http.StatusBadRequest {
    panic(err)
  }
}

Java

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Result<Boolean> result = client.schema().classDeleter()
      .withClassName("Article")
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

Curl

curl \
  -X DELETE \
  https://WEAVIATE_INSTANCE_URL/v1/schema/YourClassName  # Replace WEAVIATE_INSTANCE_URL with your instance URL

Add a property

Limitations when adding a property after importing objects

Adding a property after importing objects can lead to limitations in inverted-index related behavior.

This is caused by the inverted index being built at import time. If you add a property after importing objects, the inverted index will not be updated. This means that the new property will not be indexed for existing objects. This can lead to unexpected behavior when querying.

To avoid this, you can either:

• Add the property before importing objects.
• Delete the collection, re-create it with the new property and then re-import the data.

We are working on a re-indexing API to allow you to re-index the data after adding a property. This will be available in a future release.

Python (v4)

from weaviate.classes.config import Property, DataType

articles = client.collections.get("Article")

articles.config.add_property(
    Property(
        name="onHomepage",
        data_type=DataType.BOOL
    )
)

Python (v3)

import weaviate

client = weaviate.Client("http://localhost:8080")

add_prop = {
  "dataType": [
      "boolean"
  ],
  "name": "onHomepage"
}

client.schema.property.create("Article", add_prop)

JavaScript/TypeScript

import weaviate from 'weaviate-ts-client';

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

const className = 'Article';
const prop = {
  dataType: ['boolean'],
  name: 'onHomepage',
};

const response = await client.schema
  .propertyCreator()
  .withClassName(className)
  .withProperty(prop)
  .do();
console.log(JSON.stringify(response, null, 2));

Go

package main

import (
  "context"

  "github.com/weaviate/weaviate-go-client/v4/weaviate"
  "github.com/weaviate/weaviate/entities/models"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }

  prop := &models.Property{
    DataType: []string{"boolean"},
    Name:     "onHomepage",
  }

  err := client.Schema().PropertyCreator().
    WithClassName("Article").
    WithProperty(prop).
    Do(context.Background())

  if err != nil {
    panic(err)
  }
}

Java

package io.weaviate;

import java.util.Arrays;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.schema.model.DataType;
import io.weaviate.client.v1.schema.model.Property;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Property property = Property.builder()
      .dataType(Arrays.asList(DataType.BOOLEAN))
      .name("onHomepage")
      .build();

    Result<Boolean> result = client.schema().propertyCreator()
      .withClassName("Article")
      .withProperty(property)
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

Inspect shards (for a collection)

An index itself can be comprised of multiple shards.

Python (v4)

articles = client.collections.get("Article")

article_shards = articles.config.get_shards()
print(article_shards)

Python (v3)

import weaviate

client = weaviate.Client("http://localhost:8080")

article_shards = client.schema.get_class_shards("Article")
print(article_shards)

JavaScript/TypeScript

import weaviate from 'weaviate-ts-client';

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

const response = await client.schema
  .shardsGetter()
  .withClassName('Article')
  .do();
console.log(JSON.stringify(response, null, 2));

Go

package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v4/weaviate"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }
  shards, err := client.Schema().
    ShardsGetter().
    WithClassName("Article").
    Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", shards)
}

Java

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.schema.model.Shard;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Result<Shard[]> result = client.schema()
      .shardsGetter()
      .withClassName("Article")
      .run()
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

Update shard status

You can manually a shard to READY from READONLY, for example after disk pressure has been lowered.

Python (v4)

articles = client.collections.get("Article")

article_shards = articles.config.get_shards()
print(article_shards)

Python (v3)

import weaviate

client = weaviate.Client("http://localhost:8080")

article_shards = client.schema.get_class_shards("Article")
print(article_shards)

JavaScript/TypeScript

import weaviate from 'weaviate-ts-client';

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

const response = await client.schema
  .shardsGetter()
  .withClassName('Article')
  .do();
console.log(JSON.stringify(response, null, 2));

Go

package main

import (
  "context"
  "fmt"

  "github.com/weaviate/weaviate-go-client/v4/weaviate"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client, err := weaviate.NewClient(cfg)
  if err != nil {
    panic(err)
  }
  shards, err := client.Schema().
    ShardsGetter().
    WithClassName("Article").
    Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", shards)
}

Java

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.schema.model.Shard;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Result<Shard[]> result = client.schema()
      .shardsGetter()
      .withClassName("Article")
      .run()
    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

Further resources

References

• API References: REST: Schema
• References: Configuration: Schema
• Concepts: Data structure

Background knowledge

• Connect to Weaviate
• Tutorial: Schema

Questions and feedback

If you have any questions or feedback, let us know in our user forum.

• Technical questions
• Documentation feedback