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.

PythonJavaScript/TypeScript

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

)

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

Add a cross-reference property

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

PythonJavaScript/TypeScript

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

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

Create an object with a cross-reference

Specify a cross-reference when creating an object.

PythonJavaScript/TypeScript

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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)

Add a one-way cross-reference

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

PythonJavaScript/TypeScriptJavaGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

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

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

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:

PythonJavaScript/TypeScript

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

Create the JeopardyQuestion collection including the reference property to JeopardyCategory:

PythonJavaScript/TypeScript

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

Modify JeopardyCategory to add the reference to JeopardyQuestion:

PythonJavaScript/TypeScript

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

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

And add the cross-references:

PythonJavaScript/TypeScriptJavaGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

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.

PythonJavaScript/TypeScriptJavaGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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)

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

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

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)

Read cross-references

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

PythonJavaScript/TypeScript

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

Delete a cross-reference

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

PythonJavaScript/TypeScriptJavaGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

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.

PythonJavaScript/TypeScriptJavaGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

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