MarkLogic Node.js Client API

Namespace: vec

planBuilder. vec

Builds expressions to call functions in the vec server library for a row pipeline.
Since:
  • 3.5.0

Methods

add(vector1, vector2) → {VecVector}

Returns the sum of two vectors. The vectors must be of the same dimension. Provides a client interface to a server function. See vec.add
Parameters:
Name Type Argument Description
vector1 VecVector <optional>
 The first addend vector.
vector2 VecVector <optional>
 The second addend vector.
Since:
  • 3.5.0
Returns:
Type
VecVector

base64Decode(base64Vector) → {VecVector}

Returns a vector value by decoding the base64 encoded string input. Provides a client interface to a server function. See vec.base64Decode
Parameters:
Name Type Argument Description
base64Vector XsString <optional>
 The base64 binary encoded string vector to decode.
Since:
  • 3.5.0
Returns:
Type
VecVector

base64Encode(vector1) → {XsString}

Returns the base64 encoding of the vector. Useful for compressing a high-dimensional float vector represented as a string into fewer characters. Provides a client interface to a server function. See vec.base64Encode
Parameters:
Name Type Argument Description
vector1 VecVector <optional>
 The vector to base64 encode.
Since:
  • 3.5.0
Returns:
Type
XsString

cosine(vector1, vector2) → {XsDouble}

Returns the cosine of the angle between two vectors. The vectors must be of the same dimension. Provides a client interface to a server function. See vec.cosine
Parameters:
Name Type Argument Description
vector1 VecVector <optional>
 The vector from which to calculate the cosine with vector2.
vector2 VecVector <optional>
 The vector from which to calculate the cosine with vector1.
Since:
  • 3.7.0
Returns:
Type
XsDouble

cosineDistance(vector1, vector2) → {XsDouble}

Returns the cosine distance between two vectors. The vectors must be of the same dimension. Provides a client interface to a server function. See vec.cosineDistance
Parameters:
Name Type Argument Description
vector1 VecVector <optional>
 The vector from which to calculate the cosine distance to vector2.
vector2 VecVector <optional>
 The vector from which to calculate the cosine distance to vector1.
Since:
  • 3.7.0
Returns:
Type
XsDouble

dimension(vector1) → {XsUnsignedInt}

Returns the dimension of the vector passed in. Provides a client interface to a server function. See vec.dimension
Parameters:
Name Type Argument Description
vector1 VecVector <optional>
 The vector to find the dimension of.
Since:
  • 3.5.0
Returns:
Type
XsUnsignedInt

dotProduct(vector1, vector2) → {XsDouble}

Returns the dot product between two vectors. The vectors must be of the same dimension. Use this function to calculate similarity between vectors if you are certain they are both of magnitude 1. Provides a client interface to a server function. See vec.dotProduct
Parameters:
Name Type Argument Description
vector1 VecVector <optional>
 The vector from which to calculate the dot product with vector2.
vector2 VecVector <optional>
 The vector from which to calculate the dot product with vector1.
Since:
  • 3.5.0
Returns:
Type
XsDouble

euclideanDistance(vector1, vector2) → {XsDouble}

Returns the Euclidean distance between two vectors. The vectors must be of the same dimension. Provides a client interface to a server function. See vec.euclideanDistance
Parameters:
Name Type Argument Description
vector1 VecVector <optional>
 The vector from which to calculate the Euclidean distance to vector2.
vector2 VecVector <optional>
 The vector from which to calculate the Euclidean distance to vector1.
Since:
  • 3.5.0
Returns:
Type
XsDouble

get(vector1, k) → {XsFloat}

Returns the element at the k-th index of the vector. Provides a client interface to a server function. See vec.get
Parameters:
Name Type Argument Description
vector1 VecVector <optional>
 The vector to grab the k-th element of.
k XsUnsignedInt <optional>
 The zero-based index of vector1 to return. If k is greater than the number of elements in the vector, throw VEC-OUTOFBOUNDS.
