Basic collection operations

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.

Python and JS/TS client - Vectorizer Configuration API Changes

Starting with Weaviate Python client v4.16.0, the vectorizer configuration API has been updated.
Starting with Weaviate JS/TS client v3.8.0, the vectorizer configuration API has been updated.

Action required: Update to the latest client version and migrate your code to use the new vectorizer configuration API.

Create a collection

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

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.

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

client.collections.create("Article")

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

className := "Article"

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

  // Create the collection (also called class)
  err := client.Schema().ClassCreator().
    WithClass(emptyClass).
    Do(ctx)

client.collections.create("Article");

String collectionName = "Article";

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

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

await client.Collections.Create(new CollectionConfig { Name = "Article" });

Production ready collections

• Manually define you data schema: Avoid using the auto-schema feature, instead, manually define the properties for your collection.
• Avoid creating too many collections: Using too many collections can lead to scalability issues like high memory usage and degraded query performance. Instead, consider using multi-tenancy, where a single collection is subdivided into multiple tenants. For more details, see Starter Guides: Scaling limits with collections.

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

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

import { dataType } from 'weaviate-client';

await client.collections.create({
  name: 'Article',
  properties: [
    {
      name: 'title',
      dataType: dataType.TEXT,
    },
    {
      name: 'body',
      dataType: dataType.TEXT,
    },
  ],
})

  articleClass := &models.Class{
    Class:       "Article",
    Description: "Collection of articles",
    Properties: []*models.Property{
      {
        Name:     "title",
        DataType: schema.DataTypeText.PropString(),
      },
      {
        Name:     "body",
        DataType: schema.DataTypeText.PropString(),
      },
    },
  }

client.collections.create("Article",
    col -> col.properties(Property.text("title"), Property.text("body")));

// Define collection properties
Property titleProperty = Property.builder()
    .name("title")
    .description("Title Property Description...")
    .dataType(Arrays.asList(DataType.TEXT))
    .build();
Property bodyProperty = Property.builder()
    .name("body")
    .description("Body Property Description...")
    .dataType(Arrays.asList(DataType.TEXT))
    .build();

// Add the defined properties to the collection
WeaviateClass articleCollection = WeaviateClass.builder()
    .className(collectionName)
    .description("Article collection Description...")
    .properties(Arrays.asList(titleProperty, bodyProperty))
    .build();

Result<Boolean> result = client.schema().classCreator()
    .withClass(articleCollection)
    .run();

await client.Collections.Create(new CollectionConfig
{
    Name = "Article",
    Properties =
    [
        Property.Text("title"),
        Property.Text("body"),
    ]
});

Or by using the fields from a class:

// public class Article
// {
//     public string Title { get; set; }
//     public string Body { get; set; }
// }
    
await client.Collections.Create(new CollectionConfig
{
    Name = "Article",
    Properties = [.. Property.FromClass<Article>()],
});

Create a collection with a vectorizer

Specify a vectorizer for a collection that will generate vector embeddings when creating objects and executing vector search queries.

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

client.collections.create(
    "Article",
    vector_config=Configure.Vectors.text2vec_openai(),
    properties=[
        Property(name="title", data_type=DataType.TEXT),
        Property(name="body", data_type=DataType.TEXT),
    ],
)

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

await client.collections.create({
  name: 'Article',
  vectorizers: vectors.text2VecOpenAI(),
  properties: [
    { name: 'title', dataType: dataType.TEXT },
    { name: 'body', dataType: dataType.TEXT },
  ],
})

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

client.collections.create("Article",
    col -> col.vectorConfig(VectorConfig.text2vecTransformers())
        .properties(Property.text("title"), Property.text("body")));

// Additional configuration not shown
// Define the vectorizer in the WeaviateClass Builder
WeaviateClass articleCollection = WeaviateClass.builder()
    .className(collectionName)
    .properties(Arrays.asList(titleProperty, bodyProperty))
    .vectorizer("text2vec-openai") // Vectorize of your choic e.g. text2vec-openai or text2vec-cohere
    .build();
