Skip to main content

REST - /v1/schema

LICENSE Weaviate on Stackoverflow badge Weaviate issues on Github badge Weaviate version badge Weaviate total Docker pulls badge Go Report Card

NOTE: From v1.5.0 onwards creating a schema is now optional, learn more about Auto Schema here.

Get the schema​

Dumps the current Weaviate schema. The result contains an array of objects.

Method and URL​

GET /v1/schema

Example request​

import weaviate

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

schema = client.schema.get()
print(schema)

Example response​

{
"classes": [
{
"class": "Category",
"description": "Category an article is a type off",
"moduleConfig": {
"text2vec-contextionary": {
"vectorizeClassName": false
}
},
"properties": [
{
"dataType": [
"string"
],
"description": "category name",
"indexInverted": 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": [
"string"
],
"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": [
"string"
],
"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": [
"string"
],
"description": "title of the article",
"indexInverted": true,
"moduleConfig": {
"text2vec-contextionary": {
"vectorizePropertyName": false
}
},
"name": "title"
},
{
"dataType": [
"string"
],
"description": "url of the article",
"indexInverted": false,
"moduleConfig": {
"text2vec-contextionary": {
"vectorizePropertyName": false
}
},
"name": "url"
},
{
"dataType": [
"text"
],
"description": "summary of the article",
"indexInverted": 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 class​

Create a new data object class in the schema.

NOTE: From v1.5.0 onwards creating a schema is now optional, learn more about Auto Schema here.

Method and URL​

POST /v1/schema

Parameters​

Learn more about the schema configuration here.

namelocationtype
classbodystring
descriptionbodystring
vectorIndexTypebodystring
vectorIndexConfigbodyobject
vectorizerbodystring
moduleConfig > text2vec-contextionary > vectorizeClassNamebodyobject
propertiesbodyarray
properties > dataTypebodyarray
properties > descriptionbodystring
properties > moduleConfig > text2vec-contextionary > skipbodyboolean
properties > moduleConfig > text2vec-contextionary > vectorizePropertyNamebodyboolean
properties > namebodystring
properties > indexInvertedbodyboolean
properties > tokenizationbodystring
invertedIndexConfig > stopwordsbodyobject
invertedIndexConfig > indexTimestampsbodyboolean
replicationConfig > factorbodyint

Example request for creating a class​

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": [
"string"
],
"description": "Title of the article",
"name": "title",
},
{
"dataType": [
"text"
],
"description": "The content of the article",
"name": "content"
}
]
}

client.schema.create_class(class_obj)

Or with all the possible parameters:

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": [
"string"
],
"description": "Title of the article",
"name": "title",
"indexInverted": True,
"moduleConfig": {
"text2vec-contextionary": {
"skip": False,
"vectorizePropertyName": False
}
}
},
{
"dataType": [
"text"
],
"description": "The content of the article",
"name": "content",
"indexInverted": True,
"moduleConfig": {
"text2vec-contextionary": {
"skip": False,
"vectorizePropertyName": False
}
}
}
],
"shardingConfig": {
"virtualPerPhysical": 128,
"desiredCount": 1,
"desiredVirtualCount": 128,
"key": "_id",
"strategy": "hash",
"function": "murmur3"
},
"invertedIndexConfig": {
"stopwords": {
"preset": "en",
"additions": ["star", "nebula"],
"removals": ["a", "the"]
},
"indexTimestamps": True
},
"replicationConfig": {
"factor": 3
}
}

client.schema.create_class(class_obj)

Get a single class from the schema​

Retrieves the configuration of a single class in the schema.

Method and URL​

GET /v1/schema/{className}

Example request​

import weaviate

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

schema = client.schema.get("Article")
print(schema)

Delete a class​

Remove a class (and all data in the instances) from the schema.

Method and URL​

DELETE v1/schema/{class_name}

Parameters​

namelocationtype
{class_name}URLstring

Example request for deleting a class​

import weaviate

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

client.schema.delete_class("Article") # deletes the class "Article" along with all data points of class "Article"
# OR
client.schema.delete_all() # deletes all classes along with the whole data

Update a class​

Update settings of an existing schema class.

Use this endpoint to alter an existing class in the schema. Note that not all settings are mutable. If an error about immutable fields is returned and you still need to update this particular setting, you will have to delete the class (and the underlying data) and recreate. This endpoint cannot be used to modify properties. Instead use POST /v1/schema/{className}/properties. A typical use case for this endpoint is to update configuration, such as the vectorIndexConfig. 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 class.

Method and URL​

PUT v1/schema/{class_name}

Parameters​

Parameter in the PUT request:

namelocationtype
{class_name}URLstring

Parameter in the PUT body:

namelocationtype
classbodystring
descriptionbodystring
vectorIndexTypebodystring
vectorIndexConfigbodyobject
vectorizerbodystring
moduleConfig > text2vec-contextionary > vectorizeClassNamebodyobject
propertiesbodyarray
properties > dataTypebodyarray
properties > descriptionbodystring
properties > moduleConfig > text2vec-contextionary > skipbodyboolean
properties > moduleConfig > text2vec-contextionary > vectorizePropertyNamebodyboolean
properties > namebodystring
properties > indexInvertedbodyboolean
properties > tokenizationbodystring
invertedIndexConfig > stopwordsbodyobject
invertedIndexConfig > indexTimestampsbodyboolean

Example request for updating a class​

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": [
"string"
],
"description": "Title of the article",
"name": "title",
},
{
"dataType": [
"text"
],
"description": "The content of the article",
"name": "content"
}
]
}

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

Add a property​

Method and URL​

POST v1/schema/{class_name}/properties

Parameters​

namelocationtype
dataTypebodyarray
descriptionbodystring
moduleConfig > text2vec-contextionary > skipbodyboolean
moduleConfig > text2vec-contextionary > vectorizePropertyNamebodyboolean
namebodystring
indexInvertedbodyboolean

Example request for adding a property​

import weaviate

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

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

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

Inspect the shards of a class​

As described in Architecture > Storage, creation of a class 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 class 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 class:

Method and URL​

Note: This API was added in v1.12.0

GET v1/schema/{class_name}/shards

Parameters​

namelocationtype
{class_name}URLstring

Example request viewing shards of a class​

import weaviate

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

client.schema.get_class_shards("Article")

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

Method and URL​

note

This API was added in v1.12.0

PUT v1/schema/{class_name}/shards/{shard_name}

Parameters​

namelocationtype
{class_name}URLstring
{shard_name}URLstring
statusbodystring

Example requests to update the status of a shard​

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

More Resources​

If you can't find the answer to your question here, please look at the:

  1. Frequently Asked Questions. Or,
  2. Knowledge base of old issues. Or,
  3. For questions: Stackoverflow. Or,
  4. For issues: Github. Or,
  5. Ask your question in the Slack channel: Slack.