Manage classes (object collections)
Overview
Each Weaviate object belongs to one (and only one) class. This page covers the essential topics in relation to managing Weaviate classes.
Under the hood, these are carried out through the schema
REST endpoint. For raw REST commands, or a full list of parameters, please refer to the reference page.
Create a class
You can create a class:
- Manually, or
- Have Weaviate create it as needed (with
Auto-schema
).
We recommend you create classes manually, as:
- You will gain greater control over your data model, and
- Many of the settings in the class definition are immutable.
Manual creation
To create a class, you must specify the class name with the class
parameter.
- Python
- JavaScript/TypeScript
- Java
- Go
class_name = "Article"
class_obj = {"class": class_name}
client.schema.create_class(class_obj) # returns null on success
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));
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();
className := "Article"
emptyClass := &models.Class{
Class: className,
}
// Add the class to the schema
err := client.Schema().ClassCreator().
WithClass(emptyClass).
Do(ctx)
Typically, you would specify additional configurations. We include some examples in the following sections.
Sample configuration
One example configuration is shown below, which defines:
- The class name (
Article
) - The vectorizer module (
text2vec-cohere
) - The vector distance metric (
cosine
) - Which generative module to use (
generative-openai
) - A set of properties (
title
,chunk
,chunk_no
andurl
), with data types set accordingly. - Tokenization option for the
url
property.
{
"class": "Article",
"vectorizer": "text2vec-cohere",
"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"
},
],
}
You can specify as many of the available options in the class definition as you would like.
Auto-schema
If you create objects into a class that does not yet exist, Weaviate will create the class by inferring necessary information as required.
See this page
Example class configurations
We include a few sample class configurations below as starting points.
For simple text objects
The below defines:
- The class name (
Article
) - The vectorizer module (
text2vec-cohere
) and model (embed-multilingual-v2.0
) - A set of properties (
title
,body
) withtext
data types.
{
"class": "Article",
"vectorizer": "text2vec-cohere",
"moduleConfig": {
"text2vec-cohere": {
"model": "embed-multilingual-v2.0",
},
},
"properties": [
{
"name": "title",
"dataType": ["text"]
},
{
"name": "body",
"dataType": ["text"]
},
],
}
For text objects and generative search
The below defines:
- The class name (
Article
) - The vectorizer module (
text2vec-openai
) and default model - The vector index distance metric (
cosine
) - Which generative module to use (
generative-openai
) - A set of properties (
title
,chunk
,chunk_no
andurl
), with data types set accordingly. - Tokenization option for the
url
property. - Vectorization option (
skip
vectorization) for theurl
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
},
}
},
],
}
For image objects
The below defines:
- The class name (
Image
) - The vectorizer module (
img2vec-neural
), with theimage
property set as the store of image data. - The vector index distance metric (
cosine
) - A set of properties (
image
), with theimage
property set asblob
.
{
"class": "Image",
"vectorizer": "img2vec-neural",
"vectorIndexConfig": {
"distance": "cosine",
},
"moduleConfig": {
"img2vec-neural": {
"imageFields": [
"image"
]
}
},
"properties": [
{
"name": "image",
"dataType": ["blob"]
},
],
}
Read a class definition
You can retrieve a class definition from the schema using the class name.
- Python
- JavaScript/TypeScript
- Java
- Go
class_name = "Article"
response = client.schema.get(class_name)
print(json.dumps(response, indent=2))
const className = 'Article';
let classDefinition = await client
.schema
.classGetter()
.withClassName(className)
.do();
console.log(JSON.stringify(classDefinition, null, 2));
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);
className := "Article"
class, err := client.Schema().ClassGetter().
WithClassName(className).
Do(ctx)
b, err := json.MarshalIndent(class, "", " ")
fmt.Println(string(b))
Read all class definitions
You can also retrieve all class definitions by fetching the entire schema.
- Python
- JavaScript/TypeScript
- Java
- Go
response = client.schema.get()
print(json.dumps(response, indent=2))
let allClassDefinitions = await client
.schema
.getter()
.do();
console.log(JSON.stringify(allClassDefinitions, null, 2));
Result<Schema> result = client.schema().getter()
.run();
String json = new GsonBuilder().setPrettyPrinting().create().toJson(result.getResult());
System.out.println(json);
schema, err := client.Schema().Getter().
Do(ctx)
b, err := json.MarshalIndent(schema, "", " ")
fmt.Println(string(b))
Update a class definition
You can update class definitions as follows.
Are all settings mutable?
Not all settings are mutable.
A typical use case for this functionality is to update configuration, such as the vectorIndexConfig. Note that even in mutable sections, such as vectorIndexConfig, some fields may be immutable.
- Python
- JavaScript/TypeScript
- Java
- Go
class_name = "Article"
# Define and create a class
original_class_obj = {
"class": class_name,
"vectorIndexConfig": {
"distance": "cosine" # Note the distance metric
}
}
client.schema.create_class(original_class_obj)
# Update the class definition
changed_class_obj = {
"class": class_name,
"vectorIndexConfig": {
"distance": "dot" # Change the distance metric
}
}
client.schema.update_config("Article", changed_class_obj)
// This feature is under development
// This feature is under development
// This feature is under development
How do I change immutable settings then?
In this case, you must delete the class recreate it. If possible, we recommend using the cursor API to retrieve all objects and re-populate it.
Delete a class
You can delete any unwanted class(es), along with the data that they contain.
Know that deleting a class will also delete all associated objects!
Do not do this to a production database, or anywhere where you do not wish to delete your data.
Run the code below to delete the relevant class and its objects.
- Python
- JavaScript/TypeScript
- Go
- Curl
# delete class "YourClassName" - THIS WILL DELETE ALL DATA IN THIS CLASS
client.schema.delete_class("YourClassName") # Replace with your class name - e.g. "Question"
const className: string = 'YourClassName'; // Replace with your class name
await client.schema
.classDeleter()
.withClassName(className)
.do();
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)
}
}
curl \
-X DELETE \
https://some-endpoint.weaviate.network/v1/schema/YourClassName
More Resources
For additional information, try these sources.