/v1/schema

Weaviate on Stackoverflow badge Weaviate issues on Github badge Weaviate v1.13.2 version badge Weaviate v1.13.2 version badge Weaviate total Docker pulls badge

Before adding data to Weaviate, you need to create a schema. The schema contains the structure of your Weaviate in graph format. You will use the graph format to search through your Weaviate instance using GraphQL. To learn how to create a schema, you can follow this How-To tutorial.

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)

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client
  .schema
  .getter()
  .do()
  .then(res => {
    console.log(res);
  })
  .catch(err => {
    console.error(err)
  });

  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  schema, err := client.Schema().Getter().Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", schema)
}

  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.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": [
            "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.

namelocationtypedescription
classbodystringThe name of the class, multiple words should be concatenated in CamelCase like ArticleAuthor.
descriptionbodystringDescription of the classname
vectorIndexTypebodystringdefaults to hnsw, can be omitted in schema definition since this is the only available type for now
vectorIndexConfigbodyobjectvector index type specific settings
vectorizerbodystringvectorizer to use for data objects added to this class, default can be set in Weaviate’s environment variables
moduleConfig > text2vec-contextionary > vectorizeClassNamebodyobjectinclude the class name in vector calculation (default true). Learn more about how to regulate indexing in Weaviate here.
propertiesbodyarrayAn array of property objects
properties > dataTypebodyarrayClick here for a list of available data types.
properties > descriptionbodystringDescription of the property
properties > moduleConfig > text2vec-contextionary > skipbodybooleanif true, the whole property will NOT be included in vectorization. default is false, meaning that the object will be NOT be skipped
properties > moduleConfig > text2vec-contextionary > vectorizePropertyNamebodybooleanwhether name of the property is used in the calculation for the vector position of data objects. default is true. Learn more about how to regulate indexing in Weaviate here.
properties > namebodystringThe name of the property, multiple words should be concatenated in camelCase like nameOfAuthor.
properties > indexInvertedbodybooleanShould the the data stored in this property be indexed? Learn more about how to regulate indexing in Weaviate here.
properties > tokenizationbodystringOnly 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". See more details here.
invertedIndexConfig > stopwordsbodyobjectConfigure which words should be treated as stopwords and therefore be ignored on inverted indexing and querying. See more details here.
invertedIndexConfig > indexTimestampsbodybooleanMaintain an inverted index for each object by its internal timestamps, currently including creationTimeUnix and lastUpdateTimeUnix See more details here.

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)

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

var classObj = {
    "class": "Article",
    "description": "A written text, for example a news article or blog post",
    "vectorizeClassName": true,
    "properties": [
        {
        "dataType": [
            "string"
        ],
        "description": "Title of the article",
        "name": "title",
        "vectorizePropertyName": true,
        "index": true
        },
        {
        "dataType": [
            "text"
        ],
        "description": "The content of the article",
        "name": "content"
        }
    ]
}

client
  .schema
  .classCreator()
  .withClass(classObj)
  .do()
  .then(res => {
    console.log(res)
  })
  .catch(err => {
    console.error(err)
  });

  package main

import (
    "context"

    "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
    "github.com/semi-technologies/weaviate/entities/models"
)

func main() {
    cfg := weaviate.Config{
        Host:   "localhost:8080",
        Scheme: "http",
    }
    client := weaviate.New(cfg)

    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 technology.semi.weaviate;

import java.util.ArrayList;
import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.schema.model.DataType;
import technology.semi.weaviate.client.v1.schema.model.Property;
import technology.semi.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 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": {
        "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
    }
}

client.schema.create_class(class_obj)

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

var classObj = {
    "class": "Article",
    "description": "A written text, for example a news article or blog post",
    "vectorIndexType": "hnsw",
    "vectorIndexConfig": {
        "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
    }
}

client
  .schema
  .classCreator()
  .withClass(classObj)
  .do()
  .then(res => {
    console.log(res)
  })
  .catch(err => {
    console.error(err)
  });

  package main

import (
  "context"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate/entities/models"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  classObj := &models.Class{
    Class:           "Article",
    Description:     "A written text, for example a news article or blog post",
    VectorIndexType: "hnsw",
    Vectorizer:      "text2vec-contextionary",
    Properties: []*models.Property{
      {
        DataType:    []string{"string"},
        Description: "Title of the article",
        Name:        "title",
      },
      {
        DataType:    []string{"text"},
        Description: "The content of the article",
        Name:        "content",
      },
    },
    InvertedIndexConfig: &models.InvertedIndexConfig{
      Stopwords: &models.StopwordConfig{
        Preset:    "en",
        Additions: []string{"star", "nebula"},
        Removals:  []string{"a", "the"},
      },
      IndexTimestamps: true,
    },
  }

  err := client.Schema().ClassCreator().WithClass(classObj).Do(context.Background())
  if err != nil {
    panic(err)
  }
}

  package technology.semi.weaviate;

