Cross-references

Cross-references and query performance

Queries involving cross-references can be slower than queries that do not involve cross-references, especially at scale such as for multiple objects or complex queries.

At the first instance, we strongly encourage you to consider whether you can avoid using cross-references in your data schema. As a scalable AI-native database, Weaviate is well-placed to perform complex queries with vector, keyword and hybrid searches involving filters. You may benefit from rethinking your data schema to avoid cross-references where possible.

For example, instead of creating separate "Author" and "Book" collections with cross-references, consider embedding author information directly in Book objects and using searches and filters to find books by author characteristics.

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

)

  API docs

JS/TS

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

  API docs

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 created
category = client.collections.use("JeopardyCategory")
# category.config.add_reference(
category.config.add_reference(
    ReferenceProperty(
        name="hasQuestion",
        target_collection="JeopardyQuestion"
    )
)

  API docs

JS/TS

// Add the "hasQuestion" cross-reference property to the JeopardyCategory collection
const category = client.collections.use('JeopardyCategory')

await category.config.addReference({
  name: 'hasQuestion',
  targetCollection: 'JeopardyQuestion'
})

  API docs

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

  API docs

JS/TS

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)

  API docs

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
)

  API docs

JS/TS

const jeopardy = client.collections.use('JeopardyCategory')

await jeopardy.data.referenceAdd({
  fromProperty: 'hasCategory',
  fromUuid: questionObjectId,
  to: categoryObjectId,
})

  API docs

Java

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();

  API docs

Go

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)

  API docs

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

  API docs

JS/TS

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

  API docs

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

  API docs

JS/TS

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

  API docs

Modify JeopardyCategory to add the reference to JeopardyQuestion:

Python

from weaviate.classes.config import ReferenceProperty

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

  API docs

JS/TS

// Add the "hasQuestion" cross-reference property to the JeopardyCategory collection
const category = client.collections.use('JeopardyCategory')

await category.config.addReference({
  name: 'hasQuestion',
  targetCollection: 'JeopardyQuestion'
})

  API docs

And add the cross-references:

Python

# For the "San Francisco" JeopardyQuestion object, add a cross-reference to the "U.S. CITIES" JeopardyCategory object
questions = 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
)

  API docs

JS/TS

// For the "San Francisco" JeopardyQuestion object, add a cross-reference to the "U.S. CITIES" JeopardyCategory object
const 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
})

  API docs

Java

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();

  API docs

Go

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)

  API docs

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

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

Python

from weaviate.classes.data import DataReference

questions = 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)

  API docs

JS/TS

const questions = client.collections.use("JeopardyQuestion")

await questions.data.referenceAddMany(
  [{
    fromUuid: questionObjectId,
    fromProperty: 'hasCategory',
    to: catogoryObjectId1
  },{
    fromUuid: questionObjectId,
    fromProperty: 'hasCategory',
    to: catogoryObjectId2
  }]
)

  API docs

Java

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();

  API docs

Go

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)

  API docs

Read cross-references

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

Python

from weaviate.classes.query import QueryReference

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

  API docs

JS/TS

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

  API docs

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-reference
questions = client.collections.use("JeopardyQuestion")
questions.data.reference_delete(
    from_uuid=question_obj_id,
    from_property="hasCategory",
    to=category_obj_id
)

  API docs

JS/TS

// From the "San Francisco" JeopardyQuestion object, delete the "MUSEUMS" category cross-reference
const questions = client.collections.use("JeopardyQuestion")

await questions.data.referenceDelete({
  fromUuid: questionObjectId,
  fromProperty: 'hasCategory',
  to: catogoryObjectId
})

  API docs

Java

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();

  API docs

Go

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)

  API docs

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
)

  API docs

JS/TS

// 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
})

  API docs

Java

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();

  API docs

Go

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)

  API docs

Related pages

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

Questions and feedback

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

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.