REST - /v1/schema
Overview
The schema
endpoint is for creating, reading, updating and deleting collections (also called collections) and properties. The overall configuration is referred to as the schema.
Get the schema
The response will contain an array of objects.
Method and URL
GET /v1/schema
Example request
- Python (v4)
- Python (v3)
- JS/TS (Beta)
- JS/TS
- Go
- Java
- Curl
import weaviate
client = weaviate.connect_to_local()
try:
schema = client.collections.list_all(simple=False) # Use `simple=False` to get comprehensive information
print(schema)
finally:
client.close()
import weaviate
client = weaviate.Client("http://localhost:8080")
schema = client.schema.get()
print(schema)
import weaviate from 'weaviate-client';
const client = await weaviate.connectToLocal({
httpHost: 'localhost',
httpPort: 8080,
httpSecure: false,
grpcHost: 'localhost',
grpcPort: 50051,
grpcSecure: false,
});
console.log(await client.getMeta())
import weaviate from 'weaviate-ts-client';
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
const response = await client.schema
.getter()
.do();
console.log(JSON.stringify(response, null, 2));
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)
}
schema, err := client.Schema().Getter().Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", schema)
}
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.Schema;
public class App {
public static void main(String[] args) {
Config config = new Config("http", "localhost:8080");
WeaviateClient client = new WeaviateClient(config);
Result<Schema> result = client.schema().getter().run();
if (result.hasErrors()) {
System.out.println(result.getError());
return;
}
System.out.println(result.getResult());
}
}
curl http://localhost:8080/v1/schema
Example response
{
"classes": [
{
"class": "Category",
"description": "Category an article is a type off",
"moduleConfig": {
"text2vec-contextionary": {
"vectorizeClassName": false
}
},
"properties": [
{
"dataType": [
"text"
],
"description": "category name",
"indexFilterable": true,
"indexSearchable": true,
"moduleConfig": {
"text2vec-contextionary": {
"vectorizePropertyName": false
}
},
"name": "name"
}
],
"vectorIndexType": "hnsw",
"vectorizer": "none"
},
{
"class": "Publication",
"description": "A publication with an online source",
"moduleConfig": {
"text2vec-contextionary": {
"vectorizeClassName": false
}
},
"properties": [
{
"dataType": [
"text"
],
"description": "Name of the publication",
"name": "name"
},
{
"dataType": [
"geoCoordinates"
],
"description": "Geo location of the HQ",
"name": "headquartersGeoLocation"
},
{
"dataType": [
"Article"
],
"description": "The articles this publication has",
"name": "hasArticles"
},
{
"dataType": [
"Article"
],
"description": "Articles this author wrote",
"name": "wroteArticles"
}
],
"vectorIndexType": "hnsw",
"vectorizer": "none"
},
{
"class": "Author",
"description": "Normalised types",
"moduleConfig": {
"text2vec-contextionary": {
"vectorizeClassName": true
}
},
"properties": [
{
"dataType": [
"text"
],
"description": "Name of the author",
"name": "name"
},
{
"dataType": [
"Publication"
],
"description": "The publication this author writes for",
"name": "writesFor"
}
],
"vectorIndexType": "hnsw",
"vectorizer": "none"
},
{
"class": "Article",
"description": "Normalised types",
"moduleConfig": {
"text2vec-contextionary": {
"vectorizeClassName": false
}
},
"properties": [
{
"dataType": [
"text"
],
"description": "title of the article",
"indexFilterable": true,
"indexSearchable": true,
"moduleConfig": {
"text2vec-contextionary": {
"vectorizePropertyName": false
}
},
"name": "title"
},
{
"dataType": [
"text"
],
"description": "url of the article",
"indexFilterable": true,
"indexSearchable": false,
"moduleConfig": {
"text2vec-contextionary": {
"vectorizePropertyName": false
}
},
"name": "url"
},
{
"dataType": [
"text"
],
"description": "summary of the article",
"indexFilterable": true,
"indexSearchable": true,
"moduleConfig": {
"text2vec-contextionary": {
"vectorizePropertyName": false
}
},
"name": "summary"
},
{
"dataType": [
"date"
],
"description": "date of publication of the article",
"name": "publicationDate"
},
{
"dataType": [
"int"
],
"description": "Words in this article",
"name": "wordCount"
},
{
"dataType": [
"Author",
"Publication"
],
"description": "authors this article has",
"name": "hasAuthors"
},
{
"dataType": [
"Publication"
],
"description": "publication this article is in",
"name": "inPublication"
},
{
"dataType": [
"Category"
],
"description": "category this article is of",
"name": "ofCategory"
},
{
"dataType": [
"boolean"
],
"description": "whether the article is currently accessible through the url",
"name": "isAccessible"
}
],
"vectorIndexType": "hnsw",
"vectorizer": "none"
}
]
}
Create a collection
Create a new data object collection in the schema.
From v1.5.0
onwards, manual creation of a schema is optional. Learn more about Auto Schema.
Method and URL
POST /v1/schema
Parameters
For more details on these parameters, see the schema configuration reference page.
Name | Location | Type | Description |
---|---|---|---|
class | body | string | The name of the collection (a.k.a. class). Multiple words should be concatenated in CamelCase, e.g. ArticleAuthor . |
description | body | string | Description of the collection. |
vectorizer | body | string | Vectorizer to use for data objects added to this collection. Default can be set via Weaviate environment variables. |
vectorIndexType | body | string | Vector index type. Defaults to hnsw. |
vectorIndexConfig | body | object | Vector index type specific settings. See the vector index configuration page for more details. |
moduleConfig > <module_name> > vectorizeClassName | body | boolean | Include the collection name in vector calculation (default true). Learn more about semantic indexing in Weaviate. |
properties | body | array | An array of property objects. |
properties > name | body | string | The name of the property. Multiple words should be concatenated in camelCase, e.g. nameOfAuthor . |
properties > dataType | body | array | See the available data types. |
properties > description | body | string | Description of the property. |
properties > moduleConfig > <module_name> > skip | body | boolean | If true, the whole property will NOT be included in vectorization. Default is false, meaning that the object will be NOT be skipped. |
properties > moduleConfig > <module_name> > vectorizePropertyName | body | boolean | Whether the name of the property is used in the calculation for the vector position of data objects. Default is true. Learn more about semantic indexing in Weaviate. |
properties > indexFilterable (available from v1.19 ) | body | boolean | Should the data stored in this property be indexed with the filterable, Roaring Bitmap index? Read more about indexing in Weaviate. |
properties > indexSearchable (available from v1.19 ) | body | boolean | Should the data stored in this property be indexed to allow BM25/hybrid-search index? Read more on how to configure indexing in Weaviate. |
properties > tokenization | body | string | Only for string /text props. Introduced in v1.12.0 . Control how a field is tokenized in the inverted index. Defaults to "word" , can be set to "field" . Learn more about property tokenization. |
invertedIndexConfig > bm25 > b | body | float | b parameter for BM25 searches. Default: 0.75 |
invertedIndexConfig > bm25 > k1 | body | float | k1 parameter for BM25 searches. Default: 1.2 |
invertedIndexConfig > stopwords | body | object | Configure stopword behavior. See more details here. |
invertedIndexConfig > indexTimestamps | body | boolean | Maintain an inverted index for each object by its internal timestamps, currently including creationTimeUnix and lastUpdateTimeUnix .See more details here. |
invertedIndexConfig > indexNullState | body | boolean | Index null values to allow filtering. |
invertedIndexConfig > indexPropertyLength | body | boolean | Index property lengths to allow filtering. |
shardingConfig | body | object | Sharding specific settings. See the schema configuration reference page for more details. |
replicationConfig > factor | body | int | The replication factor, aka the number of copies in a replicated Weaviate setup. |
multiTenancyConfig > enabled | body | Boolean | Whether to enable multi-tenancy for this collection. (Defaults to false .) |
Example request for creating a collection
You can specify as few parameters as the collection name.
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Go
- Java
- Curl
import weaviate
import weaviate.classes as wvc
client = weaviate.connect_to_local()
try:
client.collections.create(
name="Article",
description="A written text, for example a news article or blog post",
properties=[
wvc.config.Property(
data_type=wvc.config.DataType.TEXT,
description="Title of the article",
name="title",
),
wvc.config.Property(
data_type=wvc.config.DataType.TEXT,
description="The content of the article",
name="content",
),
]
)
finally:
client.close()
import weaviate
client = weaviate.Client("http://localhost:8080")
class_obj = {
"class": "Article",
"description": "A written text, for example a news article or blog post",
"properties": [
{
"dataType": ["text"],
"description": "Title of the article",
"name": "title",
},
{
"dataType": ["text"],
"description": "The content of the article",
"name": "content"
}
]
}
client.schema.create_class(class_obj)
import weaviate from 'weaviate-ts-client';
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
const classObj = {
'class': 'Article',
'description': 'A written text, for example a news article or blog post',
'vectorizeClassName': true,
'properties': [
{
'name': 'title',
'dataType': ['string'],
'description': 'Title of the article',
'vectorizePropertyName': true,
'index': true,
},
{
'name': 'content',
'dataType': ['text'],
'description': 'The content of the article',
},
],
};
const response = await client
.schema
.classCreator()
.withClass(classObj)
.do();
console.log(JSON.stringify(response, null, 2));
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)
}
classObj := &models.Class{
Class: "Article",
Description: "A written text, for example a news article or blog post",
Properties: []*models.Property{
{
DataType: []string{"string"},
Description: "Title of the article",
Name: "title",
},
{
DataType: []string{"text"},
Description: "The content of the article",
Name: "content",
},
},
}
err := client.Schema().ClassCreator().WithClass(classObj).Do(context.Background())
if err != nil {
panic(err)
}
}
package io.weaviate;
import java.util.ArrayList;
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;
import io.weaviate.client.v1.schema.model.WeaviateClass;
public class App {
public static void main(String[] args) {
Config config = new Config("http", "localhost:8080");
WeaviateClient client = new WeaviateClient(config);
WeaviateClass clazz = WeaviateClass.builder()
.className("Article")
.description("A written text, for example a news article or blog post")
.properties(new ArrayList() { {
add(Property.builder()
.dataType(new ArrayList(){ { add(DataType.STRING); } })
.description("Title of the article")
.name("title")
.build());
add(Property.builder()
.dataType(new ArrayList(){ { add(DataType.TEXT); } })
.description("The content of the article")
.name("content")
.build());
} })
.build();
Result<Boolean> result = client.schema().classCreator().withClass(clazz).run();
if (result.hasErrors()) {
System.out.println(result.getError());
return;
}
System.out.println(result.getResult());
}
}
curl \
-X POST \
-H "Content-Type: application/json" \
-d '{
"class": "Article",
"description": "A written text, for example a news article or blog post",
"properties": [
{
"dataType": [
"string"
],
"description": "Title of the article",
"name": "title"
},
{
"dataType": [
"text"
],
"description": "The content of the article",
"name": "content"
}
]
}' \
http://localhost:8080/v1/schema
Or you can manually specify any number of the possible parameters:
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Go
- Java
- Curl
import weaviate
import weaviate.classes as wvc
client = weaviate.connect_to_local()
try:
client.collections.create(
name="Article",
description="A written text, for example a news article or blog post",
vector_index_config=wvc.config.Configure.VectorIndex.hnsw(
distance_metric=wvc.config.VectorDistances.COSINE,
ef=128,
max_connections=64
),
vectorizer_config=wvc.config.Configure.Vectorizer.text2vec_openai(
vectorize_collection_name=True,
),
properties=[
wvc.config.Property(
data_type=wvc.config.DataType.TEXT,
description="Title of the article",
name="title",
index_filterable=True,
index_searchable=True,
skip_vectorization=False,
vectorize_property_name=False,
),
wvc.config.Property(
data_type=wvc.config.DataType.TEXT,
description="The content of the article",
name="content",
index_filterable=True,
index_searchable=True,
skip_vectorization=False,
vectorize_property_name=False,
),
],
sharding_config=wvc.config.Configure.sharding(
virtual_per_physical=128,
desired_count=1,
desired_virtual_count=128,
)
)
finally:
client.close()
import weaviate
client = weaviate.Client("http://localhost:8080")
class_obj = {
"class": "Article",
"description": "A written text, for example a news article or blog post",
"vectorIndexType": "hnsw",
"vectorIndexConfig": {
"distance": "cosine",
"efConstruction": 128,
"maxConnections": 64
},
"vectorizer": "text2vec-contextionary",
"moduleConfig": {
"text2vec-contextionary": {
"vectorizeClassName": True
}
},
"properties": [
{
"dataType": [
"text"
],
"description": "Title of the article",
"name": "title",
"indexFilterable": True,
"indexSearchable": True,
"moduleConfig": {
"text2vec-contextionary": {
"skip": False,
"vectorizePropertyName": False
}
}
},
{
"dataType": [
"text"
],
"description": "The content of the article",
"name": "content",
"indexFilterable": True,
"indexSearchable": True,
"moduleConfig": {
"text2vec-contextionary": {
"skip": False,
"vectorizePropertyName": False
}
}
}
],
"shardingConfig": {
"virtualPerPhysical": 128,
"desiredCount": 1,
"desiredVirtualCount": 128,
},
"invertedIndexConfig": {
"stopwords": {
"preset": "en",
"additions": ["star", "nebula"],
"removals": ["a", "the"]
},
"indexTimestamps": True
},
"replicationConfig": {
"factor": 3
}
}
client.schema.create_class(class_obj)
import weaviate from 'weaviate-ts-client';
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
const classObj = {
class: 'Article',
description: 'A written text, for example a news article or blog post',
vectorIndexType: 'hnsw',
vectorIndexConfig: {
distance: 'cosine',
efConstruction: 128,
maxConnections: 64,
},
vectorizer: 'text2vec-contextionary',
moduleConfig: {
'text2vec-contextionary': {
vectorizeClassName: true,
},
},
properties: [
{
dataType: [
'text',
],
description: 'Title of the article',
name: 'title',
indexFilterable: true,
indexSearchable: true,
moduleConfig: {
'text2vec-contextionary': {
skip: false,
vectorizePropertyName: false,
},
},
},
{
dataType: [
'text',
],
description: 'The content of the article',
name: 'content',
indexFilterable: true,
indexSearchable: true,
moduleConfig: {
'text2vec-contextionary': {
skip: false,
vectorizePropertyName: false,
},
},
},
],
shardingConfig: {
virtualPerPhysical: 128,
desiredCount: 1,
desiredVirtualCount: 128,
},
invertedIndexConfig: {
stopwords: {
preset: 'en',
additions: ['star', 'nebula'],
removals: ['a', 'the'],
},
indexTimestamps: true,
},
replicationConfig: {
factor: 3,
},
};
const response = await client
.schema
.classCreator()
.withClass(classObj)
.do();
console.log(JSON.stringify(response, null, 2));
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)
}
classObj := &models.Class{
Class: "Article",
Description: "A written text, for example a news article or blog post",
VectorIndexType: "hnsw",
Vectorizer: "text2vec-contextionary",
VectorIndexConfig: map[string]interface{}{
"distance": "cosine",
"ef": float64(128),
"efConstruction": float64(128),
"maxConnections": float64(32),
},
Properties: []*models.Property{
{
DataType: []string{"text"},
Description: "Title of the article",
Name: "title",
IndexFilterable: true,
IndexSearchable: true,
},
{
DataType: []string{"text"},
Description: "The content of the article",
Name: "content",
IndexFilterable: true,
IndexSearchable: true,
},
},
InvertedIndexConfig: &models.InvertedIndexConfig{
Stopwords: &models.StopwordConfig{
Preset: "en",
Additions: []string{"star", "nebula"},
Removals: []string{"a", "the"},
},
IndexTimestamps: true,
},
ReplicationConfig: &models.ReplicationConfig{
Factor: 3,
}
}
err := client.Schema().ClassCreator().WithClass(classObj).Do(context.Background())
if err != nil {
panic(err)
}
}
package io.weaviate;
import java.util.ArrayList;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.misc.model.InvertedIndexConfig;
import io.weaviate.client.v1.misc.model.ShardingConfig;
import io.weaviate.client.v1.misc.model.StopwordConfig;
import io.weaviate.client.v1.misc.model.VectorIndexConfig;
import io.weaviate.client.v1.schema.model.DataType;
import io.weaviate.client.v1.schema.model.Property;
import io.weaviate.client.v1.schema.model.WeaviateClass;
import io.weaviate.client.v1.misc.model.ReplicationConfig;
public class App {
public static void main(String[] args) {
Config config = new Config("http", "localhost:8080");
WeaviateClient client = new WeaviateClient(config);
StopwordConfig stopwordConfig = StopwordConfig.builder()
.preset("en")
.additions(new String[]{ "star", "nebula" })
.removals(new String[]{ "a", "the" })
.build();
InvertedIndexConfig invertedIndexConfig = InvertedIndexConfig.builder()
.stopwords(stopwordConfig)
.indexTimestamps(true)
.build();
VectorIndexConfig vectorIndexConfig = VectorIndexConfig.builder()
.distance("cosine")
.cleanupIntervalSeconds(300)
.efConstruction(128)
.maxConnections(64)
.vectorCacheMaxObjects(500000)
.ef(-1)
.skip(false)
.dynamicEfFactor(8)
.dynamicEfMax(500)
.dynamicEfMin(100)
.flatSearchCutoff(40000)
.build();
ShardingConfig shardingConfig = ShardingConfig.builder()
.desiredCount(1)
.desiredVirtualCount(128)
.virtualPerPhysical(128)
.build();
ReplicationConfig replicationConfig = ReplicationConfig.builder()
.factor(3)
.build();
WeaviateClass clazz = WeaviateClass.builder()
.className("Article")
.description("A written text, for example a news article or blog post")
.vectorIndexType("hnsw")
.vectorizer("text2vec-contextionary")
.invertedIndexConfig(invertedIndexConfig)
.shardingConfig(shardingConfig)
.vectorIndexConfig(vectorIndexConfig)
.replicationConfig(replicationConfig)
.properties(new ArrayList() { {
add(Property.builder()
.dataType(new ArrayList(){ { add(DataType.TEXT); } })
.description("Title of the article")
.name("title")
.indexFilterable(true)
.indexSearchable(true)
.build());
add(Property.builder()
.dataType(new ArrayList(){ { add(DataType.TEXT); } })
.description("The content of the article")
.name("content")
.indexFilterable(true)
.indexSearchable(true)
.build());
} })
.build();
Result<Boolean> result = client.schema().classCreator().withClass(clazz).run();
if (result.hasErrors()) {
System.out.println(result.getError());
return;
}
System.out.println(result.getResult());
}
}
curl \
-X POST \
-H "Content-Type: application/json" \
-d '{
"class": "Article",
"description": "A written text, for example a news article or blog post",
"vectorIndexType": "hnsw",
"vectorIndexConfig": {
"distance": "cosine",
"efConstruction": 128,
"maxConnections": 64
},
"vectorizer": "text2vec-contextionary",
"moduleConfig": {
"text2vec-contextionary": {
"vectorizeClassName": true
}
},
"properties": [
{
"dataType": [
"text"
],
"description": "Title of the article",
"name": "title",
"indexFilterable": true,
"indexSearchable": true,
"moduleConfig": {
"text2vec-contextionary": {
"skip": false,
"vectorizePropertyName": true
}
}
},
{
"dataType": [
"text"
],
"description": "The content of the article",
"name": "content",
"indexFilterable": true,
"indexSearchable": true,
"moduleConfig": {
"text2vec-contextionary": {
"skip": false,
"vectorizePropertyName": true
}
}
}
],
"shardingConfig": {
"virtualPerPhysical": 128,
"desiredCount": 1,
"desiredVirtualCount": 128,
},
"invertedIndexConfig": {
"stopwords": {
"preset": "en",
"additions": ["star", "nebula"],
"removals": ["a", "the"]
},
"indexTimestamps": true
},
"replicationConfig": {
"factor": 3
}
}' \
http://localhost:8080/v1/schema
Get a single collection from the schema
Retrieves the configuration of a single collection in the schema.
Method and URL
GET /v1/schema/{collection_name}
Example request
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Go
- Java
- Curl
import weaviate
client = weaviate.connect_to_local()
try:
articles = client.collections.get("Article")
articles_config = articles.config.get(simple=False)
print(articles_config)
finally:
client.close()
import weaviate
client = weaviate.Client("http://localhost:8080")
schema = client.schema.get("Article")
print(schema)
import weaviate from 'weaviate-ts-client';
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
const response = await client
.schema
.classGetter()
.withClassName('Article')
.do();
console.log(JSON.stringify(response, null, 2));
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)
}
schema, err := client.Schema().ClassGetter().WithClassName("Article").Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", schema)
}
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.Schema;
public class App {
public static void main(String[] args) {
Config config = new Config("http", "localhost:8080");
WeaviateClient client = new WeaviateClient(config);
Result<Schema> result = client.schema().classGetter().withClassName("Article").run();
if (result.hasErrors()) {
System.out.println(result.getError());
return;
}
System.out.println(result.getResult());
}
}
curl http://localhost:8080/v1/schema/Article
Delete a collection
Remove a collection (and all its data objects).
Method and URL
DELETE v1/schema/{collection_name}
URL parameters
Name | Location | Type | Description |
---|---|---|---|
{collection_name} | path | string | The name of the collection |
Example request for deleting a collection
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Go
- Java
- Curl
import weaviate
client = weaviate.connect_to_local()
try:
client.collections.delete("Article")
finally:
client.close()
import weaviate
client = weaviate.Client("http://localhost:8080")
client.schema.delete_class("Article")
import weaviate from 'weaviate-ts-client';
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
await client.schema
.classDeleter()
.withClassName('Article')
.do();
package main
import (
"context"
"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)
}
err := client.Schema().ClassDeleter().
WithClassName("Article").
Do(context.Background())
if err != nil {
panic(err)
}
}
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 -X DELETE http://localhost:8080/v1/schema/Article
Update a collection
Update settings of an existing collection. Use this endpoint to alter an existing collection in the schema.
- Please note that not all settings are mutable.
- To update any other (i.e. immutable) setting, you need to delete the collection, re-create it with the correct setting and then re-import the data.
The list of mutable settings
description
invertedIndexConfig
bm25
b
k1
cleanupIntervalSeconds
stopwords
additions
preset
removals
replicationConfig
factor
vectorIndexConfig
dynamicEfFactor
dynamicEfMin
dynamicEfMax
flatSearchCutoff
skip
vectorCacheMaxObjects
pq
bitCompression
centroids
enabled
segments
trainingLimit
encoder
type
distribution
This endpoint cannot be used to introduce additional properties. For this, use POST /v1/schema/{collection_name}/properties
. A typical use case for this endpoint is to update configuration, such as vectorIndexConfig/dynamicEfFactor
or vectorIndexConfig/pq/bitCompression
. Note that even in mutable sections, such as vectorIndexConfig
, some fields may be immutable.
You should attach a body to this PUT request with the entire new configuration of the collection.
Method and URL
PUT v1/schema/{collection_name}
Parameters
The URL must contain the following parameter:
Name | Location | Type | Description |
---|---|---|---|
{collection_name} | path | string | The name of the collection |
Parameters in the PUT body:
Name | Location | Type | Description |
---|---|---|---|
class | body | string | The name of the collection (a.k.a. class). Multiple words should be concatenated in CamelCase, e.g. ArticleAuthor . |
description | body | string | Description of the collection. |
vectorIndexConfig | body | object | Vector index type specific settings. See the vector index configuration page for more details. |
invertedIndexConfig > bm25 > b | body | float | b parameter for BM25 searches. Default: 0.75 |
invertedIndexConfig > bm25 > k1 | body | float | k1 parameter for BM25 searches. Default: 1.2 |
invertedIndexConfig > stopwords | body | object | Configure stopword behavior. See more details here. |
replicationConfig > factor | body | int | The replication factor, aka the number of copies in a replicated Weaviate setup. |
Example request for updating a collection
- Python (v4)
- Python (v3)
- Curl
import weaviate
client = weaviate.connect_to_local()
try:
# Retrieve the collection
articles = client.collections.get("Article")
# Update the collection
articles.config.update(
description="An updated collection description.",
inverted_index_config=wvc.config.Reconfigure.inverted_index(
bm25_k1=1.1,
bm25_b=0.8
),
vector_index_config=wvc.config.Reconfigure.VectorIndex.hnsw(
dynamic_ef_factor=10
)
)
# Coming soon :)
finally:
client.close()
import weaviate
client = weaviate.Client("http://localhost:8080")
class_obj = {
"class": "Article", # immutable - must be kept the same, or omitted
"description": "A written text, for example a news article or blog post",
"invertedIndexConfig": {
"bm25": {
"b": 0.8,
"k1": 1.1
}
},
"vectorIndexConfig": {
"dynamicEfFactor": 10
}
}
client.schema.update_config("Article", class_obj)
curl \
-X PUT \
-H "Content-Type: application/json" \
-d '{
"class": "Article",
"description": "A written text, for example a news article or blog post",
"invertedIndexConfig": {
"bm25": {
"b": 0.8,
"k1": 1.1
}
},
"vectorIndexConfig": {
"dynamicEfFactor": 10
}
}' \
http://localhost:8080/v1/schema/Article
Add a property
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.
Method and URL
POST v1/schema/{collection_name}/properties
Parameters
Name | Location | Type | Description |
---|---|---|---|
dataType | body | array | An available data type. |
description | body | string | Description of the property. |
moduleConfig > <module_name> > skip | body | boolean | If true, the whole property will NOT be included in vectorization. Default is false, meaning that the object will be NOT be skipped. |
moduleConfig > <module_name> > vectorizePropertyName | body | boolean | Whether the name of the property is used in the calculation for the vector position of data objects. Default is true. Learn more about how to configure indexing in Weaviate. |
name | body | string | The name of the property. Multiple words should be concatenated in camelCase like nameOfAuthor . |
indexFilterable (available from v1.19 ) | body | boolean | Should the data stored in this property be indexed with the filterable, Roaring Bitmap index? Read more about indexing in Weaviate. |
indexSearchable (available from v1.19 ) | body | boolean | Should the data stored in this property be indexed to allow BM25/hybrid-search index? Read more about indexing in Weaviate. |
indexInverted (deprecated) | body | boolean | Should the data stored in this property be indexed? Learn more about indexing in Weaviate. |
Example request for adding a property
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Go
- Java
- Curl
import weaviate
client = weaviate.connect_to_local()
try:
articles = client.collections.get("Article")
articles.config.add_property(
wvc.config.Property(
name="onHomepage",
data_type=wvc.config.DataType.BOOL
)
)
finally:
client.close()
import weaviate
client = weaviate.Client("http://localhost:8080")
add_prop = {
"dataType": [
"boolean"
],
"name": "onHomepage"
}
client.schema.property.create("Article", add_prop)
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));
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)
}
}
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());
}
}
curl \
-X POST \
-H "Content-Type: application/json" \
-d '{
"dataType": [
"boolean"
],
"name": "onHomepage"
}' \
http://localhost:8080/v1/schema/Article/properties
Inspect the shards of a collection
As described in Architecture > Storage, creation of a collection leads to creating an index which manages all the disk storage and vector indexing. An index itself can be comprised of multiple shards. If a collection index is used on multiple nodes of a multi-node Weaviate cluster there must be at least one shard per node.
You can view a list of all shards for a particular collection:
Method and URL
This API was added in v1.12.0
.
GET v1/schema/{collection_name}/shards
Parameters
Name | Location | Type | Description |
---|---|---|---|
{collection_name} | URL path | string | The name of the collection |
Example request viewing shards of a collection
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Go
- Java
- Curl
import weaviate
client = weaviate.connect_to_local()
try:
articles = client.collections.get("Article")
article_shards = articles.config.get_shards()
print(article_shards)
finally:
client.close()
import weaviate
client = weaviate.Client("http://localhost:8080")
article_shards = client.schema.get_class_shards("Article")
print(article_shards)
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));
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)
}
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());
}
}
curl http://localhost:8080/v1/schema/Article/shards
Update shard status
A shard may have been marked as read-only, for example because the disk was full. You can manually set a shard to READY
again using the following API. There is also a convenience function in each client to set the status of all shards of a collection.
Method and URL
This API was added in v1.12.0
PUT v1/schema/{collection_name}/shards/{shard_name}
Parameters
Name | Location | Type | Description |
---|---|---|---|
{collection_name} | URL path | string | The name of the collection. |
{shard_name} | URL path | string | The name/id of the shard. |
status | body | string | The status to update the shard to. One of READONLY , READY . |
Example requests to update the status of a shard
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Go
- Java
- Curl
import weaviate
client = weaviate.connect_to_local()
try:
# Coming soon :)
finally:
client.close()
import weaviate
client = weaviate.Client("http://localhost:8080")
# Update a shard
client.schema.update_class_shard(
class_name="Article",
status="READONLY",
shard_name="shard-1234",
)
# Convenience method to update all shards in a class
client.schema.update_class_shard(
class_name="Article",
status="READONLY",
)
import weaviate from 'weaviate-ts-client';
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
// Update a shard
await client.schema
.shardUpdater()
.withClassName('Article')
.withShardName('shard-1234')
.withStatus('READONLY')
.do();
// Convenience method to update all shards in a class
await client.schema
.shardsUpdater()
.withClassName('Article')
.withStatus('READONLY')
.do();
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)
}
// Update a shard
status, err := client.Schema().
ShardUpdater().
WithClassName("Article").
WithShardName("shard-1234").
WithStatus("READONLY").
Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", status)
// Convenience method to update all shards in a class
shards, err := client.Schema().
ShardsUpdater().
WithClassName("Article").
WithStatus("READY").
Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", shards)
}
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.ShardStatus;
import io.weaviate.client.v1.schema.model.ShardStatuses;
public class App {
public static void main(String[] args) {
Config config = new Config("http", "localhost:8080");
WeaviateClient client = new WeaviateClient(config);
// Update a shard
Result<ShardStatus> updateShard = client.schema()
.shardUpdater()
.withClassName("Article")
.withShardName("shard-1234")
.withStatus(ShardStatuses.READONLY)
.run();
if (updateShard.hasErrors()) {
System.out.println(updateShard.getError());
return;
}
System.out.println(updateShard.getResult());
// Convenience method to update all shards in a class
Result<ShardStatus[]> updateShards = client.schema()
.shardsUpdater()
.withClassName("Article")
.withStatus(ShardStatuses.READY)
.run();
if (updateShards.hasErrors()) {
System.out.println(updateShards.getError());
return;
}
System.out.println(updateShards.getResult());
}
}
curl \
-X PUT \
-H "Content-Type: application/json" \
-d '{
"status": "READONLY"
}' \
http://localhost:8080/v1/schema/Article/shards/shard-1234
Multi-tenancy
- Multi-tenancy available from version
v1.20
- (Experimental) Tenant activity status setting available from version
v1.21
Tenants are used to separate data between different users or groups of users. They can be specified as follows:
Enable multi-tenancy
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Java
- Go
import weaviate.classes as wvc
multi_collection = client.collections.create(
name="MultiTenancyCollection",
# Enable multi-tenancy on the new collection
multi_tenancy_config=wvc.config.Configure.multi_tenancy(True)
)
client.schema.create_class({
"class": "MultiTenancyCollection",
"multiTenancyConfig": {"enabled": True}
})
await client.schema
.classCreator().withClass({
class: 'MultiTenancyCollection',
multiTenancyConfig: { enabled: true },
})
.do();
WeaviateClass multiTenancyCollection = WeaviateClass.builder()
.className("MultiTenancyCollection")
.multiTenancyConfig(MultiTenancyConfig.builder().enabled(true).build())
.build();
client.schema().classCreator()
.withClass(multiTenancyCollection)
.run();
client.Schema().ClassCreator().
WithClass(&models.Class{
Class: "MultiTenancyCollection",
MultiTenancyConfig: &models.MultiTenancyConfig{
Enabled: true,
},
}).
Do(ctx)
Add tenant(s)
Pass a payload with an array of tenant objects. The available fields are:
Name | Type | Description |
---|---|---|
name | string | (Required) The name of the tenant. |
activityStatus | string | (Optional, experimental) The activity status of the tenant. Can be HOT (default) or COLD . |
Example payload
[
{
"name": "TENANT_A"
},
{
"name": "TENANT_B",
"activityStatus": "COLD"
}
]
A tenant name can only contain alphanumeric characters (a-z, A-Z, 0-9), underscore (_), and hyphen (-), with a length of 4 to 64 characters.
POST v1/schema/{collection_name}/tenants
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Java
- Go
import weaviate.classes as wvc
# Add two tenants to the collection
multi_collection.tenants.create(
tenants=[
wvc.tenants.Tenant(name="tenantA"),
wvc.tenants.Tenant(name="tenantB"),
]
)
from weaviate import Tenant
client.schema.add_class_tenants(
class_name="MultiTenancyCollection", # The class to which the tenants will be added
tenants=[Tenant(name="tenantA"), Tenant(name="tenantB")]
)
let tenants = await client.schema
.tenantsCreator(
'MultiTenancyCollection',
[{ name: 'tenantA' }, { name: 'tenantB' }]
)
.do();
client.schema().tenantsCreator()
.withClassName("MultiTenancyCollection")
.withTenants(
Tenant.builder().name("tenantA").build(),
Tenant.builder().name("tenantB").build()
)
.run();
client.Schema().TenantsCreator().
WithClassName("MultiTenancyCollection").
WithTenants(models.Tenant{Name: "tenantA"}, models.Tenant{Name: "tenantB"}).
Do(ctx)
List tenants
GET v1/schema/{collection_name}/tenants
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Java
- Go
multi_collection = client.collections.get("MultiTenancyCollection")
tenants = multi_collection.tenants.get()
print(tenants)
tenants = client.schema.get_class_tenants(
class_name="MultiTenancyCollection" # The class from which the tenants will be retrieved
)
tenants = await client.schema
.tenantsGetter('MultiTenancyCollection')
.do();
client.schema().tenantsGetter()
.withClassName("MultiTenancyCollection")
.run();
tenants, err := client.Schema().TenantsGetter().
WithClassName("MultiTenancyCollection").
Do(ctx)
Remove tenants
Pass a payload with an array of tenant names in the form of ["TENANT_NAME1", "TENANT_NAME2"]
to remove from the collection.
DELETE v1/schema/{collection_name}/tenants
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Java
- Go
multi_collection = client.collections.get("MultiTenancyCollection")
# Remove a list of tenants - tenantX will be ignored.
multi_collection.tenants.remove(["tenantB", "tenantX"])
client.schema.remove_class_tenants(
class_name="MultiTenancyCollection", # The class from which the tenants will be removed
tenants=["tenantB", "tenantX"] # The tenants to be removed. tenantX will be ignored.
)
await client.schema
.tenantsDeleter('MultiTenancyCollection', ['tenantB', 'tenantX']) // tenantX will be ignored
.do();
client.schema().tenantsDeleter()
.withClassName("MultiTenancyCollection")
.withTenants("tenantB", "tenantX") // tenantX will be ignored
.run();
client.Schema().TenantsDeleter().
WithClassName("MultiTenancyCollection").
WithTenants("tenantB", "tenantX"). // tenantX will be ignored
Do(ctx)
Update tenants
PUT v1/schema/{collection_name}/tenants
Pass a payload with an array of tenant objects. For updating tenants, both name
and activityStatus
are required.
Example payload
[
{
"name": "TENANT_A",
"activityStatus": "COLD"
},
{
"name": "TENANT_B",
"activityStatus": "HOT"
}
]
- Python (v4)
multi_collection = client.collections.get("MultiTenancyCollection")
multi_collection.tenants.update(tenants=[
wvc.tenants.Tenant(
name="tenantA",
activity_status=weaviate.schema.TenantActivityStatus.COLD
)
])