import java.util.ArrayList;
import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.misc.model.InvertedIndexConfig;
import technology.semi.weaviate.client.v1.misc.model.ShardingConfig;
import technology.semi.weaviate.client.v1.misc.model.StopwordConfig;
import technology.semi.weaviate.client.v1.misc.model.VectorIndexConfig;
import technology.semi.weaviate.client.v1.schema.model.DataType;
import technology.semi.weaviate.client.v1.schema.model.Property;
import technology.semi.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);

    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()
      .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)
      .function("murmur3")
      .key("_id")
      .strategy("hash")
      .virtualPerPhysical(128)
      .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)
      .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",
    "vectorIndexType": "hnsw",
    "vectorIndexConfig": {
        "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": true
                }
              }
        },
        {
            "dataType": [
                "text"
            ],
            "description": "The content of the article",
            "name": "content",
            "indexInverted": true,
            "moduleConfig": {
                "text2vec-contextionary": {
                  "skip": false,                   
                  "vectorizePropertyName": true
                }
              }
        }
    ],
    "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
    }
}' \
http://localhost:8080/v1/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

namelocationtypedescription
{class_name}URLstringThe name of the class

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

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

var className = 'Article';

client.schema
  .classDeleter()
  .withClassName(className)
  .do()
  .then(res => {
    console.log(res);
  })
  .catch(err => {
    console.error(err)
  });

  package main

import (
  "context"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  err := client.Schema().ClassDeleter().
    WithClassName("Article").
    Do(context.Background())

  if err != nil {
    panic(err)
  }
}

  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.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

Add a property

Method and URL

POST v1/schema/{class_name}/properties

Parameters

namelocationtypedescription
dataTypebodyarrayClick here for a list of available data types.
descriptionbodystringDescription of the property
moduleConfig > text2vec-contextionary > skipbodybooleanif true, the whole property will NOT be included in vectorization. default is false, meaning that the object will be NOT be skipped
moduleConfig > text2vec-contextionary > vectorizePropertyNamebodybooleanwhether name of the property is used in the calculation for the vector position of data objects. default is true. Learn more about how to regulate indexing in Weaviate here.
namebodystringThe name of the property, multiple words should be concatenated in camelCase like nameOfAuthor.
indexInvertedbodybooleanShould the the data stored in this property be indexed? Learn more about how to regulate indexing in Weaviate here.

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)

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

const className = 'Article';
const prop = {
  dataType: ['boolean'],
  name: 'onHomepage',
};

client.schema
      .propertyCreator()
      .withClassName(className)
      .withProperty(prop)
      .do()
      .then(res => {
    console.log(res);
  })
  .catch(err => {
    console.error(err)
  });

  package main

import (
  "context"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate/entities/models"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  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 technology.semi.weaviate;

import java.util.Arrays;
import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.schema.model.DataType;
import technology.semi.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 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

namelocationtypedescription
{class_name}URLstringThe name of the class

Example request viewing shards of a class

  import weaviate

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

client.schema.get_class_shards('Article')

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.schema
  .shardsGetter()
  .withClassName("Article")
  .do()

  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)
  shards, err := client.Schema().
    ShardsGetter().
    WithClassName("Article").
    Do(context.Background())
  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", shards)
}

  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.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 class.

Method and URL

Note: This API was added in v1.12.0

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

Parameters

namelocationtypedescription
{class_name}URLstringThe name of the class
{shard_name}URLstringThe name/id of the shard
statusbodystringThe status to update the shard to. One of READONLY, READY

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

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

// Update a shard
client.schema
  .shardUpdater()
  .withClassName("Article")
  .withShardName("shard-1234")
  .withStatus("READONLY")
  .do()

// Convenience method to update all shards in a class
client.schema
  .shardsUpdater()
  .withClassName("Article")
  .withStatus("READONLY")
  .do()

  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }

  client := weaviate.New(cfg)

  // 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 technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.schema.model.ShardStatus;
import technology.semi.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 POST \
    -H "Content-Type: application/json" \
    -d '{
         "status": "READONLY"
        }' \
    http://localhost:8080/v1/schema/Article/shards/shard-1234

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.

Edit on Github

Table of Contents