WeaviateEx.Types.Reference (WeaviateEx v0.7.4)

Cross-reference handling with multi-target vector support.

Represents a reference to another object in Weaviate, supporting both simple references and multi-target references for named vectors.

Simple Reference

ref = Reference.to("Author", "uuid-123")
# => %Reference{beacon: "weaviate://localhost/Author/uuid-123"}

Multi-Target Reference

When using named vectors, you can specify which target vectors to use:

ref = Reference.multi_target("Author", "uuid-123", ["title_vector", "content_vector"])
# => %Reference{beacon: "...", target_vectors: ["title_vector", "content_vector"]}

Summary

Types

t()

Functions

extract_collection(reference)

Extracts the collection name from the reference beacon.

extract_id(reference)

Extracts the object ID from the reference beacon.

from_beacon(beacon)

Creates a reference from a beacon URL string.

from_map(map)

Creates a Reference from a map (e.g., from API response).

multi_target(collection, id, target_vectors)

Creates a multi-target reference specifying which named vectors to use.

to(collection, id, opts \\ [])

Creates a reference to an object.

to_map(ref)

Converts the reference to a map for the Weaviate API.

Types

t()

@type t() :: %WeaviateEx.Types.Reference{
  beacon: String.t(),
  target_collection: String.t() | nil,
  target_vectors: [String.t()]
}

Functions

extract_collection(reference)

@spec extract_collection(t()) :: {:ok, String.t()} | {:error, String.t()}

Extracts the collection name from the reference beacon.

Examples

ref = Reference.to("Author", "uuid-123")
Reference.extract_collection(ref)
# => {:ok, "Author"}

extract_id(reference)

@spec extract_id(t()) :: {:ok, String.t()} | {:error, String.t()}

Extracts the object ID from the reference beacon.

Examples

ref = Reference.to("Author", "uuid-123")
Reference.extract_id(ref)
# => {:ok, "uuid-123"}

from_beacon(beacon)

@spec from_beacon(String.t()) :: t()

Creates a reference from a beacon URL string.

Automatically extracts and populates the target collection from the beacon.

Examples

Reference.from_beacon("weaviate://localhost/Author/uuid-123")
# => %Reference{beacon: "weaviate://localhost/Author/uuid-123", target_collection: "Author"}

Reference.from_beacon("weaviate://localhost/uuid-123")
# => %Reference{beacon: "weaviate://localhost/uuid-123", target_collection: nil}

from_map(map)

@spec from_map(map()) :: t()

Creates a Reference from a map (e.g., from API response).

Automatically extracts the target collection from the beacon.

Examples

Reference.from_map(%{"beacon" => "weaviate://localhost/Author/uuid-123"})
# => %Reference{beacon: "...", target_collection: "Author", target_vectors: []}

Reference.from_map(%{"beacon" => "weaviate://localhost/uuid-123"})
# => %Reference{beacon: "...", target_collection: nil, target_vectors: []}

multi_target(collection, id, target_vectors)

@spec multi_target(String.t(), String.t(), [String.t()]) :: t()

Creates a multi-target reference specifying which named vectors to use.

Use this when you need to specify target vectors for ref2vec-centroid or other multi-vector scenarios.

Examples

Reference.multi_target("Author", "uuid-123", ["title_vector", "content_vector"])

to(collection, id, opts \\ [])

@spec to(String.t(), String.t(), keyword()) :: t()

Creates a reference to an object.

Options

:target_vectors - List of named vectors to use (for multi-target references)

Examples

Reference.to("Author", "uuid-123")
# => %Reference{beacon: "weaviate://localhost/Author/uuid-123"}

Reference.to("Author", "uuid-123", target_vectors: ["title_vector"])
# => %Reference{beacon: "...", target_vectors: ["title_vector"]}

to_map(ref)

@spec to_map(t()) :: map()

Converts the reference to a map for the Weaviate API.

Examples

ref = Reference.to("Author", "uuid-123")
Reference.to_map(ref)
# => %{"beacon" => "weaviate://localhost/Author/uuid-123"}

ref = Reference.multi_target("Author", "uuid-123", ["title_vector"])
Reference.to_map(ref)
# => %{"beacon" => "...", "targetVectors" => ["title_vector"]}