Since:
  • 3.5.0
Returns:
Type
XsFloat

magnitude(vector1) → {XsDouble}

Returns the magnitude of the vector. Provides a client interface to a server function. See vec.magnitude
Parameters:
Name Type Argument Description
vector1 VecVector <optional>
 The vector to find the magnitude of.
Since:
  • 3.5.0
Returns:
Type
XsDouble

normalize(vector1) → {VecVector}

Returns the vector passed in, normalized to a length of 1. Provides a client interface to a server function. See vec.normalize
Parameters:
Name Type Argument Description
vector1 VecVector <optional>
 The vector to normalize.
Since:
  • 3.5.0
Returns:
Type
VecVector

subtract(vector1, vector2) → {VecVector}

Returns the difference of two vectors. The vectors must be of the same dimension. Provides a client interface to a server function. See vec.subtract
Parameters:
Name Type Argument Description
vector1 VecVector <optional>
 The minuend vector.
vector2 VecVector <optional>
 The subtrahend vector.
Since:
  • 3.5.0
Returns:
Type
VecVector

subvector(vector, start, length) → {VecVector}

Returns a subvector of the input vector, starting at the specified index, with the specified length (optional). Provides a client interface to a server function. See vec.subvector
Parameters:
Name Type Argument Description
vector VecVector <optional>
 The input vector.
start XsUnsignedInt <optional>
 The zero-based index of the input vector from which to start (inclusive).
length XsUnsignedInt <optional>
 The length of the subvector. If not provided, returns a subvector beginning from index at start to the end of the input vector. If length is greater than the number of elements left in the input vector, throw VEC-OUTOFBOUNDS.
Since:
  • 3.5.0
Returns:
Type
VecVector

vector(values) → {VecVector}

Returns a vector value. Provides a client interface to a server function. See vec.vector
Parameters:
Name Type Argument Description
values XsAnyAtomicType <optional>
 The value(s) to create the vector from. Can be a sequence or json:array of integer or floating-point numbers. Also accepts a string that has the format of a JSON array of Numbers. Also accepts a string that was created by vec:base64-encode().
Since:
  • 3.5.0
Returns:
Type
VecVector

vectorScore(score, distance, distanceWeight, weight) → {XsUnsignedLong}

A helper function that returns a hybrid score using a cts score and a vector distance calculation result. You can tune the effect of the vector distance on the score using the distanceWeight option. The ideal value for distanceWeight depends on your application. The hybrid score is calculated using the formula: score = weight * annScore + (1 - weight) * ctsScore. - annScore is derived from the distance and distanceWeight, where a larger distanceWeight reduces the annScore for the same distance. - weight determines the contribution of the annScore and ctsScore to the final score. A weight of 0.5 balances both equally. This formula allows you to combine traditional cts scoring with vector-based distance scoring, providing a flexible way to rank results. Provides a client interface to a server function. See vec.vectorScore
Parameters:
Name Type Argument Description
score XsUnsignedInt <optional>
 The cts:score of the matching document.
distance XsDouble <optional>
 The distance between the vector in the matching document and the query vector. Examples, the result of a call to ovec:cosine-distance() or ovec:euclidean-distance().
distanceWeight XsDouble <optional>
 The weight of the vector distance on the annScore. This value is a positive coefficient that scales the distance. A larger distanceWeight produces a lower annScore for the same distance. The default value is 1.
weight XsDouble <optional>
 The weight of the annScore in the final hybrid score. This value is a coefficient between 0 and 1, where 0 gives full weight to the cts score and 1 gives full weight to the annScore. The default value is 0.5.
Since:
  • 3.5.0
Returns:
Type
XsUnsignedLong
Copyright (c) 2020 MarkLogic Corporation Documentation generated by JSDoc 4.0.0 on 2025-08-17T20:28:56-07:00 using the DocStrap template.