Skip to main content

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.

from weaviate.classes.config import Property, DataType, ReferenceProperty

client.collections.create(
name="JeopardyQuestion",
description="A Jeopardy! question",
properties=[
Property(name="question", data_type=DataType.TEXT),
Property(name="answer", data_type=DataType.TEXT),
],
references=[
ReferenceProperty(
name="hasCategory",
target_collection="JeopardyCategory"
)
]

)

Add a cross-reference property

It is also possible to add a cross-reference property to an existing collection definition.

from weaviate.classes.config import ReferenceProperty

# Add the reference to JeopardyQuestion, after it was created
category = client.collections.get("JeopardyCategory")
# category.config.add_reference(
category.config.add_reference(
ReferenceProperty(
name="hasQuestion",
target_collection="JeopardyQuestion"
)
)

Create an object with a cross-reference

Specify a cross-reference when creating an object.

questions = client.collections.get("JeopardyQuestion")

questions.data.insert(
properties=properties, # A dictionary with the properties of the object
uuid=obj_uuid, # The UUID of the object
references={"hasCategory": category_uuid}, # e.g. {"hasCategory": "583876f3-e293-5b5b-9839-03f455f14575"}
)

Add a one-way cross-reference

Specify the required id and properties for the source and the target.

questions = client.collections.get("JeopardyQuestion")

questions.data.reference_add(
from_uuid=question_obj_id,
from_property="hasCategory",
to=category_obj_id
)

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:

from weaviate.classes.config import Property, DataType, ReferenceProperty

category = client.collections.create(
name="JeopardyCategory",
description="A Jeopardy! category",
properties=[
Property(name="title", data_type=DataType.TEXT)
]
)

Create the JeopardyQuestion collection including the reference property to JeopardyCategory:

client.collections.create(
name="JeopardyQuestion",
description="A Jeopardy! question",
properties=[
Property(name="question", data_type=DataType.TEXT),
Property(name="answer", data_type=DataType.TEXT),
],
references=[
ReferenceProperty(
name="hasCategory",
target_collection="JeopardyCategory"
)
]
)

Modify JeopardyCategory to add the reference to JeopardyQuestion:

from weaviate.classes.config import ReferenceProperty

# Add the reference to JeopardyQuestion, after it was created
category = client.collections.get("JeopardyCategory")
# category.config.add_reference(
category.config.add_reference(
ReferenceProperty(
name="hasQuestion",
target_collection="JeopardyQuestion"
)
)

And add the cross-references:

# 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
)

Add multiple (one-to-many) cross-references

Weaviate allows creation of multiple cross-references from one source object.

from weaviate.classes.data import DataReference

questions = client.collections.get("JeopardyQuestion")

refs_list = []
for temp_uuid in [category_obj_id, category_obj_id_alt]:
ref_obj = 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)

Read cross-references

Cross-references can be read as part of the object.

from weaviate.classes.query import QueryReference

questions = client.collections.get("JeopardyQuestion")

# Include the cross-references in a query response
response = questions.query.fetch_objects( # Or `hybrid`, `near_text`, etc.
limit=2,
return_references=QueryReference(
link_on="hasCategory",
return_properties=["title"]
)
)

# Or include cross-references in a single-object retrieval
obj = questions.query.fetch_object_by_id(
uuid=question_obj_id,
return_references=QueryReference(
link_on="hasCategory",
return_properties=["title"]
)
)

Delete a cross-reference

Deleting a cross-reference with the same parameters used to define the cross-reference.

# 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
)
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.

# 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
)

Questions and feedback

If you have any questions or feedback, let us know in the user forum.