MLE-23473 Implement fromDocs

Add implementation of optic fromDocs to java client. Includes new context method to indicate current row for expressions.

Author: stevebio

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

@@ -247,6 +247,11 @@ protected PlanBuilder(
   */
   public abstract PatchBuilder patchBuilder(XsStringVal contextPath, Map<String,String> namespaces);
   /**
+  * Create column definitions which can be used in op:from-docs. Below functions are used to create column definitions. op:add-column, op:type, op:xpath, op:expr, op:nullable, op:default, op:dimension, op:coordinate-system, op:units, op:collation.
+  * @return  a PlanColumnBuilder object
+  */
+  public abstract PlanColumnBuilder columnBuilder();
+  /**
   * This function creates a placeholder for a literal value in an expression or as the offset or max for a limit. The op:result function throws in an error if the binding parameter does not specify a literal value for the parameter.
   * <p>
   * Provides a client interface to the <a href="http://docs.marklogic.com/op:param" target="mlserverdoc">op:param</a> server function.
@@ -403,6 +408,91 @@ protected PlanBuilder(
   */
   public abstract AccessPlan fromView(XsStringVal schema, XsStringVal view, XsStringVal qualifierName, PlanSystemColumn sysCols);
   /**
+  * This function dynamically maps semi-structured data (JSON/XML) into rows and columns without deploying a TDE template. It enables ad-hoc queries similar to Virtual Template Views but with additional flexibility, such as node output and advanced column customization.
+  * @param query  Query to select documents for row generation. The query can be a cts:query or a string as a shortcut for a cts:word-query.
+  * @param contextPath  XPath applied to each matched document; each result becomes a row.
+  * @param columnSpec  The column definitions created by using op:column-builder.
+  * @return  a AccessPlan object
+  */
+  public abstract AccessPlan fromDocs(String query, String contextPath, PlanColumnBuilder columnSpec);
+  /**
+  * This function dynamically maps semi-structured data (JSON/XML) into rows and columns without deploying a TDE template. It enables ad-hoc queries similar to Virtual Template Views but with additional flexibility, such as node output and advanced column customization.
+  * @param query  Query to select documents for row generation. The query can be a cts:query or a string as a shortcut for a cts:word-query.
+  * @param contextPath  XPath applied to each matched document; each result becomes a row.
+  * @param columnSpec  The column definitions created by using op:column-builder.
+  * @return  a AccessPlan object
+  */
+  public abstract AccessPlan fromDocs(CtsQueryExpr query, XsStringVal contextPath, PlanColumnBuilder columnSpec);
+  /**
+  * This function dynamically maps semi-structured data (JSON/XML) into rows and columns without deploying a TDE template. It enables ad-hoc queries similar to Virtual Template Views but with additional flexibility, such as node output and advanced column customization.
+  * @param query  Query to select documents for row generation. The query can be a cts:query or a string as a shortcut for a cts:word-query.
+  * @param contextPath  XPath applied to each matched document; each result becomes a row.
+  * @param columnSpec  The column definitions created by using op:column-builder.
+  * @param qualifier  Specifies a name for qualifying the column names in place of the combination of the schema and view names. Use cases for the qualifier include self joins. Using an empty string removes all qualification from the column names.
+  * @return  a AccessPlan object
+  */
+  public abstract AccessPlan fromDocs(String query, String contextPath, PlanColumnBuilder columnSpec, String qualifier);
+  /**
+  * This function dynamically maps semi-structured data (JSON/XML) into rows and columns without deploying a TDE template. It enables ad-hoc queries similar to Virtual Template Views but with additional flexibility, such as node output and advanced column customization.
+  * @param query  Query to select documents for row generation. The query can be a cts:query or a string as a shortcut for a cts:word-query.
+  * @param contextPath  XPath applied to each matched document; each result becomes a row.
+  * @param columnSpec  The column definitions created by using op:column-builder.
+  * @param qualifier  Specifies a name for qualifying the column names in place of the combination of the schema and view names. Use cases for the qualifier include self joins. Using an empty string removes all qualification from the column names.
+  * @return  a AccessPlan object
+  */
+  public abstract AccessPlan fromDocs(CtsQueryExpr query, String contextPath, PlanColumnBuilder columnSpec, String qualifier);
+  /**
+  * This function dynamically maps semi-structured data (JSON/XML) into rows and columns without deploying a TDE template. It enables ad-hoc queries similar to Virtual Template Views but with additional flexibility, such as node output and advanced column customization.
+  * @param query  Query to select documents for row generation. The query can be a cts:query or a string as a shortcut for a cts:word-query.
+  * @param contextPath  XPath applied to each matched document; each result becomes a row.
+  * @param columnSpec  The column definitions created by using op:column-builder.
+  * @param qualifier  Specifies a name for qualifying the column names in place of the combination of the schema and view names. Use cases for the qualifier include self joins. Using an empty string removes all qualification from the column names.
+  * @return  a AccessPlan object
+  */
+  public abstract AccessPlan fromDocs(CtsQueryExpr query, XsStringVal contextPath, PlanColumnBuilder columnSpec, XsStringVal qualifier);
+  /**
+  * This function dynamically maps semi-structured data (JSON/XML) into rows and columns without deploying a TDE template. It enables ad-hoc queries similar to Virtual Template Views but with additional flexibility, such as node output and advanced column customization.
+  * @param query  Query to select documents for row generation. The query can be a cts:query or a string as a shortcut for a cts:word-query.
+  * @param contextPath  XPath applied to each matched document; each result becomes a row.
+  * @param columnSpec  The column definitions created by using op:column-builder.
+  * @param qualifier  Specifies a name for qualifying the column names in place of the combination of the schema and view names. Use cases for the qualifier include self joins. Using an empty string removes all qualification from the column names.
+  * @param systemCol  An optional named fragment id column returned by op:fragment-id-col. One use case for fragment ids is in joins with lexicons or document content.
+  * @return  a AccessPlan object
+  */
+  public abstract AccessPlan fromDocs(String query, String contextPath, PlanColumnBuilder columnSpec, String qualifier, PlanSystemColumn systemCol);
+  /**
+  * This function dynamically maps semi-structured data (JSON/XML) into rows and columns without deploying a TDE template. It enables ad-hoc queries similar to Virtual Template Views but with additional flexibility, such as node output and advanced column customization.
+  * @param query  Query to select documents for row generation. The query can be a cts:query or a string as a shortcut for a cts:word-query.
+  * @param contextPath  XPath applied to each matched document; each result becomes a row.
+  * @param columnSpec  The column definitions created by using op:column-builder.
+  * @param qualifier  Specifies a name for qualifying the column names in place of the combination of the schema and view names. Use cases for the qualifier include self joins. Using an empty string removes all qualification from the column names.
+  * @param systemCol  An optional named fragment id column returned by op:fragment-id-col. One use case for fragment ids is in joins with lexicons or document content.
+  * @return  a AccessPlan object
+  */
+  public abstract AccessPlan fromDocs(CtsQueryExpr query, XsStringVal contextPath, PlanColumnBuilder columnSpec, XsStringVal qualifier, PlanSystemColumn systemCol);
+  /**
+  * This function dynamically maps semi-structured data (JSON/XML) into rows and columns without deploying a TDE template. It enables ad-hoc queries similar to Virtual Template Views but with additional flexibility, such as node output and advanced column customization.
+  * @param query  Query to select documents for row generation. The query can be a cts:query or a string as a shortcut for a cts:word-query.
+  * @param contextPath  XPath applied to each matched document; each result becomes a row.
+  * @param columnSpec  The column definitions created by using op:column-builder.
+  * @param qualifier  Specifies a name for qualifying the column names in place of the combination of the schema and view names. Use cases for the qualifier include self joins. Using an empty string removes all qualification from the column names.
+  * @param systemCol  An optional named fragment id column returned by op:fragment-id-col. One use case for fragment ids is in joins with lexicons or document content.
+  * @param namespaces  Namespaces prefix (key) and uri (value).
+  * @return  a AccessPlan object
+  */
+  public abstract AccessPlan fromDocs(String query, String contextPath, PlanColumnBuilder columnSpec, String qualifier, PlanSystemColumn systemCol, PlanNamespaceBindingsSeq namespaces);
+  /**
+  * This function dynamically maps semi-structured data (JSON/XML) into rows and columns without deploying a TDE template. It enables ad-hoc queries similar to Virtual Template Views but with additional flexibility, such as node output and advanced column customization.
+  * @param query  Query to select documents for row generation. The query can be a cts:query or a string as a shortcut for a cts:word-query.
+  * @param contextPath  XPath applied to each matched document; each result becomes a row.
+  * @param columnSpec  The column definitions created by using op:column-builder.
+  * @param qualifier  Specifies a name for qualifying the column names in place of the combination of the schema and view names. Use cases for the qualifier include self joins. Using an empty string removes all qualification from the column names.
+  * @param systemCol  An optional named fragment id column returned by op:fragment-id-col. One use case for fragment ids is in joins with lexicons or document content.
+  * @param namespaces  Namespaces prefix (key) and uri (value).
+  * @return  a AccessPlan object
+  */
+  public abstract AccessPlan fromDocs(CtsQueryExpr query, XsStringVal contextPath, PlanColumnBuilder columnSpec, XsStringVal qualifier, PlanSystemColumn systemCol, PlanNamespaceBindingsSeq namespaces);
+  /**
   * This function factory returns a new function that takes a name parameter and returns a sem:iri, prepending the specified base URI onto the name.
   * @param base  The base URI to be prepended to the name.
   * @return  a PlanPrefixer object
@@ -1130,6 +1220,11 @@ protected PlanBuilder(
   */
   public abstract PlanCase when(ServerExpression condition, ServerExpression... value);
   /**
+  * This helper function returns the node from the current processing row. It is to be used in op:xpath, to reference the 'current item' instead of a doc column.
+  * @return  a PlanContextExprCall object
+  */
+  public abstract PlanContextExprCall context();
+  /**
   * This function extracts a sequence of child nodes from a column with node values -- especially, the document nodes from a document join. The path is an XPath (specified as a string) to apply to each node to generate a sequence of nodes as an expression value.
   * <p>
   * Provides a client interface to the <a href="http://docs.marklogic.com/op:xpath" target="mlserverdoc">op:xpath</a> server function.
@@ -1167,6 +1262,24 @@ protected PlanBuilder(
   * @return  a server expression with the <a href="{@docRoot}/doc-files/types/node.html">node</a> server data type
   */
   public abstract ServerExpression xpath(PlanColumn column, ServerExpression path, PlanNamespaceBindingsSeq namespaceBindings);
+  /**
+  * This function extracts a sequence of child nodes from a server expression (such as op:context()) with node values. The path is an XPath (specified as a string) to apply to each node to generate a sequence of nodes as an expression value.
+  * <p>
+  * Provides a client interface to the <a href="http://docs.marklogic.com/op:xpath" target="mlserverdoc">op:xpath</a> server function.
+  * @param expression  The server expression (such as op:context()) from which to extract the child nodes.
+  * @param path  An XPath (specified as a string) to apply to each node.  (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/node.html">node</a> server data type
+  */
+  public abstract ServerExpression xpath(ServerExpression expression, String path);
+  /**
+  * This function extracts a sequence of child nodes from a server expression (such as op:context()) with node values. The path is an XPath to apply to each node to generate a sequence of nodes as an expression value.
+  * <p>
+  * Provides a client interface to the <a href="http://docs.marklogic.com/op:xpath" target="mlserverdoc">op:xpath</a> server function.
+  * @param expression  The server expression (such as op:context()) from which to extract the child nodes.
+  * @param path  An XPath to apply to each node.  (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/node.html">node</a> server data type
+  */
+public abstract ServerExpression xpath(ServerExpression expression, ServerExpression path);
   /**
   * This function constructs a JSON document with the root content, which must be exactly one JSON object or array node.
   * <p>

marklogic-client-api/src/main/java/com/marklogic/client/impl/ColumnBuilderImpl.java

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2010-2026 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.
+ */
+package com.marklogic.client.impl;
+
+import com.marklogic.client.type.PlanColumnBuilder;
+import com.marklogic.client.type.ServerExpression;
+import com.marklogic.client.type.XsStringVal;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+@SuppressWarnings("unchecked")
+class ColumnBuilderImpl extends BaseTypeImpl.BaseCallImpl implements PlanColumnBuilder, BaseTypeImpl.BaseArgImpl {
+
+	ColumnBuilderImpl() {
+		super("op", "suboperators",
+			new BaseTypeImpl.BaseArgImpl[]{
+				new BaseTypeImpl.BaseCallImpl("op", "column-builder", new BaseTypeImpl.BaseArgImpl[]{})
+			});
+	}
+
+	private ColumnBuilderImpl(List<BaseTypeImpl.BaseArgImpl> args) {
+		super("op", "suboperators", args.toArray(new BaseTypeImpl.BaseArgImpl[]{}));
+	}
+
+	public PlanColumnBuilder addColumn(String name) {
+		return addArg("add-column", name);
+	}
+
+	public PlanColumnBuilder addColumn(XsStringVal name) {
+		return addArg("add-column", name);
+	}
+
+	public PlanColumnBuilder xpath(String path) {
+		return addArg("xpath", path);
+	}
+
+	public PlanColumnBuilder xpath(XsStringVal path) {
+		return addArg("xpath", path);
+	}
+
+	public PlanColumnBuilder type(String type) {
+		return addArg("type", type);
+	}
+
+	public PlanColumnBuilder type(XsStringVal type) {
+		return addArg("type", type);
+	}
+
+	public PlanColumnBuilder nullable(boolean nullable) {
+		return addArg("nullable", new XsValueImpl.BooleanValImpl(nullable));
+	}
+
+	public PlanColumnBuilder expr(ServerExpression expression) {
+		return addArg("expr", expression);
+	}
+
+	public PlanColumnBuilder defaultValue(String value) {
+		return addArg("default", value);
+	}
+
+	public PlanColumnBuilder defaultValue(XsStringVal value) {
+		return addArg("default", value);
+	}
+
+	public PlanColumnBuilder collation(String collation) {
+		return addArg("collation", collation);
+	}
+
+	public PlanColumnBuilder collation(XsStringVal collation) {
+		return addArg("collation", collation);
+	}
+
+	public PlanColumnBuilder dimension(int dimension) {
+		return addArg("dimension", dimension);
+	}
+
+	public PlanColumnBuilder coordinateSystem(String coordinateSystem) {
+		return addArg("coordinate-system", coordinateSystem);
+	}
+
+	public PlanColumnBuilder coordinateSystem(XsStringVal coordinateSystem) {
+		return addArg("coordinate-system", coordinateSystem);
+	}
+
+	private PlanColumnBuilder addArg(String functionName, Object... args) {
+		BaseTypeImpl.BaseArgImpl newArg = new BaseTypeImpl.BaseCallImpl(
+			"op", functionName, makeArgs(args)
+		);
+		List<BaseTypeImpl.BaseArgImpl> newArgs = new ArrayList<>();
+		newArgs.addAll(Arrays.asList(getArgsImpl()));
+		newArgs.add(newArg);
+		return new ColumnBuilderImpl(newArgs);
+	}
+
+	private BaseTypeImpl.BaseArgImpl[] makeArgs(Object... args) {
+		List<BaseTypeImpl.BaseArgImpl> argList = new ArrayList<>();
+		for (Object arg : args) {
+			if (arg instanceof BaseTypeImpl.BaseArgImpl) {
+				argList.add((BaseTypeImpl.BaseArgImpl) arg);
+			} else {
+				// Use Literal for plain values (strings, numbers, etc.)
+				argList.add(new BaseTypeImpl.Literal(arg));
+			}
+		}
+		return argList.toArray(new BaseTypeImpl.BaseArgImpl[]{});
+	}
+}