Table of documentation contents

/v1/{semantic kind}

You can get, add, update, and delete individual data objects ("Things" or "Actions") to and from a Weaviate via this end-point. If you want to add multiple data objects in one request, checkout the batching endpoint. To query and search through the data checkout the GraphQL section.

List all data objects of a semantic kind

Lists all semantic kind data objects in reverse order of creation. The data will be returned as an array of schema data objects.

Method and URL

GET /v1/{semantic_kind}

Parameters

namelocationtypedescription
{semantic_kind}URLstringA semantic kind is used to -respectively- describe nouns or verbs. Options are things or actions
limitURLintegerThe maximum number of data objects to return.
includeURLstringInclude additional information, such as classification info. Allowed values include: classification, _classification, vector, _vector, interpretation, _interpretation, featureProjection, _featureProjection.

Response fields

The response of a GET query of a data object of any semantic kind will give you information about all objects (or a single object). Next to general information about the data objects, like schema information and property values, meta information will be shown depending on the include fields or _underscore properties of your request.

field namedatatyperequired include or _underscore fielddescription
classstringnonethe class name
creationTimeUnixunix timestampnonethe time stamp of creation of the data object
iduuidnonethe uuid of the data object
lastUpdateTimeUnixunix timestampnonethe time stamp when the data object was last updated
schema > {property_name}dataTypenonethe name and value of an individual property
schema > {cref_property_name} > _classification > winningDistancedataTypeclassification, _classificationThe mean distance of the winning group. It is a normalized distance (between 0 and 1), where 0 means equal and 1 would mean a perfect opposite. See for more info here.
schema > {cref_property_name} > _classification > losingDistancedataTypeclassification, _classificationThe mean distance of the losing group. It is a normalized distance (between 0 and 1), where 0 means equal and 1 would mean a perfect opposite. See for more info here.
_vectorlist of floatsvector, _vectorthe long vector of the location of the object in the 300 dimensional space
_classification > basedOnstringclassification, _classificationthe property name where the classification was based on
_classification > classifiedFieldsstringclassification, _classificationthe classified property
_classification > completedtimestampclassification, _classificationthe time of classification completion
_classification > iduuidclassification, _classificationthe classification id
_classification > scopelist of stringsclassification, _classificationthe initial fields to classify
_featureProjection > vectorlist of floatsfeatureProjection, _featureProjectionthe 2D or 3D vector coordinates of the feature projection
_interpretation > sourcelist of objectsinterpretation, _interpretationvectorization info: the concepts used to vectorize this data object
_interpretation > source > conceptstringinterpretation, _interpretationthe concept used for vectorization
_interpretation > source > occurrenceintegerinterpretation, _interpretationthe number of times this word occurs in the c11y set
_interpretation > source > weightfloatinterpretation, _interpretationthe relative importance and thus influence of this concept on the data object’s vector
_nearestNeighbors > neighborslist of objectsnearestNeighbors, _nearestNeighborslist of nearest neighbours in the semantic space
_nearestNeighbors > neighbors > conceptstringnearestNeighbors, _nearestNeighborsthe concept
_nearestNeighbors > neighbors > distancefloatnearestNeighbors, _nearestNeighborsthe distance in space between the data object and the concept
_nearestNeighbors > neighbors > vectorlist of floatsnearestNeighbors, _nearestNeighborsthe 300 dimensional vector coordinate of the concept

Example request

  import weaviate

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

all_things = client.data_object.get()
print(all_things)

Example response

