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

from weaviate.classes.config import Property, DataType, ReferencePropertyclient.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"        )    ])

JavaScript/TypeScript

await client.collections.create({  name: 'JeopardyQuestion',  properties: [        { name: 'question' , dataType: 'text' },        { name: 'answer', dataType: 'text' }      ],  references: [{    name: 'hasCategory',    targetCollection: 'JeopardyCategory',  }]})

Java

client.collections.create("JeopardyCategory",    col -> col.description("A Jeopardy! category")        .properties(Property.text("title")));client.collections.create("JeopardyQuestion",    col -> col.description("A Jeopardy! question")        .properties(Property.text("question"), Property.text("answer"))        .references(ReferenceProperty.to("hasCategory", "JeopardyCategory")));

await client.Collections.Create(    new CollectionCreateParams    {        Name = "JeopardyCategory",        Description = "A Jeopardy! category",        Properties = [Property.Text("title")],    });await client.Collections.Create(    new CollectionCreateParams    {        Name = "JeopardyQuestion",        Description = "A Jeopardy! question",        Properties = [Property.Text("question"), Property.Text("answer")],        References = [new Reference("hasCategory", "JeopardyCategory")],    });

Add a cross-reference property

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

Python

from weaviate.classes.config import ReferenceProperty# Add the reference to JeopardyQuestion, after it was createdcategory = client.collections.use("JeopardyCategory")# category.config.add_reference(category.config.add_reference(    ReferenceProperty(        name="hasQuestion",        target_collection="JeopardyQuestion"    ))

JavaScript/TypeScript

// Add the "hasQuestion" cross-reference property to the JeopardyCategory collectionconst category = client.collections.use('JeopardyCategory')await category.config.addReference({  name: 'hasQuestion',  targetCollection: 'JeopardyQuestion'})

Java

var category = client.collections.use("JeopardyCategory");category.config.addReference(    "hasQuestion", "JeopardyQuestion");

var category = client.Collections.Use("JeopardyCategory");await category.Config.AddReference(    Property.Reference("hasQuestion", "JeopardyQuestion"));

Create an object with a cross-reference

Specify a cross-reference when creating an object.

Python

questions = client.collections.use("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"})

JavaScript/TypeScript

