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.

Related pages

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

Which endpoint does this use?

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

Manual class creation recommended

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

class_name = "Article"

class_obj = {"class": class_name}

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

JavaScript/TypeScript

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)

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 and url), 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.

Where to find a list of available options

See:

• References: Configuration: Schema
• API References: REST: Schema

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.

Read more about Auto-schema

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

How to perform similarity or generative searches

• Similarity search

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 and url), with data types set accordingly.
• Tokenization option for the url property.
• 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
                },
            }
        },
    ],
}

How to perform similarity or generative searches

• Similarity search
• Generative search

For image objects

The below defines:

• The class name (Image)
• The vectorizer module (img2vec-neural), with the image property set as the store of image data.
• The vector index distance metric (cosine)
• A set of properties (image), with the image property set as blob.

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

How to perform image searches

• Image search

Read a class definition

You can retrieve a class definition from the schema using the class name.

Python

class_name = "Article"

response = client.schema.get(class_name)

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

JavaScript/TypeScript

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

Read all class definitions

You can also retrieve all class definitions by fetching the entire schema.

Python

response = client.schema.get()

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

JavaScript/TypeScript

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

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)

JavaScript/TypeScript

// This feature is under development

Java

// This feature is under development

Go

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

Deleting a class == Deleting its objects

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

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

JavaScript/TypeScript

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

Curl

curl \
  -X DELETE \
  https://some-endpoint.weaviate.network/v1/schema/YourClassName

More Resources

For additional information, try these sources.

1. Frequently Asked Questions
2. Weaviate Community Forum
3. Knowledge base of old issues
4. Stackoverflow
5. Weaviate slack channel