{
  "deprecations": null,
  "things": [
    {
      "_classification": {
        "basedOn": null,
        "classifiedFields": [
          "ofCategory"
        ],
        "completed": "2020-09-09T14:57:11.816Z",
        "id": "973e3b4c-4c1d-4b51-87d8-4d0343beb7ad",
        "scope": [
          "ofCategory"
        ]
      },
      "class": "Article",
      "creationTimeUnix": 1599650728421,
      "id": "046edbf3-235e-323e-886c-a37b7c1607ec",
      "meta": {
        "classification": {
          "basedOn": null,
          "classifiedFields": [
            "ofCategory"
          ],
          "completed": "2020-09-09T14:57:11.816Z",
          "id": "973e3b4c-4c1d-4b51-87d8-4d0343beb7ad",
          "scope": [
            "ofCategory"
          ]
        }
      },
      "schema": {
        "hasAuthors": [
          {
            "beacon": "weaviate://localhost/things/3946d9ea-f1cc-342d-99d7-c33a3bb04077",
            "href": "/v1/things/3946d9ea-f1cc-342d-99d7-c33a3bb04077"
          },
          {
            "beacon": "weaviate://localhost/things/99f05775-5552-3686-87a1-581b5872fb0f",
            "href": "/v1/things/99f05775-5552-3686-87a1-581b5872fb0f"
          }
        ],
        "inPublication": [
          {
            "beacon": "weaviate://localhost/things/212e56a6-e535-3569-ad1b-2215526c1d9d",
            "href": "/v1/things/212e56a6-e535-3569-ad1b-2215526c1d9d"
          }
        ],
        "ofCategory": [
          {
            "_classification": {
              "winningDistance": 0.35781192779541016
            },
            "beacon": "weaviate://localhost/things/ec4bb873-6b75-3f39-8a4b-d38212c9aa5f",
            "href": "/v1/things/ec4bb873-6b75-3f39-8a4b-d38212c9aa5f",
            "meta": {
              "classification": {
                "winningDistance": 0.35781192779541016
              }
            }
          }
        ],
        "summary": "In 1986, Cliff Stoll’s boss at Lawrence Berkeley National Labs tasked him with getting to the bottom of a 75-cent accounting discrepancy in the lab’s computer network, which was rented out to remote users by the minute. Stoll then spent the next year of his life following that hacker’s footprints across the lab’s network and the nascent internet. As The Cuckoo’s Egg hits its 30th anniversary, the book has sold more than 1 million copies. Stoll asks people who have interviewed him to sign his personal copy of The Cuckoo's Egg. Or that the CEO of a credit reporting company could lose his job because of computer security.",
        "title": "Meet The Mad Scientist Who Wrote the Book on How to Hunt Hackers",
        "url": "https://wired.com/story/meet-the-mad-scientist-who-wrote-the-book-on-how-to-hunt-hackers/",
        "wordCount": 509
      },
      "vectorWeights": null
    },
    {
      "_classification": {
        "basedOn": null,
        "classifiedFields": [
          "ofCategory"
        ],
        "completed": "2020-09-09T14:57:11.834Z",
        "id": "973e3b4c-4c1d-4b51-87d8-4d0343beb7ad",
        "scope": [
          "ofCategory"
        ]
      },
      "class": "Article",
      "creationTimeUnix": 1599650728431,
      "id": "bf1156f4-509a-3432-90ee-8b8cba6c5bd1",
      "meta": {
        "classification": {
          "basedOn": null,
          "classifiedFields": [
            "ofCategory"
          ],
          "completed": "2020-09-09T14:57:11.834Z",
          "id": "973e3b4c-4c1d-4b51-87d8-4d0343beb7ad",
          "scope": [
            "ofCategory"
          ]
        }
      },
      "schema": {
        "hasAuthors": [
          {
            "beacon": "weaviate://localhost/things/46dbc061-5fe3-3ac5-a87c-c01a301d2b22",
            "href": "/v1/things/46dbc061-5fe3-3ac5-a87c-c01a301d2b22"
          }
        ],
        "inPublication": [
          {
            "beacon": "weaviate://localhost/things/f2968730-9ce5-3e6f-8e64-b6b9f68984b0",
            "href": "/v1/things/f2968730-9ce5-3e6f-8e64-b6b9f68984b0"
          }
        ],
        "ofCategory": [
          {
            "_classification": {
              "winningDistance": 0.41243571043014526
            },
            "beacon": "weaviate://localhost/things/592b8e70-b464-3708-a802-dcfced711c81",
            "href": "/v1/things/592b8e70-b464-3708-a802-dcfced711c81",
            "meta": {
              "classification": {
                "winningDistance": 0.41243571043014526
              }
            }
          }
        ],
        "summary": "Biden, as he did on other occasions, got swept away with puffing himself up and sprinted over the factual line. I wrote another story at the same time about Biden lifting chunks of Robert Kennedy speeches. I ran into him on a back stairway in the Senate when he was getting ready for his news conference. One of his top aides yelled at me and told me I wouldn’t be allowed into Robert Bork’s Supreme Court confirmation hearings, which Biden was chairing. Biden has a talent for messes and has made some bad judgment calls — including voting to authorize the Iraq war.",
        "title": "Opinion | Liar, Liar, Nation on Fire",
        "url": "https://www.nytimes.com/2020/07/11/opinion/sunday/trump-biden-2020.html",
        "wordCount": 242
      },
      "vectorWeights": null
    }
  ],
  "totalResults": 2
}

