Table of documentation contents

Python Client Library Guide



  • A python native weaviate client makes using the Weaviate API easier.
  • An overview of all functions can be found here.


The package can be easily installed using pip. The client is developed and tested for python 2.7 and 3.7.

pip install weaviate-client

Create schema

First make sure that weaviate is running. See the installation guide on how to start weaviate.

Before we can load data we need to create a client and load a schema. You can learn how to create a schema here.

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

A schema can be provided as a URL, file or a dict.

Create Things or Actions

Things can be created like this:

client.create({"name": "John von Neumann"}, "Person", "b36268d4-a6b5-5274-985f-45f13ce0c642")
client.create({"name": "Alan Turing"}, "Person", "1c9cd584-88fe-5010-83d0-017cb3fcb446")
client.create({"name": "Legends"}, "Group", "2db436b5-0557-5016-9c5f-531412adf9c6")

Actions can be created in a similar fashion like this:

client.create({"description": "John von Neumann's book"}, "Buy", semantic_type=weaviate.SEMANTIC_TYPE_ACTIONS)

You can add cross-references through:

client.add_reference("2db436b5-0557-5016-9c5f-531412adf9c6", "members", "b36268d4-a6b5-5274-985f-45f13ce0c642")
client.add_reference("2db436b5-0557-5016-9c5f-531412adf9c6", "members", "1c9cd584-88fe-5010-83d0-017cb3fcb446")
# From action to thing
client.add_reference("2db436b5-0557-5016-9c5f-531412adf9c6", "members", "1c9cd584-88fe-5010-83d0-017cb3fcb446", 
                     from_semantic_type=SEMANTIC_TYPE_ACTIONS, to_semantic_type=SEMANTIC_TYPE_THINGS)

Note: Weaviate might need a short time to update its index after a new thing has been created.

Look at the data using the simple query on the GraphQL endpoint:

curl http://localhost/v1/graphql -X POST -H 'Content-type: application/json' -d '
  Get {
    Things {
      Group {
        Members {
          ... on Person {


You can also execute batch requests which allows you to add large sets of data in one API call.

You can batch load things or actions as follows

i = 1

# create a ThingsBatchRequest for adding things
batch = weaviate.ThingsBatchRequest()

# create a ReferenceBatchRequest for adding references
batchRefs = weaviate.ReferenceBatchRequest()

for author, publication in authors.items():

    # empty author object
    authorObj = {}

    # author obj
    authorObj = {
        'name': author,
        'writesFor': [
                'beacon': 'weaviate://localhost/things/' + publication

    # add every 1000 by taking the modus of 999 (counter starts at 0)
    if (i % 999) == 0:
        # Send the batch to Weaviate
        # Create an empty batch
        batch = weaviate.ThingsBatchRequest()
        # Send the ref batch to Weaviate
        # Create an empty ref batch
        batchRefs = weaviate.ReferenceBatchRequest()

    # Add the thing to the batch request queue
    batch.add_thing(authorObj, 'Author', str(uuid.uuid3(uuid.NAMESPACE_DNS, author)))
    # Add a reference to the batch request queue
    batchRefs.add_reference("Publication", obj['publicationId'], "hasArticles", articleId)    
    i += 1

# Send the batch to Weaviate

# Create an empty ref batch


A weaviate instance that uses authentication can also be accessed using the client. Simply create an authentication secret and pass it to the client.

import weaviate

auth = weaviate.AuthClientPassword(<user>, <password>)
client = weaviate.Client(<weaviate URL>, auth)

Currently the floowing grand types are currently supported:

  • password
    weaviate.AuthClientPassword(<user>, <password>)
  • client credentials


The client allows to send simple GraphQL queries in the form of strings. Lets create a simple class Person and some add some people.

import weaviate

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

schema = {
    "actions": {"classes": [],"type": "action"},
    "things": {"classes": [{
        "class": "Person",
        "description": "A person such as humans or personality known through culture",
        "properties": [
                "cardinality": "atMostOne",
                "dataType": ["text"],
                "description": "The name of this person",
                "name": "name"
        "type": "thing"

w.create_thing({"name": "Andrew S. Tanenbaum"}, "Person")
w.create_thing({"name": "Alan Turing"}, "Person")
w.create_thing({"name": "John von Neumann"}, "Person")
w.create_thing({"name": "Tim Berners-Lee"}, "Person")

Now we define a query for all Person objects.

query = """
  Get {
    Things {
      Person {

Finally we can run the query unsing the clients query function.

import json

query_result = w.query(query)
# Pretty print the result of the query
print(json.dumps(query_result, indent=4, sort_keys=True))

When creating new things it can take up to 2 seconds until weaviate has indexed the newley added data. Therefore the query might not return all the previously added things during that time frame.

To create complex GraphQL query please consider a GraphQL python client. Be cautios of query injections when generating string based queries.

Please find the full client documentation here.

More Resources

If you can’t find the answer to your question here, please use the:

  1. Knowledge base of old issues. Or,
  2. For questions: Stackoverflow. Or,
  3. For issues: Github.
  4. For Frequently Asked Questions.
  • Python
  • Library