// Add the collection to the schema
Result<Boolean> result = client.schema().classCreator()
    .withClass(articleCollection)
    .run();

await client.Collections.Create(new CollectionConfig
{
    Name = "Article",
    VectorConfig = new VectorConfigList
    {
        new VectorConfig("default", new Vectorizer.Text2VecTransformers())
    },
    Properties =
    [
        Property.Text("title"),
        Property.Text("body"),
    ]
});

Vectorizer configuration

Find out more about the vectorizer and vector index configuration in Manage collections: Vectorizer and vector index.

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.

Check if a collection exists

Get a boolean indicating whether a given collection exists.

PythonJavaScript/TypeScript

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

exists = client.collections.exists("Article")  # Returns a boolean

var exists = await client.collections.exists("Article")  // Returns a boolean

Read a single collection definition

Retrieve a collection definition from the schema.

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

print(articles_config)

let articles = client.collections.use('Article')
const collectionConfig = await articles.config.get()
console.log(collectionConfig)

className := "Article"

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

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

CollectionHandle<Map<String, Object>> articles =
    client.collections.use("Article");
Optional<CollectionConfig> articlesConfig = articles.config.get();

System.out.println(articlesConfig);

String collectionName = "Article";

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

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

var articles = client.Collections.Use<object>("Article");
var articlesConfig = await articles.Config.Get();

Console.WriteLine(articlesConfig);

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 retrieval augmented generation 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.

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

response = client.collections.list_all(simple=False)

print(response)

const allCollections = await client.collections.listAll()
console.log(JSON.stringify(allCollections, null, 2));

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

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

List<CollectionConfig> response = client.collections.list();

System.out.println(response);

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

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

var response = new List<CollectionConfig>();
await foreach (var collection in client.Collections.List())
{
    response.Add(collection);
    Console.WriteLine(collection);
}

Update a collection definition

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, the replication factor of a shard can be changed.

You can update a collection definition to change the mutable collection settings.

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

from weaviate.classes.config import (
    Reconfigure,
    VectorFilterStrategy,
    ReplicationDeletionStrategy,
)

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

# Update the collection definition
articles.config.update(
    description="An updated collection description.",
    property_descriptions={
        "title": "The updated title description for article",
    },  # Available from Weaviate v1.31.0
    inverted_index_config=Reconfigure.inverted_index(bm25_k1=1.5),
    vector_config=Reconfigure.Vectors.update(
        name="default",
        vector_index_config=Reconfigure.VectorIndex.hnsw(
            filter_strategy=VectorFilterStrategy.ACORN  # Available from Weaviate v1.27.0
        ),
    ),
    replication_config=Reconfigure.replication(
        deletion_strategy=ReplicationDeletionStrategy.TIME_BASED_RESOLUTION  # Available from Weaviate v1.28.0
    ),
)
articles = client.collections.use("Article")

article_shards = articles.config.update_shards(
    status="READY",
    shard_names=shard_names,  # The names (List[str]) of the shard to update (or a shard name)
)

print(article_shards)

import { reconfigure } from 'weaviate-client';

let articles = client.collections.use('Article')
await articles.config.update({
  invertedIndex: reconfigure.invertedIndex({
    bm25k1: 1.5 // Change the k1 parameter from 1.2
  }),
  vectorizers: reconfigure.vectors.update({
    vectorIndexConfig: reconfigure.vectorIndex.hnsw({
      quantizer: reconfigure.vectorIndex.quantizer.pq(),
      ef: 4,
      filterStrategy: 'acorn',  // Available from Weaviate v1.27.0
    }),

  })
})

  updatedArticleClassConfig := &models.Class{
    // Note: The new collection config must be provided in full,
    // including the configuration that is not being updated.
    // We suggest using the original class config as a starting point.
    Class: "Article",
    InvertedIndexConfig: &models.InvertedIndexConfig{
      Bm25: &models.BM25Config{
        K1: 1.5,
      },
    },
    VectorIndexConfig: map[string]interface{}{
      "filterStrategy": "acorn",
    },
    ReplicationConfig: &models.ReplicationConfig{
      DeletionStrategy: models.ReplicationConfigDeletionStrategyTimeBasedResolution,
    },
  }