const category = client.collections.use('JeopardyCategory')const dataObject = {'name': 'Science'}const response = await category.data.insert({  properties: dataObject,  references: {    'hasCategory': categoryId  // e.g. {'hasCategory': '583876f3-e293-5b5b-9839-03f455f14575'}  }})console.log('UUID: ', response)

Java

var questions = client.collections.use("JeopardyQuestion");var result = questions.data.insert(properties, // A map with the properties of the object    opt -> opt        .reference("hasCategory", ObjectReference.uuids(categoryUuid)) // e.g. {"hasCategory":// "583876f3-e293-5b5b-9839-03f455f14575"});

var questions = client.Collections.Use("JeopardyQuestion");var newObject = await questions.Data.Insert(    properties, // The properties of the object    references: [new ObjectReference("hasCategory", categoryUuid)]);

Add a one-way cross-reference

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

Python

questions = client.collections.use("JeopardyQuestion")questions.data.reference_add(    from_uuid=question_obj_id,    from_property="hasCategory",    to=category_obj_id)

JavaScript/TypeScript

const jeopardy = client.collections.use('JeopardyCategory')await jeopardy.data.referenceAdd({  fromProperty: 'hasCategory',  fromUuid: questionObjectId,  to: categoryObjectId,})

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)

Java

questions.data.referenceAdd(questionObjId, "hasCategory",    ObjectReference.uuids(categoryObjId)[0]);

await questions.Data.ReferenceAdd(    from: questionObjId,    fromProperty: "hasCategory",    to: categoryObjId);

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

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

JavaScript/TypeScript

const category = client.collections.create({
  name: "JeopardyCategory",
  description: "A Jeopardy! category",
  properties: [
    { name: "title", dataType: "text" }
  ]
})

Java

client.collections.create("JeopardyCategory",
    col -> col.description("A Jeopardy! category")
        .properties(Property.text("title")));

await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = "JeopardyCategory",
        Description = "A Jeopardy! category",
        Properties = [Property.Text("title")],
    }
);

Create the JeopardyQuestion collection including the reference property to JeopardyCategory:

Python

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"        )    ])

JavaScript/TypeScript

const jeopardyQuestionCollection = client.collections.create({  name: 'JeopardyQuestion',  properties: [    { name: 'question' , dataType: 'text' },    { name: 'answer', dataType: 'text' }  ],  references: [{    name: 'hasCategory',    targetCollection: 'JeopardyCategory'  }]})

Java

client.collections.create("JeopardyQuestion",    col -> col.description("A Jeopardy! question")        .properties(Property.text("question"), Property.text("answer"))        .references(ReferenceProperty.to("hasCategory", "JeopardyCategory")));

await client.Collections.Create(    new CollectionCreateParams    {        Name = "JeopardyQuestion",        Description = "A Jeopardy! question",        Properties = [Property.Text("question"), Property.Text("answer")],        References = [new Reference("hasCategory", "JeopardyCategory")],    });

Modify JeopardyCategory to add the reference to JeopardyQuestion:

Python

from weaviate.classes.config import ReferenceProperty# Add the reference to JeopardyQuestion, after it was createdcategory = client.collections.use("JeopardyCategory")# category.config.add_reference(category.config.add_reference(    ReferenceProperty(        name="hasQuestion",        target_collection="JeopardyQuestion"    ))

JavaScript/TypeScript

// Add the "hasQuestion" cross-reference property to the JeopardyCategory collectionconst category = client.collections.use('JeopardyCategory')await category.config.addReference({  name: 'hasQuestion',  targetCollection: 'JeopardyQuestion'})

Java

var category = client.collections.use("JeopardyCategory");category.config.addReference(    "hasQuestion", "JeopardyQuestion");

var category = client.Collections.Use("JeopardyCategory");await category.Config.AddReference(    Property.Reference("hasQuestion", "JeopardyQuestion"));

And add the cross-references:

Python

# For the "San Francisco" JeopardyQuestion object, add a cross-reference to the "U.S. CITIES" JeopardyCategory objectquestions = client.collections.use("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.use("JeopardyCategory")categories.data.reference_add(    from_uuid=category_obj_id,    from_property="hasQuestion",    to=question_obj_id)

JavaScript/TypeScript

// For the "San Francisco" JeopardyQuestion object, add a cross-reference to the "U.S. CITIES" JeopardyCategory objectconst questions = client.collections.use("JeopardyQuestion")await questions.data.referenceAdd({    fromUuid: questionObjectId,    fromProperty: 'hasCategory',    to: catogoryObjectId})// For the "U.S. CITIES" JeopardyCategory object, add a cross-reference to "San Francisco"const category = client.collections.use("JeopardyCategory")await category.data.referenceAdd({    fromUuid: catogoryObjectId,    fromProperty: 'hasQuestion',    to: questionObjectId})

sfID := "00ff6900-e64f-5d94-90db-c8cfa3fc851b"
usCitiesID := "20ffc68d-986b-5e71-a680-228dba18d7ef"

Java

// For the "San Francisco" JeopardyQuestion object, add a cross-reference to the// "U.S. CITIES" JeopardyCategory objectquestions.data.referenceAdd(questionObjId, "hasCategory",    ObjectReference.uuids(categoryObjId)[0]);// For the "U.S. CITIES" JeopardyCategory object, add a cross-reference to "San// Francisco"categories.data.referenceAdd(categoryObjId, "hasQuestion",    ObjectReference.uuids(questionObjId)[0]);

// For the "San Francisco" JeopardyQuestion object, add a cross-reference to the "U.S. CITIES" JeopardyCategory objectawait questions.Data.ReferenceAdd(    from: questionObjId,    fromProperty: "hasCategory",    to: categoryObjId);// For the "U.S. CITIES" JeopardyCategory object, add a cross-reference to "San Francisco"await categories.Data.ReferenceAdd(    from: categoryObjId,    fromProperty: "hasQuestion",    to: questionObjId);

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

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

Python

from weaviate.classes.data import DataReferencequestions = client.collections.use("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)

JavaScript/TypeScript

const questions = client.collections.use("JeopardyQuestion")await questions.data.referenceAddMany(  [{    fromUuid: questionObjectId,    fromProperty: 'hasCategory',    to: catogoryObjectId1  },{    fromUuid: questionObjectId,    fromProperty: 'hasCategory',    to: catogoryObjectId2  }])

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)

Java

// Add multiple references - need to add them individuallyfor (String tempUuid : List.of(categoryObjId, categoryObjIdAlt)) {  questions.data.referenceAdd(questionObjId, "hasCategory",      ObjectReference.uuids(tempUuid)[0]);}

// Add multiple references - need to add them individuallyforeach (var tempUuid in new[] { categoryObjId, categoryObjIdAlt }){    await questions.Data.ReferenceAdd(        from: questionObjId,        fromProperty: "hasCategory",        to: tempUuid    );}

Read cross-references

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

Python

from weaviate.classes.query import QueryReferencequestions = client.collections.use("JeopardyQuestion")# Include the cross-references in a query responseresponse = 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 retrievalobj = questions.query.fetch_object_by_id(    uuid=question_obj_id,    return_references=QueryReference(        link_on="hasCategory",        return_properties=["title"]    ))

JavaScript/TypeScript

const questions = client.collections.use("JeopardyQuestion")const response = await questions.query.fetchObjects({ // Or `hybrid`, `nearText`, etc.  limit: 2,  returnReferences: [{    linkOn: 'hasCategory',    returnProperties: ['title']  }]})response.objects.forEach(item =>  console.log(JSON.stringify(item.references, null, 2)))

Java

// Include the cross-references in a query responsevar response = questions.query.fetchObjects( // Or `hybrid`, `nearText`, etc.    opt -> opt.limit(2)        .returnReferences(QueryReference.single("hasCategory",            ref -> ref.returnProperties("title"))));// Or include cross-references in a single-object retrievalvar obj = questions.query.fetchObjectById(questionObjId,    opt -> opt.returnReferences(QueryReference.single("hasCategory",        ref -> ref.returnProperties("title"))));

// Include the cross-references in a query responsevar response = await questions.Query.FetchObjects( // Or `Hybrid`, `NearText`, etc.    limit: 2,    returnReferences: [new QueryReference("hasCategory", fields: ["title"])]);// Or include cross-references in a single-object retrievalvar obj = await questions.Query.FetchObjectByID(    questionObjId,    returnReferences: [new QueryReference("hasCategory", fields: ["title"])]);

Delete a cross-reference

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

Python

# From the "San Francisco" JeopardyQuestion object, delete the "MUSEUMS" category cross-referencequestions = client.collections.use("JeopardyQuestion")questions.data.reference_delete(    from_uuid=question_obj_id,    from_property="hasCategory",    to=category_obj_id)

JavaScript/TypeScript

// From the "San Francisco" JeopardyQuestion object, delete the "MUSEUMS" category cross-referenceconst questions = client.collections.use("JeopardyQuestion")await questions.data.referenceDelete({  fromUuid: questionObjectId,  fromProperty: 'hasCategory',  to: catogoryObjectId})

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)

Java

// From the "San Francisco" JeopardyQuestion object, delete the "MUSEUMS"// category cross-referencequestions.data.referenceDelete(    questionObjId, "hasCategory", ObjectReference.uuids(categoryObjId)[0]);

// From the "San Francisco" JeopardyQuestion object, delete the "MUSEUMS" category cross-referenceawait questions.Data.ReferenceDelete(    from: questionObjId,    fromProperty: "hasCategory",    to: categoryObjId);

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

# In the "San Francisco" JeopardyQuestion object, set the "hasCategory" cross-reference only to "MUSEUMS"questions = client.collections.use("JeopardyQuestion")questions.data.reference_replace(    from_uuid=question_obj_id,    from_property="hasCategory",    to=category_obj_id)

JavaScript/TypeScript

// In the "San Francisco" JeopardyQuestion object, set the "hasCategory" cross-reference only to "MUSEUMS"const questions = client.collections.use("JeopardyQuestion")await questions.data.referenceReplace({  fromUuid: questionObjectId,  fromProperty: 'hasCategory',  to: catogoryObjectId})

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)

Java

// In the "San Francisco" JeopardyQuestion object, set the "hasCategory"// cross-reference only to "MUSEUMS"questions.data.referenceReplace(    questionObjId, "hasCategory", ObjectReference.uuids(categoryObjId)[0]);

// In the "San Francisco" JeopardyQuestion object, set the "hasCategory" cross-reference only to "MUSEUMS"await questions.Data.ReferenceReplace(    from: questionObjId,    fromProperty: "hasCategory",    to: [categoryObjId]);

Connect to Weaviate
References: REST - /v1/objects
Retrieve the cross-reference as a part of a query.

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.

Define a cross-reference property

Add a cross-reference property

Create an object with a cross-reference

Add a one-way cross-reference

Add two-way cross-references

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

Read cross-references

Delete a cross-reference

Update a cross-reference

Related pages

Questions and feedback