Cross-references
Use cross-references to establish directional relationships between collections.
Additional information
Notes:
- Cross-references does not affect object vectors of the source or the target objects.
- For multi-tenancy collection, you can establish a cross-reference from a multi-tenancy collection object to:
- A non-multi-tenancy collection object, or
- A multi-tenancy collection object belonging to the same tenant.
Define a cross-reference property
Include the reference property in the collection definition before adding cross-references to it.
- Python (v4)
- Python (v3)
import weaviate.classes as wvc
client.collections.create(
name="JeopardyQuestion",
description="A Jeopardy! question",
properties=[
wvc.config.Property(name="question", data_type=wvc.config.DataType.TEXT),
wvc.config.Property(name="answer", data_type=wvc.config.DataType.TEXT),
],
references=[
wvc.config.ReferenceProperty(
name="hasCategory",
target_collection="JeopardyCategory"
)
]
)
class_definitions = [
{
"class": "JeopardyCategory",
"properties": [
{"name": "title", "dataType": ["text"]},
],
},
{
"class": "JeopardyQuestion",
"description": "A Jeopardy! question",
"properties": [
{"name": "question", "dataType": ["text"]},
{"name": "answer", "dataType": ["text"]},
{
"name": "hasCategory",
"dataType": ["JeopardyCategory"],
"description": "The category of the question",
},
],
},
]
client.schema.create({"classes": class_definitions})
Add a cross-reference property
It is also possible to add a cross-reference property to an existing collection definition.
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
# Add the reference to JeopardyQuestion, after it was created
category = client.collections.get("JeopardyCategory")
# category.config.add_reference(
category.config.add_reference(
wvc.config.ReferenceProperty(
name="hasQuestion",
target_collection="JeopardyQuestion"
)
)
# Add the "hasQuestion" cross-reference property to the JeopardyCategory class
client.schema.property.create("JeopardyCategory", {
"name": "hasQuestion",
"dataType": ["JeopardyQuestion"]
})
// Add the "hasQuestion" cross-reference property to the JeopardyCategory class
await client.schema
.propertyCreator()
.withClassName('JeopardyCategory')
.withProperty({
name: 'hasQuestion',
dataType: ['JeopardyQuestion'],
})
.do();
Create an object with a cross-reference
Specify a cross-reference when creating an object.
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
import weaviate.classes as wvc
questions = client.collections.get("JeopardyQuestion")
questions.data.insert(
properties=properties, # A dictionary with the properties of the object
uuid=obj_uuid, # A UUID for the object
references={"hasCategory": category_uuid}, # e.g. {"hasCategory": "583876f3-e293-5b5b-9839-03f455f14575"}
)
# data_obj is a dictionary with the object's properties
data_obj["hasCategory"] = [ # Add one or more cross-references through the "hasCategory" property
{"beacon": f"weaviate://localhost/JeopardyCategory/{category_uuid}"}
]
data_uuid = client.data_object.create(
data_obj,
"JeopardyQuestion",
uuid=obj_uuid, # optional; if not provided, one will be generated
)
const myCollection = client.collections.get('WineReviewNV')
const dataObject = {
"title": "A delicious Riesling",
"review_body": "This wine is a delicious Riesling which pairs well with seafood.",
"country": "Germany",
}
const uuid = await myCollection.data.insert({
properties: dataObject,
id: '<UUID>', // A UUID for the object
references: {
'hasCategory': '<CATEGORY UUID>' // e.g. {'hasCategory': '583876f3-e293-5b5b-9839-03f455f14575'}
}
})
console.log('UUID: ', uuid)
Add a one-way cross-reference
Specify the required id and properties for the source and the target.
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Java
- Go
import weaviate.classes as wvc
questions = client.collections.get("JeopardyQuestion")
questions.data.reference_add(
from_uuid=question_obj_id,
from_property="hasCategory",
to=category_obj_id
)
sf_id = "00ff6900-e64f-5d94-90db-c8cfa3fc851b"
us_cities_id = "20ffc68d-986b-5e71-a680-228dba18d7ef"
client.data_object.reference.add(
from_class_name="JeopardyQuestion",
from_uuid=sf_id,
from_property_name="hasCategory",
to_class_name="JeopardyCategory",
to_uuid=us_cities_id,
)
await client.data
.referenceCreator()
.withClassName('JeopardyQuestion').withId('00ff6900-e64f-5d94-90db-c8cfa3fc851b')
.withReferenceProperty('hasCategory')
.withReference(
client.data
.referencePayloadBuilder()
.withClassName('JeopardyCategory')
.withId('20ffc68d-986b-5e71-a680-228dba18d7ef')
.payload()
)
.do();
String sfId = "00ff6900-e64f-5d94-90db-c8cfa3fc851b";
String usCitiesId = "20ffc68d-986b-5e71-a680-228dba18d7ef";
client.data().referenceCreator()
.withClassName("JeopardyQuestion")
.withID(sfId)
.withReferenceProperty("hasCategory")
.withReference(client.data()
.referencePayloadBuilder()
.withClassName("JeopardyCategory")
.withID(usCitiesId)
.payload())
.run();
sfID := "00ff6900-e64f-5d94-90db-c8cfa3fc851b"
usCitiesID := "20ffc68d-986b-5e71-a680-228dba18d7ef"
client.Data().ReferenceCreator().
WithClassName("JeopardyQuestion").
WithID(sfID).
WithReferenceProperty("hasCategory").
WithReference(client.Data().ReferencePayloadBuilder().
WithClassName("JeopardyCategory").
WithID(usCitiesID).
Payload()).
Do(ctx)
Add two-way cross-references
This requires adding reference properties in both directions, and adding two cross-references per object pair (from
A -> to
B and from
B -> to
A).
Create the JeopardyCategory
collection:
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
import weaviate.classes as wvc
category = client.collections.create(
name="JeopardyCategory",
description="A Jeopardy! category",
properties=[
wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT)
]
)
category_definition = {
"class": "JeopardyCategory",
"properties": [
{"name": "title", "dataType": ["text"]},
],
}
client.schema.create_class(category_definition)
const jeopardyCategoryClass = {
class: 'JeopardyCategory',
};
await client
.schema
.classCreator()
.withClass(jeopardyCategoryClass)
.do();
Create the JeopardyQuestion
collection including the reference property to JeopardyCategory
:
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
client.collections.create(
name="JeopardyQuestion",
description="A Jeopardy! question",
properties=[
wvc.config.Property(name="question", data_type=wvc.config.DataType.TEXT),
wvc.config.Property(name="answer", data_type=wvc.config.DataType.TEXT),
],
references=[
wvc.config.ReferenceProperty(
name="hasCategory",
target_collection="JeopardyCategory"
)
]
)
question_definition = {
"class": "JeopardyQuestion",
"description": "A Jeopardy! question",
"properties": [
{"name": "question", "dataType": ["text"]},
{"name": "answer", "dataType": ["text"]},
{
"name": "hasCategory",
"dataType": ["JeopardyCategory"],
"description": "The category of the question",
},
],
}
client.schema.create_class(question_definition)
const jeopardyQuestionClass = {
class: 'JeopardyQuestion',
description: 'A Jeopardy! question',
properties: [
{ name: 'question' , dataType: ['text'] },
{ name: 'answer', dataType: ['text'] },
{
name: 'hasCategory',
dataType: ['JeopardyCategory'],
description: 'The category of the question',
},
],
vectorizer: 'text2vec-openai',
};
await client
.schema
.classCreator()
.withClass(jeopardyQuestionClass)
.do();
Modify JeopardyCategory
to add the reference to JeopardyQuestion
:
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
# Add the reference to JeopardyQuestion, after it was created
category = client.collections.get("JeopardyCategory")
# category.config.add_reference(
category.config.add_reference(
wvc.config.ReferenceProperty(
name="hasQuestion",
target_collection="JeopardyQuestion"
)
)
# Add the "hasQuestion" cross-reference property to the JeopardyCategory class
client.schema.property.create("JeopardyCategory", {
"name": "hasQuestion",
"dataType": ["JeopardyQuestion"]
})
// Add the "hasQuestion" cross-reference property to the JeopardyCategory class
await client.schema
.propertyCreator()
.withClassName('JeopardyCategory')
.withProperty({
name: 'hasQuestion',
dataType: ['JeopardyQuestion'],
})
.do();
And add the cross-references:
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Java
- Go
import weaviate.classes as wvc
# For the "San Francisco" JeopardyQuestion object, add a cross-reference to the "U.S. CITIES" JeopardyCategory object
questions = client.collections.get("JeopardyQuestion")
questions.data.reference_add(
from_uuid=question_obj_id,
from_property="hasCategory",
to=category_obj_id
)
# For the "U.S. CITIES" JeopardyCategory object, add a cross-reference to "San Francisco"
categories = client.collections.get("JeopardyCategory")
categories.data.reference_add(
from_uuid=category_obj_id,
from_property="hasQuestion",
to=question_obj_id
)
sf_id = "00ff6900-e64f-5d94-90db-c8cfa3fc851b"
us_cities_id = "20ffc68d-986b-5e71-a680-228dba18d7ef"
# For the "San Francisco" JeopardyQuestion object, add a cross-reference to the "U.S. CITIES" JeopardyCategory object
client.data_object.reference.add(
from_class_name="JeopardyQuestion",
from_uuid=sf_id,
from_property_name="hasCategory",
to_class_name="JeopardyCategory",
to_uuid=us_cities_id,
)
# For the "U.S. CITIES" JeopardyCategory object, add a cross-reference to "San Francisco"
client.data_object.reference.add(
from_class_name="JeopardyCategory",
from_uuid=us_cities_id,
from_property_name="hasQuestion",
to_class_name="JeopardyQuestion",
to_uuid=sf_id,
)
// For the "San Francisco" JeopardyQuestion object, add a cross-reference to the "U.S. CITIES" JeopardyCategory object
await client.data
.referenceCreator()
.withClassName('JeopardyQuestion').withId('00ff6900-e64f-5d94-90db-c8cfa3fc851b')
.withReferenceProperty('hasCategory')
.withReference(
client.data
.referencePayloadBuilder()
.withClassName('JeopardyCategory')
.withId('20ffc68d-986b-5e71-a680-228dba18d7ef')
.payload()
)
.do();
// For the "U.S. CITIES" JeopardyCategory object, add a cross-reference to "San Francisco"
await client.data
.referenceCreator()
.withClassName('JeopardyCategory').withId('20ffc68d-986b-5e71-a680-228dba18d7ef')
.withReferenceProperty('hasQuestion')
.withReference(
client.data
.referencePayloadBuilder()
.withClassName('JeopardyQuestion')
.withId('00ff6900-e64f-5d94-90db-c8cfa3fc851b')
.payload()
)
.do();
String sfId = "00ff6900-e64f-5d94-90db-c8cfa3fc851b";
String usCitiesId = "20ffc68d-986b-5e71-a680-228dba18d7ef";
// First, add the "hasQuestion" cross-reference property to the JeopardyCategory class
client.schema().propertyCreator()
.withClassName("JeopardyCategory")
.withProperty(Property.builder()
.name("hasQuestion")
.dataType(Collections.singletonList("JeopardyQuestion"))
.build())
.run();
// For the "San Francisco" JeopardyQuestion object, add a cross-reference to the "U.S. CITIES" JeopardyCategory object
client.data().referenceCreator()
.withClassName("JeopardyQuestion")
.withID(usCitiesId)
.withReferenceProperty("hasCategory")
.withReference(client.data()
.referencePayloadBuilder()
.withClassName("JeopardyCategory")
.withID(sfId)
.payload())
.run();
// For the "U.S. CITIES" JeopardyCategory object, add a cross-reference to "San Francisco"
client.data().referenceCreator()
.withClassName("JeopardyCategory")
.withID(usCitiesId)
.withReferenceProperty("hasQuestion")
.withReference(client.data()
.referencePayloadBuilder()
.withClassName("JeopardyQuestion")
.withID(usCitiesId)
.payload())
.run();
sfID := "00ff6900-e64f-5d94-90db-c8cfa3fc851b"
usCitiesID := "20ffc68d-986b-5e71-a680-228dba18d7ef"
// First, add the "hasQuestion" cross-reference property to the JeopardyCategory class
client.Schema().PropertyCreator().
WithClassName("JeopardyCategory").
WithProperty(&models.Property{
Name: "hasQuestion",
DataType: []string{"JeopardyQuestion"},
}).
Do(ctx)
// For the "San Francisco" JeopardyQuestion object, add a cross-reference to the "U.S. CITIES" JeopardyCategory object
client.Data().ReferenceCreator().
WithClassName("JeopardyQuestion").
WithID(sfID).
WithReferenceProperty("hasCategory").
WithReference(client.Data().ReferencePayloadBuilder().
WithClassName("JeopardyCategory").
WithID(usCitiesID).
Payload()).
Do(ctx)
// For the "U.S. CITIES" JeopardyCategory object, add a cross-reference to "San Francisco"
client.Data().ReferenceCreator().
WithClassName("JeopardyCategory").
WithID(usCitiesID).
WithReferenceProperty("hasQuestion").
WithReference(client.Data().ReferencePayloadBuilder().
WithClassName("JeopardyQuestion").
WithID(sfID).
Payload()).
Do(ctx)
Add multiple (one-to-many) cross-references
Weaviate allows creation of multiple cross-references from one source object.
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Java
- Go
import weaviate.classes as wvc
questions = client.collections.get("JeopardyQuestion")
refs_list = []
for temp_uuid in [category_obj_id, category_obj_id_alt]:
ref_obj = wvc.data.DataReference(
from_uuid=question_obj_id,
from_property="hasCategory",
to_uuid=temp_uuid
)
refs_list.append(ref_obj)
questions.data.reference_add_many(refs_list)
sf_id = "00ff6900-e64f-5d94-90db-c8cfa3fc851b"
us_cities_id = "20ffc68d-986b-5e71-a680-228dba18d7ef"
museums_id = "fec50326-dfa1-53c9-90e8-63d0240bd933"
# Add to "San Francisco" the "U.S. CITIES" category
client.data_object.reference.add(
from_class_name="JeopardyQuestion",
from_uuid=sf_id,
from_property_name="hasCategory",
to_class_name="JeopardyCategory",
to_uuid=us_cities_id,
)
# Add the "MUSEUMS" category as well
client.data_object.reference.add(
from_class_name="JeopardyQuestion",
from_uuid=sf_id,
from_property_name="hasCategory",
to_class_name="JeopardyCategory",
to_uuid=museums_id,
)
// Add to "San Francisco" the "U.S. CITIES" category
await client.data
.referenceCreator()
.withClassName('JeopardyQuestion').withId('00ff6900-e64f-5d94-90db-c8cfa3fc851b')
.withReferenceProperty('hasCategory')
.withReference(
client.data
.referencePayloadBuilder()
.withClassName('JeopardyCategory')
.withId('20ffc68d-986b-5e71-a680-228dba18d7ef')
.payload()
)
.do();
// Add the "MUSEUMS" category as well
await client.data
.referenceCreator()
.withClassName('JeopardyQuestion').withId('00ff6900-e64f-5d94-90db-c8cfa3fc851b')
.withReferenceProperty('hasCategory')
.withReference(
client.data
.referencePayloadBuilder()
.withClassName('JeopardyCategory')
.withId('fec50326-dfa1-53c9-90e8-63d0240bd933')
.payload()
)
.withConsistencyLevel('ALL')
.do();
String sfId = "00ff6900-e64f-5d94-90db-c8cfa3fc851b";
String usCitiesId = "20ffc68d-986b-5e71-a680-228dba18d7ef";
String museumsId = "fec50326-dfa1-53c9-90e8-63d0240bd933";
// Add to "San Francisco" the "U.S. CITIES" category
client.data().referenceCreator()
.withClassName("JeopardyQuestion")
.withID(sfId)
.withReferenceProperty("hasCategory")
.withReference(client.data()
.referencePayloadBuilder()
.withClassName("JeopardyCategory")
.withID(usCitiesId)
.payload())
.run();
// Add the "MUSEUMS" category as well
client.data().referenceCreator()
.withClassName("JeopardyQuestion")
.withID(sfId)
.withReferenceProperty("hasCategory")
.withReference(client.data()
.referencePayloadBuilder()
.withClassName("JeopardyCategory")
.withID(museumsId)
.payload())
.run();
sfID := "00ff6900-e64f-5d94-90db-c8cfa3fc851b"
usCitiesID := "20ffc68d-986b-5e71-a680-228dba18d7ef"
museumsID := "fec50326-dfa1-53c9-90e8-63d0240bd933"
// Add to "San Francisco" the "U.S. CITIES" category
client.Data().ReferenceCreator().
WithClassName("JeopardyQuestion").
WithID(sfID).
WithReferenceProperty("hasCategory").
WithReference(client.Data().ReferencePayloadBuilder().
WithClassName("JeopardyCategory").
WithID(usCitiesID).
Payload()).
Do(ctx)
// Add the "MUSEUMS" category as well
client.Data().ReferenceCreator().
WithClassName("JeopardyQuestion").
WithID(sfID).
WithReferenceProperty("hasCategory").
WithReference(client.Data().ReferencePayloadBuilder().
WithClassName("JeopardyCategory").
WithID(museumsID).
Payload()).
Do(ctx)
Delete a cross-reference
Deleting a cross-reference with the same parameters used to define the cross-reference.
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Java
- Go
import weaviate.classes as wvc
# From the "San Francisco" JeopardyQuestion object, delete the "MUSEUMS" category cross-reference
questions = client.collections.get("JeopardyQuestion")
questions.data.reference_delete(
from_uuid=question_obj_id,
from_property="hasCategory",
to=category_obj_id
)
sf_id = "00ff6900-e64f-5d94-90db-c8cfa3fc851b"
museums_id = "fec50326-dfa1-53c9-90e8-63d0240bd933"
# From the "San Francisco" JeopardyQuestion object, delete the "MUSEUMS" category cross-reference
# https://weaviate-python-client.readthedocs.io/en/stable/weaviate.data.references.html#weaviate.data.references.Reference.delete
sf = client.data_object.get(uuid=sf_id, class_name="JeopardyQuestion")
cat = client.data_object.get(uuid=museums_id, class_name="JeopardyCategory")
client.data_object.reference.delete(
from_class_name="JeopardyQuestion",
from_uuid=sf_id,
from_property_name="hasCategory",
to_class_name="JeopardyCategory",
to_uuid=museums_id,
)
// From the "San Francisco" JeopardyQuestion object, delete the "MUSEUMS" category cross-reference
await client.data
.referenceDeleter()
.withClassName('JeopardyQuestion').withId('00ff6900-e64f-5d94-90db-c8cfa3fc851b')
.withReferenceProperty('hasCategory')
.withReference(
client.data
.referencePayloadBuilder()
.withClassName('JeopardyCategory')
.withId('fec50326-dfa1-53c9-90e8-63d0240bd933')
.payload()
)
.do();
String sfId = "00ff6900-e64f-5d94-90db-c8cfa3fc851b";
String museumsId = "fec50326-dfa1-53c9-90e8-63d0240bd933";
// From the "San Francisco" JeopardyQuestion object, delete the "MUSEUMS" category cross-reference
client.data().referenceDeleter()
.withClassName("JeopardyQuestion")
.withID(sfId)
.withReferenceProperty("hasCategory")
.withReference(client.data()
.referencePayloadBuilder()
.withClassName("JeopardyCategory")
.withID(museumsId)
.payload())
.run();
sfID := "00ff6900-e64f-5d94-90db-c8cfa3fc851b"
museumsID := "fec50326-dfa1-53c9-90e8-63d0240bd933"
// From the "San Francisco" JeopardyQuestion object, delete the "MUSEUMS" category cross-reference
client.Data().ReferenceDeleter().
WithClassName("JeopardyQuestion").
WithID(sfID).
WithReferenceProperty("hasCategory").
WithReference(client.Data().ReferencePayloadBuilder().
WithClassName("JeopardyCategory").
WithID(museumsID).
Payload()).
Do(ctx)
What happens if the target object is deleted?
What happens if the to
object is deleted?
If an object is deleted, cross-references to it will be left intact. A Get query using the inline fragment syntax will correctly retrieve only fields in the existing cross-references objects, but getting the object by ID will show all cross-references, whether the objects they point to exist or not.
Update a cross-reference
The targets of a cross-reference can be updated.
- Python (v4)
- Python (v3)
- JavaScript/TypeScript
- Java
- Go
import weaviate.classes as wvc
# In the "San Francisco" JeopardyQuestion object, set the "hasCategory" cross-reference only to "MUSEUMS"
questions = client.collections.get("JeopardyQuestion")
questions.data.reference_replace(
from_uuid=question_obj_id,
from_property="hasCategory",
to=category_obj_id
)
sf_id = "00ff6900-e64f-5d94-90db-c8cfa3fc851b"
museums_id = "fec50326-dfa1-53c9-90e8-63d0240bd933"
# In the "San Francisco" JeopardyQuestion object, set the "hasCategory" cross-reference only to "MUSEUMS"
# https://weaviate-python-client.readthedocs.io/en/stable/weaviate.data.references.html#weaviate.data.references.Reference.update
client.data_object.reference.update(
from_class_name="JeopardyQuestion",
from_uuid=sf_id,
from_property_name="hasCategory",
to_class_names=["JeopardyCategory"],
to_uuids=[museums_id],
)
// In the "San Francisco" JeopardyQuestion object, set the "hasCategory" cross-reference only to "MUSEUMS"
await client.data
.referenceReplacer()
.withClassName('JeopardyQuestion').withId('00ff6900-e64f-5d94-90db-c8cfa3fc851b')
.withReferenceProperty('hasCategory')
.withReferences([
client.data
.referencePayloadBuilder()
.withClassName('JeopardyCategory')
.withId('fec50326-dfa1-53c9-90e8-63d0240bd933')
.payload(),
])
.do();
String sfId = "00ff6900-e64f-5d94-90db-c8cfa3fc851b";
String museumsId = "fec50326-dfa1-53c9-90e8-63d0240bd933";
// In the "San Francisco" JeopardyQuestion object, set the "hasCategory" cross-reference only to "MUSEUMS"
client.data().referenceReplacer()
.withClassName("JeopardyQuestion")
.withID(sfId)
.withReferenceProperty("hasCategory")
.withReferences(client.data()
.referencePayloadBuilder()
.withClassName("JeopardyCategory")
.withID(museumsId)
.payload())
.run();
sfID := "00ff6900-e64f-5d94-90db-c8cfa3fc851b"
museumsID := "fec50326-dfa1-53c9-90e8-63d0240bd933"
// In the "San Francisco" JeopardyQuestion object, set the "hasCategory" cross-reference only to "MUSEUMS"
client.Data().ReferenceReplacer().
WithClassName("JeopardyQuestion").
WithID(sfID).
WithReferenceProperty("hasCategory").
WithReferences(&models.MultipleRef{
client.Data().ReferencePayloadBuilder().
WithClassName("JeopardyCategory").
WithID(museumsID).
Payload(),
}).
Do(ctx)
Related pages
- Connect to Weaviate
- References: REST - /v1/objects
- Retrieve the object to retrieve its cross references.
- Retrieve the cross-reference as a part of a query.