CollectionHandle<Map<String, Object>> articles =
    client.collections.use("Article");

articles.config.update(col -> col
    .description("An updated collection description.")
    .invertedIndex(idx -> idx.bm25(bm25Builder -> bm25Builder.k1(1.5f))));
CollectionHandle<Map<String, Object>> articles =
    client.collections.use("Article");

List<Shard> articleShards =
    articles.config.updateShards(ShardStatus.READONLY, shardName);
System.out.println(articleShards);

// Get existing collection
Result<WeaviateClass> existingResult = client.schema().classGetter()
    .withClassName(collectionName)
    .run();

assertThat(existingResult).isNotNull()
    .returns(false, Result::hasErrors);

WeaviateClass existingClass = existingResult.getResult();

// Create updated configurations
InvertedIndexConfig invertedConfig = InvertedIndexConfig.builder()
    .bm25(BM25Config.builder().k1(1.5f).build())
    .build();

VectorIndexConfig vectorConfig = VectorIndexConfig.builder()
    .filterStrategy(VectorIndexConfig.FilterStrategy.ACORN)
    .build();

ReplicationConfig replicationConfig = ReplicationConfig.builder()
    .deletionStrategy(ReplicationConfig.DeletionStrategy.NO_AUTOMATED_RESOLUTION)
    .build();

// Update collection with new configurations - preserve critical existing configs
WeaviateClass updatedClass = WeaviateClass.builder()
    .className(collectionName)
    .shardingConfig(existingClass.getShardingConfig())     // Preserve sharding (immutable)
    .invertedIndexConfig(invertedConfig)                   // Update
    .vectorIndexConfig(vectorConfig)                       // Update
    .replicationConfig(replicationConfig)                  // Update
    .build();

Result<Boolean> updateResult = client.schema().classUpdater()
    .withClass(updatedClass)
    .run();

var articles = client.Collections.Use<object>("Article");

await articles.Config.Update(c =>
{
    c.Description = "An updated collection description.";
    c.InvertedIndexConfig.Bm25.K1 = 1.5f;
});
    // Coming soon

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.

PythonJavaScript/TypeScriptGoJavaJava v6 (Beta)CurlC# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

# collection_name can be a string ("Article") or a list of strings (["Article", "Category"])
client.collections.delete(
    collection_name
)  # THIS WILL DELETE THE SPECIFIED COLLECTION(S) AND THEIR OBJECTS

# Note: you can also delete all collections in the Weaviate instance with:
# client.collections.delete_all()

// delete collection "Article" - THIS WILL DELETE THE COLLECTION AND ALL ITS DATA
await client.collections.delete('Article')

// you can also delete all collections of a cluster
// await client.collections.deleteAll()

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

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

client.collections.delete(collectionName);

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

await client.Collections.Delete(collectionName);

Add a property

Indexing limitations after data import

There are no index limitations when you add collection properties before you import data.

If you add a new property after you import data, there is an impact on indexing.

Property indexes are built at import time. If you add a new property after importing some data, pre-existing objects index aren't automatically updated to add the new property. This means pre-existing objects aren't added to the new property index. Queries may return unexpected results because the index only includes new objects.

To create an index that includes all of the objects in a collection, do one of the following:

• New collections: Add all of the collection's properties before importing objects.
• Existing collections: Export the existing data from the collection. Re-create it with the new property. Import the data into the updated collection.

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.

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

from weaviate.classes.config import Property, DataType

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

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

let articles = client.collections.use('Article')

articles.config.addProperty({
  name: "onHomepage",
  dataType: "boolean",
});

package main

import (
  "context"

  "github.com/weaviate/weaviate-go-client/v5/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)
  }
}

  // Coming soon

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

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

CollectionClient<object> articles = client.Collections.Use<object>("Article");
await articles.Config.AddProperty(Property.Text("description"));

Further resources

• Manage collections: Vectorizer and vector index
• References: Collection definition
• Concepts: Data structure

• API References: REST: Schema

Questions and feedback

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

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.