Table of documentation contents

Adding and Modifying Data Guide

When a Weaviate schema is created, you can populate this Weaviate with data.

Index

Basics

  • Data is added through the RESTful API.
  • Individual semantic kinds can be collected or listed. However, there are seperate documentation pages for querying and exploring.
  • The examples assume that Weaviate runs on port 80 on the localhost without authentication.
  • The entry point to a Weaviate is always /v1.

Introduction

Adding data to Weaviate is very similar to filling traditional graph databases with data. The two differentiating factors within Weaviate are:

  1. The ability to make direct and indirect references to nodes in the graph.
  2. Realtime semantic indexing in the Contextionary.

Data Object

A data object syntax is defined as follows:

{
  "class": "string", // as defined during schema creation
  "id": "{UUID}", // optional, should be in UUID format.
  "schema": {
    "property": "defined as datatypes", // defined as datatypes # as defined during schema creation
  }
}

Add a data object

A concept data object can be added to a Weaviate via the following endpoint:

$ curl http://localhost:8080/v1/{semanticKind} -X POST -H '{contentType}' -d '{data}'

Example of adding a Thing:

$ curl http://localhost:8080/v1/things -X POST -H 'Content-type: application/json' -d \
'{
  "class": "Company",
  "id": "f81bfe5e-16ba-4615-a516-46c2ae2e5a80",
  "schema": {
    "name": "Apple"
  }
}'

Example of adding an Action, with a direct reference:

$ curl http://localhost:8080/v1/actions -X POST -H 'Content-type: application/json' -d \
'{
  "class": "Payment",
  "id": "22cc3380-ef73-48f8-9e3c-c603fae0f4b0",
  "schema": {
    "date": "2019-03-24T14:25:57Z",
    "toCompany": [
      {
        "beacon": "weaviate://localhost/things/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
      }
    ]
  }
}'
  • Note, it is assumed that the CREF f81bfe5e-16ba-4615-a516-46c2ae2e5a80 exsists

Update a data object

A concept data object can be updated inside a Weaviate via the following endpoint:

$ curl http://localhost:8080/v1/{semanticKind}/{semanticKindUUID} -X PUT -H '{contentType}' -d '{data}'
  • {semanticKind} = things or actions (more info).
  • {semanticKindUUID} = the UUID that points to a concept.
  • {contentType} = JSON or YAML.
  • {data} = data object.

Example of updating a Thing.

$ curl http://localhost:8080/v1/things/f81bfe5e-16ba-4615-a516-46c2ae2e5a80 -X PUT -H 'Content-type: application/json' -d 
'{
  "class": "Company",
  "schema": {
    "name": "Apple Inc."
  },
  "id": "f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
}'

Get a data object

A concept data object can be retrieved from a Weaviate directly via the following endpoint:

$ curl http://localhost:8080/v1/{semanticKind}/{semanticKindUUID}
  • {semanticKind} = things or actions (more info).
  • {semanticKindUUID} = the UUID that points to a concept.

Example of requesting a thing.

$ curl http://localhost:8080/v1/things/f81bfe5e-16ba-4615-a516-46c2ae2e5a80
  • Note, the result will be in the form of a data object.
  • Note, this endpoint is created the collect individual concepts directly, there are specific endpoints for querying and exploring.

Delete a data object

A concept data object can be deleted from a Weaviate directly via the following endpoint;

$ curl http://localhost:8080/v1/{semanticKind}/{semanticKindUUID} -X DELETE
  • {semanticKind} = things or actions (more info).
  • {semanticKindUUID} = the UUID that points to a concept.

Example of deleting a thing.

$ curl http://localhost:8080/v1/things/f81bfe5e-16ba-4615-a516-46c2ae2e5a80 -X DELETE

References guide

Weaviate has two types of references:

  1. Direct references which are references to nodes in the graph (like a traditional graph-DB).
  2. Indirect references are references that are semantically similar to each other. (coming soon)

Direct References

A direct reference connects a concept directly to another concept. The use case for this type of reference is that you want to want to make 100% sure that you make a correct reference. A Company to a hasCEO might be an example.

Direct references are always set like this:

{
  "class": "Company",
  "schema": {
    "name": "Apple",
    "hasCeo": {
      "beacon": "weaviate://localhost/things/{concept ID}"
    }
  }
}
  • Note: for more information about setting references, see the documentation below.
  • Note: click here for more information about CREF location definitions

