com.marklogic.client.expression.VecExpr Maven / Gradle / Ivy
Show all versions of marklogic-client-api Show documentation
/*
* Copyright © 2024 MarkLogic Corporation. All Rights Reserved.
*/
package com.marklogic.client.expression;
import com.marklogic.client.type.XsAnyAtomicTypeSeqVal;
import com.marklogic.client.type.XsDoubleVal;
import com.marklogic.client.type.XsFloatVal;
import com.marklogic.client.type.XsStringVal;
import com.marklogic.client.type.XsUnsignedIntVal;
import com.marklogic.client.type.XsUnsignedLongVal;
import com.marklogic.client.type.ServerExpression;
// IMPORTANT: Do not edit. This file is generated.
/**
* Builds expressions to call functions in the vec server library for a row
* pipeline.
*
* @since 7.0.0; requires MarkLogic 12 or higher.
*/
public interface VecExpr {
/**
* Returns the sum of two vectors. The vectors must be of the same dimension.
*
*
*
* Provides a client interface to the vec:add server function.
* @param vector1 The first addend vector. (of vec:vector)
* @param vector2 The second addend vector. (of vec:vector)
* @return a server expression with the vec:vector server data type
*/
public ServerExpression add(ServerExpression vector1, ServerExpression vector2);
/**
* Returns a vector value by decoding the base64 encoded string input.
*
*
*
* Provides a client interface to the vec:base64-decode server function.
* @param base64Vector The base64 binary encoded string vector to decode. (of xs:string)
* @return a server expression with the vec:vector server data type
*/
public ServerExpression base64Decode(ServerExpression base64Vector);
/**
* 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 the vec:base64-encode server function.
* @param vector1 The vector to base64 encode. (of vec:vector)
* @return a server expression with the xs:string server data type
*/
public ServerExpression base64Encode(ServerExpression vector1);
/**
* Returns the cosine similarity between two vectors. The vectors must be of the same dimension.
*
*
*
* Provides a client interface to the vec:cosine-similarity server function.
* @param vector1 The vector from which to calculate the cosine similarity with vector2. (of vec:vector)
* @param vector2 The vector from which to calculate the cosine similarity with vector1. (of vec:vector)
* @return a server expression with the xs:double server data type
*/
public ServerExpression cosineSimilarity(ServerExpression vector1, ServerExpression vector2);
/**
* Returns the dimension of the vector passed in.
*
*
*
* Provides a client interface to the vec:dimension server function.
* @param vector1 The vector to find the dimension of. (of vec:vector)
* @return a server expression with the xs:unsignedInt server data type
*/
public ServerExpression dimension(ServerExpression vector1);
/**
* 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 the vec:dot-product server function.
* @param vector1 The vector from which to calculate the dot product with vector2. (of vec:vector)
* @param vector2 The vector from which to calculate the dot product with vector1. (of vec:vector)
* @return a server expression with the xs:double server data type
*/
public ServerExpression dotProduct(ServerExpression vector1, ServerExpression vector2);
/**
* Returns the Euclidean distance between two vectors. The vectors must be of the same dimension.
*
*
*
* Provides a client interface to the vec:euclidean-distance server function.
* @param vector1 The vector from which to calculate the Euclidean distance to vector2. (of vec:vector)
* @param vector2 The vector from which to calculate the Euclidean distance to vector1. (of vec:vector)
* @return a server expression with the xs:double server data type
*/
public ServerExpression euclideanDistance(ServerExpression vector1, ServerExpression vector2);
/**
* Returns the element at the k-th index of the vector.
*
*
*
* Provides a client interface to the vec:get server function.
* @param vector1 The vector to grab the k-th element of. (of vec:vector)
* @param k The zero-based index of vector1 to return. If k is greater than the number of elements in the vector, throw VEC-OUTOFBOUNDS. (of xs:unsignedInt)
* @return a server expression with the xs:float server data type
*/
public ServerExpression get(ServerExpression vector1, ServerExpression k);
/**
* Returns the magnitude of the vector.
*
*
*
* Provides a client interface to the vec:magnitude server function.
* @param vector1 The vector to find the magnitude of. (of vec:vector)
* @return a server expression with the xs:double server data type
*/
public ServerExpression magnitude(ServerExpression vector1);
/**
* Returns the vector passed in, normalized to a length of 1.
*
*
*
* Provides a client interface to the vec:normalize server function.
* @param vector1 The vector to normalize. (of vec:vector)
* @return a server expression with the vec:vector server data type
*/
public ServerExpression normalize(ServerExpression vector1);
/**
* Returns the difference of two vectors. The vectors must be of the same dimension.
*
*
*
* Provides a client interface to the vec:subtract server function.
* @param vector1 The minuend vector. (of vec:vector)
* @param vector2 The subtrahend vector. (of vec:vector)
* @return a server expression with the vec:vector server data type
*/
public ServerExpression subtract(ServerExpression vector1, ServerExpression vector2);
/**
* Returns a subvector of the input vector, starting at the specified index, with the specified length (optional).
*
*
*
* Provides a client interface to the vec:subvector server function.
* @param vector The input vector. (of vec:vector)
* @param start The zero-based index of the input vector from which to start (inclusive). (of xs:unsignedInt)
* @return a server expression with the vec:vector server data type
*/
public ServerExpression subvector(ServerExpression vector, ServerExpression start);
/**
* Returns a subvector of the input vector, starting at the specified index, with the specified length (optional).
*
* Provides a client interface to the vec:subvector server function.
* @param vector The input vector. (of vec:vector)
* @param start The zero-based index of the input vector from which to start (inclusive). (of xs:unsignedInt)
* @param length 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. (of xs:unsignedInt)
* @return a server expression with the vec:vector server data type
*/
public ServerExpression subvector(ServerExpression vector, ServerExpression start, ServerExpression length);
/**
* Returns a vector value.
*
*
*
* Provides a client interface to the vec:vector server function.
* @param values 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(). (of xs:anyAtomicType)
* @return a server expression with the vec:vector server data type
*/
public ServerExpression vector(ServerExpression values);
/**
* A helper function that returns a hybrid score using a cts score and a vector similarity calculation result. You can tune the effect of the vector similarity on the score using the similarityWeight option. The ideal value for similarityWeight depends on your application.
*
* Provides a client interface to the vec:vector-score server function.
* @param score The cts:score of the matching document. (of xs:unsignedInt)
* @param similarity The similarity between the vector in the matching document and the query vector. The result of a call to ovec:cosine-similarity(). In the case that the vectors are normalized, pass ovec:dot-product(). Note that vec:euclidean-distance() should not be used here. (of xs:double)
* @return a server expression with the xs:unsignedLong server data type
*/
public ServerExpression vectorScore(ServerExpression score, double similarity);
/**
* A helper function that returns a hybrid score using a cts score and a vector similarity calculation result. You can tune the effect of the vector similarity on the score using the similarityWeight option. The ideal value for similarityWeight depends on your application.
*
*
*
* Provides a client interface to the vec:vector-score server function.
* @param score The cts:score of the matching document. (of xs:unsignedInt)
* @param similarity The similarity between the vector in the matching document and the query vector. The result of a call to ovec:cosine-similarity(). In the case that the vectors are normalized, pass ovec:dot-product(). Note that vec:euclidean-distance() should not be used here. (of xs:double)
* @return a server expression with the xs:unsignedLong server data type
*/
public ServerExpression vectorScore(ServerExpression score, ServerExpression similarity);
/**
* A helper function that returns a hybrid score using a cts score and a vector similarity calculation result. You can tune the effect of the vector similarity on the score using the similarityWeight option. The ideal value for similarityWeight depends on your application.
*
* Provides a client interface to the vec:vector-score server function.
* @param score The cts:score of the matching document. (of xs:unsignedInt)
* @param similarity The similarity between the vector in the matching document and the query vector. The result of a call to ovec:cosine-similarity(). In the case that the vectors are normalized, pass ovec:dot-product(). Note that vec:euclidean-distance() should not be used here. (of xs:double)
* @param similarityWeight The weight of the vector similarity on the score. The default value is 0.1. If 0.0 is passed in, vector similarity has no effect. If passed a value less than 0.0 or greater than 1.0, throw VEC-VECTORSCORE. (of xs:double)
* @return a server expression with the xs:unsignedLong server data type
*/
public ServerExpression vectorScore(ServerExpression score, double similarity, double similarityWeight);
/**
* A helper function that returns a hybrid score using a cts score and a vector similarity calculation result. You can tune the effect of the vector similarity on the score using the similarityWeight option. The ideal value for similarityWeight depends on your application.
*
* Provides a client interface to the vec:vector-score server function.
* @param score The cts:score of the matching document. (of xs:unsignedInt)
* @param similarity The similarity between the vector in the matching document and the query vector. The result of a call to ovec:cosine-similarity(). In the case that the vectors are normalized, pass ovec:dot-product(). Note that vec:euclidean-distance() should not be used here. (of xs:double)
* @param similarityWeight The weight of the vector similarity on the score. The default value is 0.1. If 0.0 is passed in, vector similarity has no effect. If passed a value less than 0.0 or greater than 1.0, throw VEC-VECTORSCORE. (of xs:double)
* @return a server expression with the xs:unsignedLong server data type
*/
public ServerExpression vectorScore(ServerExpression score, ServerExpression similarity, ServerExpression similarityWeight);
}