Vector Functions

This chapter describes the supported vector functions:

• Overview of Vectors
• Vector constructors
• Vector arithmetic
• Vector score

Overview of Vectors

In simple terms, vectors are arrays of numbers that represent a specific point in an N-dimensional space. Each point captures a given piece of data for a specific model. In large language models (LLM), these vectors encode various features of the data—such as the semantic meaning of words, sentences, or entire documents. You can perform various mathematical operations on vectors, including addition, scalar multiplication, and dot products, all of which play a key role in tasks like similarity searches.

Vector constructors

Vectors are essentially an array of numbers. To differentiate vectors from your native array of numbers, a special constructor is available, vec.vector.

  vec.vector([3.14, 1.59, 2.65])

The construction of this object is required when using the various operators for vectors.

MarkLogic Server represents each vector component using 32‑bit IEEE 754 single‑precision floating‑point values. Any double‑precision values (64‑bit) provided as input are automatically cast to single precision, which may result in loss of numeric detail. While this conversion typically has minimal impact on vector similarity operations, it can introduce small rounding differences that may affect the relative ordering of closely scored results in approximate nearest‑neighbor (ANN) searches.

Vector arithmetic

Vector operations may be performed between vectors of equal dimensions. This table describes the supported vector functions.

vec.add(
  vec.vector([3.14, 1.59, 2.65]),
  vec.vector([3.58, 9.79, 3.23])
)

vec.subtract(
  vec.vector([3.14, 1.59, 2.65]),
  vec.vector([3.58, 9.79, 3.23])
)

vec.dotProduct(
  vec.vector([3.14, 1.59, 2.65]),
  vec.vector([3.58, 9.79, 3.23])
)

vec.magnitude(
  vec.vector([3.14, 1.59, 2.65])
)

vec.normalize(
  vec.vector([3.14, 1.59, 2.65])
)

vec.euclideanDistance(
  vec.vector([3.14, 1.59, 2.65]),
  vec.vector([3.58, 9.79, 3.23])
)

vec.cosine(
  vec.vector([3.14, 1.59, 2.65]),
  vec.vector([3.58, 9.79, 3.23])
)

More information about various vector functions is available at docs.marklogic.com (XQY / SJS).

Limits on vector normalization

Vector normalization divides each component of a vector by its overall magnitude. As a result, normalization is sensitive to the numeric limits of 32‑bit floating‑point values:

• Extremely small vector magnitudes: If the computed magnitude is zero or underflows the minimum representable float value, then normalization fails and raises the VEC-MAGNITUDEZERO exception.

• Extremely large vector magnitudes: If the computed magnitude overflows the maximum representable float value, then the normalization result may collapse to zero, effectively producing a zero vector.

These conditions arise when vector components span a very large dynamic range, contain extreme values, or undergo heavy precision reduction before normalization.

Vector score

In a Retrieval Augmentation Generation (RAG) application, it is advantageous to combine ranking from different retrieval techniques to produce a "hybrid" or "fused" relevance rank. This approach is also know as Reciprocal Rank Fusion. The function vec.vectorScore is a helper function that combines a CTS score with the evaluated cosine distance to calculate a hybrid score. Assuming a document with an vector property of textEmbedding:

...
let score = cts.score(resultItem)
let distance = vec.cosineDistance(queryVector, vec.vector(resultItem.envelope.instance.emb))
let vectorScore = vec.vectorScore(score, distance)
vectorScore

• Refer to Use of an Embedding Model regarding definition of the function getVectorEquivalent(). It is important that you use the same LLM model for your embeddings and your query text.

This vectorScore, also known as Hybrid Score, can be used to rerank your search results. The impact of CTS score and vector distance can be tweaked using the weight parameters that can be supplied.

let weight = .5
let distanceWeight = 1
let vectorScore = vec.vectorScore(score, distance, weight, distanceWeight)
vectorScore

The vectorScore is computed using the formula weight * annScore + (1 - weight) * ctsScore.

weight is a floating-point value between 0 and 1. A higher value emphasizes the influence of vector distance, while a lower value emphasizes the influence of CTS score.

distanceWeight is a value that scales the value of distance. A higher value results in a lower annScore.

For indexed search of vectors using the Optic API, refer to Building Vector Queries.