Create a data object

Create a new semantic kind data object. The provided meta-data and schema values are validated.

Method and URL

POST /v1/{semantic_kind}

Parameters

namelocationtypedescription
{semantic_kind}URLstringA semantic kind is used to -respectively- describe nouns or verbs. Options are things or actions

The body of the data object for a new Thing or Action takes the following fields:

nametyperequireddescription
classstringyesthe class name as defined in the schema
schemaarrayyesan object with the property values of the new data object
schema > {property_name}dataTypeyesthe property and its value according to the set dataType
idv4 UUIDnothe given id of the data object

Example request

  import weaviate

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

data_obj = {
    "name": "Jodi Kantor",
    "writesFor": [{
        "beacon": "weaviate://localhost/things/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
    }]
}

client.data_object.create(data_obj, "Author", "36ddd591-2dee-4e7e-a3cc-eb86d30a4303")

Example response

{
  "class": "Author",
  "creationTimeUnix": 1599748326015,
  "id": "36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
  "lastUpdateTimeUnix": 1599748326015,
  "schema": {
    "name": "Jodi Kantor",
    "writesFor": [
      {
        "beacon": "weaviate://localhost/things/f81bfe5e-16ba-4615-a516-46c2ae2e5a80",
        "href": "/v1/things/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
      }
    ]
  }
}

Adding an object with geoCoordinates

If you want to fill the value of a geoCoordinates property, you need to specify the latitude and longitude as decimal degrees in floats:

  import weaviate

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

