Skip to content

Optic Generation updates for release-12.0.0-ea1 #1674

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 9, 2024
Merged

Optic Generation updates for release-12.0.0-ea1 #1674

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 88 additions & 88 deletions marklogic-client-api/src/main/java/com/marklogic/client/expression/CtsExpr.java
View file
Open in desktop

Large diffs are not rendered by default.

19 changes: 12 additions & 7 deletions marklogic-client-api/src/main/java/com/marklogic/client/expression/PlanBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
*/
public abstract class PlanBuilder implements PlanBuilderBase {
protected PlanBuilder(
CtsExpr cts, FnExpr fn, GeoExpr geo, JsonExpr json, MapExpr map, MathExpr math, RdfExpr rdf, SemExpr sem, SpellExpr spell, SqlExpr sql, XdmpExpr xdmp, XsExpr xs, RdtExpr rdt
CtsExpr cts, FnExpr fn, GeoExpr geo, JsonExpr json, MapExpr map, MathExpr math, RdfExpr rdf, SemExpr sem, SpellExpr spell, SqlExpr sql, VecExpr vec, XdmpExpr xdmp, XsExpr xs, RdtExpr rdt
) {
this.cts = cts;
this.fn = fn;
Expand All @@ -39,6 +39,7 @@ protected PlanBuilder(
this.sem = sem;
this.spell = spell;
this.sql = sql;
this.vec = vec;
this.xdmp = xdmp;
this.xs = xs;
this.rdt = rdt;
Expand Down Expand Up @@ -84,6 +85,10 @@ protected PlanBuilder(
* Builds expressions with sql server functions.
*/
public final SqlExpr sql;
/**
* Builds expressions with vec server functions.
*/
public final VecExpr vec;
/**
* Builds expressions with xdmp server functions.
*/
Expand Down Expand Up @@ -312,13 +317,13 @@ protected PlanBuilder(
public abstract PlanColumn viewCol(XsStringVal view, XsStringVal column);
/**
* Specifies a name for adding a fragment id column to the row set identifying the source documents for the rows from a view, lexicons or triples. The only use for the fragment id is joining other rows from the same document, the document uri, or the document content. The fragment id is only useful during execution of the query and not after.
* @param column the column value.
* @param column The name of the fragment ID column.
* @return a PlanSystemColumn object
*/
public abstract PlanSystemColumn fragmentIdCol(String column);
/**
* Specifies a name for adding a fragment id column to the row set identifying the source documents for the rows from a view, lexicons or triples. The only use for the fragment id is joining other rows from the same document, the document uri, or the document content. The fragment id is only useful during execution of the query and not after.
* @param column the column value.
* @param column The name of the fragment ID column.
* @return a PlanSystemColumn object
*/
public abstract PlanSystemColumn fragmentIdCol(XsStringVal column);
Expand Down Expand Up @@ -1781,26 +1786,26 @@ public interface ModifyPlan extends PreparePlan, PlanBuilderBase.ModifyPlanBase
public abstract ModifyPlan orderBy(PlanSortKeySeq keys);
/**
* Add an error-handler to the Optic Pipeline to catch Optic Update runtime errors. The runtime errors are added in the errors column. If no error occurred the value of the error column is null. When added, the error-handler should be the last operator before op:result.
* @param action Valid options are: "fail" - stop procesisng and "continue" - add an error to the error column and continue processing.
* @param action Valid options are: "fail" - stop processing and "continue" - add an error to the error column and continue processing.
* @return a ModifyPlan object
*/
public abstract ModifyPlan onError(String action);
/**
* Add an error-handler to the Optic Pipeline to catch Optic Update runtime errors. The runtime errors are added in the errors column. If no error occurred the value of the error column is null. When added, the error-handler should be the last operator before op:result.
* @param action Valid options are: "fail" - stop procesisng and "continue" - add an error to the error column and continue processing.
* @param action Valid options are: "fail" - stop processing and "continue" - add an error to the error column and continue processing.
* @return a ModifyPlan object
*/
public abstract ModifyPlan onError(XsStringVal action);
/**
* Add an error-handler to the Optic Pipeline to catch Optic Update runtime errors. The runtime errors are added in the errors column. If no error occurred the value of the error column is null. When added, the error-handler should be the last operator before op:result.
* @param action Valid options are: "fail" - stop procesisng and "continue" - add an error to the error column and continue processing.
* @param action Valid options are: "fail" - stop processing and "continue" - add an error to the error column and continue processing.
* @param errorColumn An optional error column which is not used in the plan. If this parameter is not passed in 'sys.errors' is used. See {@link PlanBuilder#col(XsStringVal)}
* @return a ModifyPlan object
*/
public abstract ModifyPlan onError(String action, String errorColumn);
/**
* Add an error-handler to the Optic Pipeline to catch Optic Update runtime errors. The runtime errors are added in the errors column. If no error occurred the value of the error column is null. When added, the error-handler should be the last operator before op:result.
* @param action Valid options are: "fail" - stop procesisng and "continue" - add an error to the error column and continue processing.
* @param action Valid options are: "fail" - stop processing and "continue" - add an error to the error column and continue processing.
* @param errorColumn An optional error column which is not used in the plan. If this parameter is not passed in 'sys.errors' is used. See {@link PlanBuilder#col(XsStringVal)}
* @return a ModifyPlan object
*/
Expand Down
204 changes: 204 additions & 0 deletions marklogic-client-api/src/main/java/com/marklogic/client/expression/VecExpr.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,204 @@
/*
* Copyright (c) 2024 MarkLogic Corporation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

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.ServerExpression;

// IMPORTANT: Do not edit. This file is generated.

/**
* Builds expressions to call functions in the vec server library for a row
* pipeline.
*/
public interface VecExpr {
public ServerExpression add(ServerExpression vector1, ServerExpression vector2);
/**
* Constructs a vector result by decoding the base64 binary input.
*
* <a name="ml-server-type-base64-decode"></a>

* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:base64-decode" target="mlserverdoc">vec:base64-decode</a> server function.
* @param base64Vector The base64 binary encoded string vector to decode. (of <a href="{@docRoot}/doc-files/types/xs_string.html">xs:string</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a> 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.
*
* <a name="ml-server-type-base64-encode"></a>

* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:base64-encode" target="mlserverdoc">vec:base64-encode</a> server function.
* @param vector1 The vector to base64 encode. (of <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_string.html">xs:string</a> server data type
*/
public ServerExpression base64Encode(ServerExpression vector1);
/**
* Returns the cosine similarity between two vectors. The vectors must be of the same dimension.
*
* <a name="ml-server-type-cosine-similarity"></a>

* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:cosine-similarity" target="mlserverdoc">vec:cosine-similarity</a> server function.
* @param vector1 The vector from which to calculate the cosine similarity with vector2. (of <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a>)
* @param vector2 The vector from which to calculate the cosine similarity with vector1. (of <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_double.html">xs:double</a> server data type
*/
public ServerExpression cosineSimilarity(ServerExpression vector1, ServerExpression vector2);
/**
* Returns the dimension of the vector passed in.
*
* <a name="ml-server-type-dimension"></a>

* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:dimension" target="mlserverdoc">vec:dimension</a> server function.
* @param vector1 The vector to find the dimension of. (of <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_unsignedInt.html">xs:unsignedInt</a> 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.
*
* <a name="ml-server-type-dot-product"></a>

* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:dot-product" target="mlserverdoc">vec:dot-product</a> server function.
* @param vector1 The vector from which to calculate the dot product with vector2. (of <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a>)
* @param vector2 The vector from which to calculate the dot product with vector1. (of <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_double.html">xs:double</a> 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.
*
* <a name="ml-server-type-euclidean-distance"></a>

* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:euclidean-distance" target="mlserverdoc">vec:euclidean-distance</a> server function.
* @param vector1 The vector from which to calculate the Euclidean distance to vector2. (of <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a>)
* @param vector2 The vector from which to calculate the Euclidean distance to vector1. (of <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_double.html">xs:double</a> server data type
*/
public ServerExpression euclideanDistance(ServerExpression vector1, ServerExpression vector2);
/**
* Returns the element at the k-th index of the vector.
*
* <a name="ml-server-type-get"></a>

* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:get" target="mlserverdoc">vec:get</a> server function.
* @param vector1 The vector to grab the k-th element of. (of <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a>)
* @param k The zero-based index of vector1 to return. (of <a href="{@docRoot}/doc-files/types/xs_unsignedInt.html">xs:unsignedInt</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_float.html">xs:float</a> server data type
*/
public ServerExpression get(ServerExpression vector1, ServerExpression k);
/**
* Returns the magnitude of the vector.
*
* <a name="ml-server-type-magnitude"></a>

* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:magnitude" target="mlserverdoc">vec:magnitude</a> server function.
* @param vector1 The vector to find the magnitude of. (of <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_double.html">xs:double</a> server data type
*/
public ServerExpression magnitude(ServerExpression vector1);
/**
* Returns the vector passed in, normalized to a length of 1.
*
* <a name="ml-server-type-normalize"></a>

* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:normalize" target="mlserverdoc">vec:normalize</a> server function.
* @param vector1 The vector to normalize. (of <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a> server data type
*/
public ServerExpression normalize(ServerExpression vector1);
public ServerExpression subtract(ServerExpression vector1, ServerExpression vector2);
/**
* Returns a subvector of the input vector, starting at the specified index and with the specified length.
*
* <a name="ml-server-type-subvector"></a>

* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:subvector" target="mlserverdoc">vec:subvector</a> server function.
* @param vector The input vector. (of <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a>)
* @param start The starting index of the subvector (inclusive). (of <a href="{@docRoot}/doc-files/types/xs_unsignedInt.html">xs:unsignedInt</a>)
* @param length The length of the subvector. (of <a href="{@docRoot}/doc-files/types/xs_unsignedInt.html">xs:unsignedInt</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a> server data type
*/
public ServerExpression subvector(ServerExpression vector, ServerExpression start, ServerExpression length);
/**
* Returns a vector value.
*
* <a name="ml-server-type-vector"></a>

* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:vector" target="mlserverdoc">vec:vector</a> server function.
* @param values The values to create the vector from. Can be a sequence or json:array of integer or floating-point numbers. (of <a href="{@docRoot}/doc-files/types/xs_anyAtomicType.html">xs:anyAtomicType</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/vec_vector.html">vec:vector</a> server data type
*/
public ServerExpression vector(ServerExpression values);
/**
* A helper function that returns the hybrid score using a cts:score and a vector similarity function. You can tune the effect of the vector similarity on the score using the "similarity-weight" option.
* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:vector-score" target="mlserverdoc">vec:vector-score</a> server function.
* @param score The cts:score of the matching document. (of <a href="{@docRoot}/doc-files/types/xs_unsignedInt.html">xs:unsignedInt</a>)
* @param similarity The similarity between the vector in the matching document and the query vector. The result of a call to ovec:cosine-similarity() or op.vec.cosineSimilarity(). In the case that the vectors are normalized, pass ovec:dot-product() or op.vec.dotProduct(). Note that vec:euclideanDistance() should not be used here. (of <a href="{@docRoot}/doc-files/types/xs_double.html">xs:double</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_unsignedInt.html">xs:unsignedInt</a> server data type
*/
public ServerExpression vectorScore(ServerExpression score, double similarity);
/**
* A helper function that returns the hybrid score using a cts:score and a vector similarity function. You can tune the effect of the vector similarity on the score using the "similarity-weight" option.
*
* <a name="ml-server-type-vector-score"></a>

* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:vector-score" target="mlserverdoc">vec:vector-score</a> server function.
* @param score The cts:score of the matching document. (of <a href="{@docRoot}/doc-files/types/xs_unsignedInt.html">xs:unsignedInt</a>)
* @param similarity The similarity between the vector in the matching document and the query vector. The result of a call to ovec:cosine-similarity() or op.vec.cosineSimilarity(). In the case that the vectors are normalized, pass ovec:dot-product() or op.vec.dotProduct(). Note that vec:euclideanDistance() should not be used here. (of <a href="{@docRoot}/doc-files/types/xs_double.html">xs:double</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_unsignedInt.html">xs:unsignedInt</a> server data type
*/
public ServerExpression vectorScore(ServerExpression score, ServerExpression similarity);
/**
* A helper function that returns the hybrid score using a cts:score and a vector similarity function. You can tune the effect of the vector similarity on the score using the "similarity-weight" option.
* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:vector-score" target="mlserverdoc">vec:vector-score</a> server function.
* @param score The cts:score of the matching document. (of <a href="{@docRoot}/doc-files/types/xs_unsignedInt.html">xs:unsignedInt</a>)
* @param similarity The similarity between the vector in the matching document and the query vector. The result of a call to ovec:cosine-similarity() or op.vec.cosineSimilarity(). In the case that the vectors are normalized, pass ovec:dot-product() or op.vec.dotProduct(). Note that vec:euclideanDistance() should not be used here. (of <a href="{@docRoot}/doc-files/types/xs_double.html">xs:double</a>)
* @param similarityWeight The weight of the vector similarity on the score. The default value is 1.0. Values less than or equal to zero have no effect. (of <a href="{@docRoot}/doc-files/types/xs_double.html">xs:double</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_unsignedInt.html">xs:unsignedInt</a> server data type
*/
public ServerExpression vectorScore(ServerExpression score, double similarity, double similarityWeight);
/**
* A helper function that returns the hybrid score using a cts:score and a vector similarity function. You can tune the effect of the vector similarity on the score using the "similarity-weight" option.
* <p>
* Provides a client interface to the <a href="http://docs.marklogic.com/vec:vector-score" target="mlserverdoc">vec:vector-score</a> server function.
* @param score The cts:score of the matching document. (of <a href="{@docRoot}/doc-files/types/xs_unsignedInt.html">xs:unsignedInt</a>)
* @param similarity The similarity between the vector in the matching document and the query vector. The result of a call to ovec:cosine-similarity() or op.vec.cosineSimilarity(). In the case that the vectors are normalized, pass ovec:dot-product() or op.vec.dotProduct(). Note that vec:euclideanDistance() should not be used here. (of <a href="{@docRoot}/doc-files/types/xs_double.html">xs:double</a>)
* @param similarityWeight The weight of the vector similarity on the score. The default value is 1.0. Values less than or equal to zero have no effect. (of <a href="{@docRoot}/doc-files/types/xs_double.html">xs:double</a>)
* @return a server expression with the <a href="{@docRoot}/doc-files/types/xs_unsignedInt.html">xs:unsignedInt</a> server data type
*/
public ServerExpression vectorScore(ServerExpression score, ServerExpression similarity, ServerExpression similarityWeight);
}
Loading