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 Client v4

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

Python Client v3

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

  API docs  Deprecated (v3)

JS/TS Client v3

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 Client v4

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

  API docs

Python Client v3

# Add the "hasQuestion" cross-reference property to the JeopardyCategory class
client.schema.property.create("JeopardyCategory", {
    "name": "hasQuestion",
    "dataType": ["JeopardyQuestion"]
})

  API docs  Deprecated (v3)

JS/TS Client v3

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

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

  API docs

JS/TS Client v2

// 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 Client v4

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

  API docs

Python Client v3

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

  API docs  Deprecated (v3)

JS/TS Client v3

const category = client.collections.get('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

JS/TS Client v2

response = await client.data
  .creator()
  .withClassName('JeopardyQuestion')
  .withId('f7344d30-7fe4-54dd-a233-fcccd4379d5c')
  .withProperties({
    'question': 'What tooling helps make Weaviate scalable?',
    'answer': 'Sharding, multi-tenancy, and replication',
    'hasCategory': [{  // Specify one or more cross-references
      'beacon': 'weaviate://localhost/583876f3-e293-5b5b-9839-03f455f14575',
    }],
  })
  .do();
console.log(JSON.stringify(response, null, 2));

Add a one-way cross-reference

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

Python Client v4

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

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

  API docs

Python Client v3

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

  API docs  Deprecated (v3)

JS/TS Client v3

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

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

  API docs

JS/TS Client v2

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

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 Client v4

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

Python Client v3

category_definition = {
    "class": "JeopardyCategory",
    "properties": [
        {"name": "title", "dataType": ["text"]},
    ],
}

client.schema.create_class(category_definition)

  API docs  Deprecated (v3)

JS/TS Client v3

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

  API docs

JS/TS Client v2

const jeopardyCategoryClass = {
  class: 'JeopardyCategory',
};

await client
  .schema
  .classCreator()
  .withClass(jeopardyCategoryClass)
  .do();

Create the JeopardyQuestion collection including the reference property to JeopardyCategory:

Python Client v4

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

Python Client v3

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)

  API docs  Deprecated (v3)

JS/TS Client v3

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

  API docs

JS/TS Client v2

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 Client v4

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

  API docs

Python Client v3

# Add the "hasQuestion" cross-reference property to the JeopardyCategory class
client.schema.property.create("JeopardyCategory", {
    "name": "hasQuestion",
    "dataType": ["JeopardyQuestion"]
})

  API docs  Deprecated (v3)

JS/TS Client v3

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

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

  API docs

JS/TS Client v2

// 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 Client v4

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

  API docs

Python Client v3

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

  API docs  Deprecated (v3)

JS/TS Client v3

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

await category.data.referenceAdd({
    fromUuid: catogoryObjectId,
    fromProperty: 'hasQuestion',
    to: questionObjectId
})

  API docs

JS/TS Client v2

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

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 Client v4

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)

  API docs

Python Client v3

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

  API docs  Deprecated (v3)

JS/TS Client v3

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

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

  API docs

JS/TS Client v2

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

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 Client v4

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

  API docs

Python Client v3

response = (
    client.query
    .get(
        "JeopardyQuestion",
        ["question", "hasCategory { ... on JeopardyCategory { title } }"],
    )
    .with_limit(2).do()
)

  API docs  Deprecated (v3)

JS/TS Client v3

const questions = client.collections.get("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 Client v4

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

  API docs

Python Client v3

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

  API docs  Deprecated (v3)

JS/TS Client v3

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

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

  API docs

JS/TS Client v2

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

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 Client v4

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

  API docs

Python Client v3

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

  API docs  Deprecated (v3)

JS/TS Client v3

// In the "San Francisco" JeopardyQuestion object, set the "hasCategory" cross-reference only to "MUSEUMS"
const questions = client.collections.get("JeopardyQuestion")

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

  API docs

JS/TS Client v2

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

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.