data_obj = {
  "name": "Elsevier",
  "headquartersGeoLocation": {
    "latitude": 52.3932696,
    "longitude": 4.8374263
  }

client.data_object.create(data_obj, "Publication", "df48b9f6-ba48-470c-bf6a-57657cb07390")

Get a data object

Collect an individual data object.

Method and URL

GET /v1/{semantic_kind}/{id}

Parameters

namelocationtypedescription
{semantic_kind}URLstringA semantic kind is used to -respectively- describe nouns or verbs. Options are things or actions
{id}URLuuidThe uuid of the data object to retrieve.
includeURLstringInclude additional information, such as classification info. Allowed values include: classification, _classification, vector, _vector, interpretation, _interpretation.

Example request

See here the explanation of the response fields.

  import weaviate

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

data_object = client.data_object.get_by_id("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
print(data_object)

Example response

{
  "class": "Author",
  "creationTimeUnix": 1599748237739,
  "id": "36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
  "lastUpdateTimeUnix": 1599748237739,
  "schema": {
    "name": "Jodi Kantor",
    "writesFor": [
      {
        "beacon": "weaviate://localhost/things/f81bfe5e-16ba-4615-a516-46c2ae2e5a80",
        "href": "/v1/things/f81bfe5e-16ba-4615-a516-46c2ae2e5a80"
      }
    ]
  },
  "vectorWeights": null
}

Update a data object

Update an individual data object based on its uuid.

Method and URL

In the RESTful API, both PUT and PATCH methods are accepted. PUT replaces all property values of the data object, while PATCH only overwrites the given properties.

PUT /v1/{semantic_kind}/{id}
PATCH /v1/{semantic_kind}/{id}

Parameters

namelocationtypedescription
{semantic_kind}URLstringA semantic kind is used to -respectively- describe nouns or verbs. Options are things or actions
{id}URLuuidThe uuid of the data object to update.

The body of the data object for a replacing (some) properties of a Thing or Action takes the following fields:

nametyperequireddescription
classstringyesthe class name as defined in the schema
schemaarrayyesan object with the property values of the new data object
schema > {property_name}dataTypeyesthe property and its value according to the set dataType

Example request

  import weaviate

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

updated_schema = {
    "name": "J. Kantor"
}

# Similar to RESTful PUT request: schema will be replaced by "updated-schema"
client.data_object.update(updated_schema, "Author", "36ddd591-2dee-4e7e-a3cc-eb86d30a4303")

# Similar to RESTful PATCH request: "updated_schema" will be merged with the existing schema, replacing only the properties in "updated_schema"
client.data_object.merge(updated_schema, "Author", "36ddd591-2dee-4e7e-a3cc-eb86d30a4303")

If the update was successful, no content will be returned.

Delete a data object

Delete an individual data object from Weaviate.

Note: if the data object is a Thing, all Actions pointing to this thing are also being deleted.

Method and URL

DELETE /v1/{semantic_kind}/{id}

Parameters

namelocationtypedescription
{id}URLuuidThe uuid of the data object to delete.

Example request

  import weaviate

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

client.data_object.delete("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")

If the deletion was successful, no content will be returned.

Validate a data object

You can validate a data object’s schema and meta data.

Method and URL

POST /v1/{semantic_kind}/validate

Parameters

namelocationtypedescription
{semantic_kind}URLstringA semantic kind is used to -respectively- describe nouns or verbs. Options are things or actions

The body of the data object for a new Thing or Action is an object taking the following field:

nametyperequireddescription
classstringyesthe class name as defined in the schema
schemaarrayyesan object with the property values of the new data object
schema > {property_name}dataTypeyesthe property and its value according to the set dataType
idv4 uuidno*The id of the data object. *An ID is required by the clients.

Example request

  import weaviate

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

schema = {"name": "New York Times"}

valid_thing = client.data_object.validate(schema, 'Publication', 'f81bfe5e-16ba-4615-a516-46c2ae2e5a80')
print(valid_thing)

If the schema of the object is valid, this request should return True/true in case of the clients and nothing with a plain RESTful request.

Cross-references

Add a cross reference

Method and URL

POST /v1/{semantic_kind}/{id}/references/{property_name}

Parameters

namelocationtypedescription
{semantic_kind}URLstringA semantic kind is used to -respectively- describe nouns or verbs. Options are things or actions
{id}URLuuidThe uuid of the data object to add the reference to.
{property_name}URLyesThe name of the cross-reference property

The body of the data object for a new Thing or Action is an object taking the following field:

nametyperequireddescription
beaconv4 UUIDyesthe beacon URL of the reference

Example request

  import weaviate

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

client.data_object.reference.add("36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
    "wroteArticles", "6bb06a43-e7f0-393e-9ecf-3c0f4e129064")

''' ALTERNATIVE METHODS
# 2. from actions
from weaviate import SEMANTIC_TYPE_ACTIONS
client.data_object.reference.add("1140b9d7-6335-49c9-92e0-3029f1cf1862",
    "wroteArticles", "7c4efed4-f38b-4f6f-abbe-b8801128f4b5",
    from_semantic_type=SEMANTIC_TYPE_ACTIONS)

# 3. using url
client.data_object.reference.add("http://localhost:8080/v1/things/36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
    "publisher", "http://localhost:8080/v1/things/6bb06a43-e7f0-393e-9ecf-3c0f4e129064")

# 4. using weaviate url
client.data_object.reference.add("weaviate://localhost/things/36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
    "wroteArticles", "weaviate://localhost/things/6bb06a43-e7f0-393e-9ecf-3c0f4e129064")
'''

If the addition was successful, no content will be returned.

Update a cross reference

A PUT request updates all references of a property of a data object.

Method and URL

PUT /v1/{semantic_kind}/{id}/references/{property_name}

Parameters

namelocationtypedescription
{semantic_kind}URLstringA semantic kind is used to -respectively- describe nouns or verbs. Options are things or actions
{id}URLuuidThe uuid of the data object to add the reference to.
{property_name}URLyesThe name of the cross-reference property

The body of the data object for a new Thing or Action is a list of beacons:

nametyperequireddescription
beaconv4 UUIDyesthe beacon URL of the reference

Example request

  import weaviate

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

client.data_object.reference.update("36ddd591-2dee-4e7e-a3cc-eb86d30a4303", "wroteArticles", ["6bb06a43-e7f0-393e-9ecf-3c0f4e129064", "b72912b9-e5d7-304e-a654-66dc63c55b32"])

If the addition was successful, no content will be returned.

Delete a cross reference

Delete the single reference that is given in the body from the list of references that this property of a data object has.

Method and URL

DELETE /v1/{semantic_kind}/{id}/references/{property_name}

Parameters

namelocationtypedescription
{semantic_kind}URLstringA semantic kind is used to -respectively- describe nouns or verbs. Options are things or actions
{id}URLuuidThe uuid of the data object to add the reference to.
{property_name}URLyesThe name of the cross-reference property

The body of the data object for a new Thing or Action is a list of beacons:

nametyperequireddescription
beaconv4 UUIDyesthe beacon URL of the reference

Example request

  import weaviate

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

client.data_object.reference.delete("36ddd591-2dee-4e7e-a3cc-eb86d30a4303", "wroteArticles", "6bb06a43-e7f0-393e-9ecf-3c0f4e129064")

If the addition was successful, no content will be returned.

Tags
  • RESTful API
  • references
  • class