Indirect References (coming soon)

Indirect references tap into the natural language processing part of Weaviate. You can set a reference to something that is close enough for Weaviate to recognize it. The use case here is that if you have multiple data entries that describe the same thing, it will help Weaviate recognize the entry and make the relations for you.

Concider the following two entries that might be in you database:

{
  "Company": {
    "name": "Apple",
    "hasCeo": {
      "name": "Tim Cook"
    }
  }
}

and

{
  "Person": {
    "name": "Timmothy Cook"
  }
}

Although the references are not identical, this is enough for Weaviate to conncet the two data items to eachother when searching.

Indirect references are always set like this:

{
  "class": "Company",
  "schema": {
    "name": "Apple",
    "hasCeo": {
      "Person": {
        "name": "Tim Cook"
      }
    }
  }
}

Note: for more information about setting references, see the documentation below.

Cross Reference Location (URL)

Weaviate uses it’s own transportaion schema. A URL is always defined in the same way:

schemalocationconceptUUID
weaviate://localhost or peername/ things or actions/ UUID

For example:

weaviate://localhost/things/f81bfe5e-16ba-4615-a516-46c2ae2e5a80

Add individual references

Requests can be done to individual references if the cardinality of this property is set to many. If the cardinality is set to atMostOne, then this REST endpoint cannot be used for individual reference manipulations.

An individual reference can be added to a concept data object as follows:

$ curl http://localhost:8080/v1/{semanticKind}/{semanticKindUUID}/references/{propertyName} -X POST -H '{contentType}' -d '{data}'
  • {semanticKind} = things or actions (more info).
  • {semanticKindUUID} = the UUID that points to a concept.
  • {propertyName} = the name of the property related to this class.
  • {contentType} = JSON or YAML.
  • {data} = direct or indirect reference.

Example of adding a direct reference:

$ curl http://localhost:8080/v1/actions/f81bfe5e-16ba-4615-a516-46c2ae2e5a80/references/toCompany -X POST -H 'Content-type: application/json' -d 'beacon: weaviate://localhost/things/22cc3380-ef73-48f8-9e3c-c609bae0b4b0'

Example of adding an indirect reference (coming soon):

$ curl http://localhost:8080/v1/things/f81bfe5e-16ba-4615-a516-46c2ae2e5a80/references/hasCeo -X POST -H 'Content-type: application/json' -d \
'{
  "name": "Steve Jobs",
  "bornIn": {
    "beacon": "weaviate://localhost/things/lo9...b2c"
  }
}'

Replace all references

All references related to a property can be updated as follows:

$ curl http://localhost:8080/v1/{semanticKind}/{semanticKindUUID}/references/{propertyName} -X PUT -H '{contentType}' -d '{data}'
  • {semanticKind} = things or actions (more info).
  • {semanticKindUUID} = the UUID that points to a concept.
  • {propertyName} = the name of the property related to this class.
  • {contentType} = JSON or YAML.
  • {data} = array of direct or indirect reference.

Example of replacing a direct reference:

$ curl http://localhost:8080/v1/things/f81bfe5e-16ba-4615-a516-46c2ae2e5a80/references/hasCustomers -X POST -H 'Content-type: application/json' -d \
'[
  {
    "beacon": "weaviate://localhost/things/lo9...b2c"
  },
  {
    "beacon": "weaviate://localhost/things/kjd...d8s"
  }
]'

Delete individual references

You can delete a single reference that is given in the body from the list of references that this property has.

$ curl http://localhost:8080/v1/{semanticKind}/{semanticKindUUID}/references/{propertyName} -X DELETE -H '{contentType}' -d '{data}'

Batching

A bulk of objects can be added to Weaviate by using a batch POST. A seperate request should be done for the semantic kinds (Things or Actions).

$ curl http://localhost:8080/v1/batching/things -X POST -H 'Content-type: application/json' -d \
'{
  "fields": [
    "ALL"
  ],
  "things": [
    {
      "class": "Company",
      "schema": {
        "name": "Apple Inc."
      },
      "id": "0a85f1db-fbf3-4343-b45b-25c794c5419d"
    },
    {
      "class": "Company",
      "schema": {
        "name": "Google LLC"
      },
      "id": "b0c18f80-d7c1-44bf-a745-14b9df5b1055"
    }
  ]
}'

Frequently Asked Questions

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.
Tags
  • Add
  • Data
  • Modify