Merge pull request #1674 from BillFarber/task/opticGenerate-release-12.0.0-ea1

Optic Generation updates for release-12.0.0-ea1

Author: BillFarber

marklogic-client-api/src/main/java/com/marklogic/client/expression/CtsExpr.java

@@ -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;
@@ -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;
@@ -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.
   */
@@ -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);
@@ -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
   */

marklogic-client-api/src/main/java/com/marklogic/client/expression/PlanBuilder.java

@@ -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);
+}