Namespace: ModifyPlan

planBuilder. ModifyPlan

ModifyPlan objects have methods and inherit planBuilder.PreparePlan methods.

Since:

2.1.1

Methods

bind(columns) → {planBuilder.ModifyPlan}

This function adds new columns or modifies existing columns based on expressions while preserving existing unmodified columns in the row set. Provides a client interface to a server function. See ModifyPlan.prototype.bind

Parameters:

Name	Type	Argument	Description
`columns`	PlanExprCol	<optional>	The op:as calls that specify the column name and the expression that constructs the column values.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

bindAs(column, expression) → {planBuilder.ModifyPlan}

This function is deprecated in favor of the bind() function and will not be supported in MarkLogic 11. This function adds a column based on an expression without altering the existing columns in the row set. Provides a client interface to a server function. See ModifyPlan.prototype.bindAs

Parameters:

Name	Type	Argument	Description
`column`	PlanColumnName	<optional>	The name of the column to be defined.
`expression`	Item	<optional>	The expression that specifies the value the column in the row.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

except(right) → {planBuilder.ModifyPlan}

This method restricts the left row set to rows where a row with the same columns and values doesn't exist in the right row set. Provides a client interface to a server function. See ModifyPlan.prototype.except

Parameters:

Name	Type	Argument	Description
`right`	PlanModifyPlan	<optional>	The row set from the right view.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

existsJoin(right, keys, condition) → {planBuilder.ModifyPlan}

This method is a filtering join that filters based on whether the join exists or not but doesn't add any columns. Provides a client interface to a server function. See ModifyPlan.prototype.existsJoin

Parameters:

Name	Type	Argument	Description
`right`	PlanModifyPlan	<optional>	The row set from the right view.
`keys`	PlanJoinKey	<optional>	The equijoin from one or more calls to the op:on function.
`condition`	XsBoolean	<optional>	A boolean expression that filters the join output rows.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

facetBy(keys, countCol) → {planBuilder.ModifyPlan}

This method counts values for multiple grouping key columns. Provides a client interface to a server function. See ModifyPlan.prototype.facetBy

Parameters:

Name	Type	Argument	Description
`keys`	PlanNamedGroupingKey	<optional>	This parameter specifies the list of column keys for performing counts. For each column, the operation determines the unique values of that column and produces a separate count for the rows with that value. A column can be named with a string or a column parameter function such as op:col or constructed from an expression with the op:as function. The facet can be named by providing a op:named-group that takes exactly one column.
`countCol`	PlanExprColName	<optional>	Specifies what to count over the rows for each unique value of each key column. By default, the operation counts the rows. To count the values of a column instead, specify the column to count with this parameter. To count documents, specify a fragment id column with op:fragment-id-col.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

groupBy(keys, aggregates) → {planBuilder.ModifyPlan}

This method collapses a group of rows into a single row. Provides a client interface to a server function. See ModifyPlan.prototype.groupBy

Parameters:

Name	Type	Argument	Description
`keys`	PlanExprColName	<optional>	This parameter specifies the columns used to determine the groups. Rows with the same values in these columns are consolidated into a single group. The columns can be existing columns or new columns created by an expression specified with op:as. The rows produced by the group by operation include the key columns. Specify an empty sequence to create a single group for all of the rows in the row set.
`aggregates`	PlanAggregateColName	<optional>	This parameter specifies either new columns for aggregate functions over the rows in the group or columndefs that are constant for the group. The aggregate library functions are listed below.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

groupByUnion(keys, aggregates) → {planBuilder.ModifyPlan}

This method performs the union of multiple group-by operations on a row set. Provides a client interface to a server function. See ModifyPlan.prototype.groupByUnion

Parameters:

Name	Type	Argument	Description
`keys`	PlanGroupingKey	<optional>	The sets of grouping keys. The keys for each group are specified with the op:group, op:rollup, or op:cube functions. Each group must have a unique set of keys but multiple groups can have the same key. As a convenience, a group with a single key can specify the name of the key column with a string or a column parameter function such as op:col or constructed from an expression with op:as. The rows produced by the group-by-union operation include the key columns from each group. A group can be empty to group over all of the rows in the row set.
`aggregates`	PlanAggregateColName	<optional>	This parameter specifies either columns to sample or aggregate functions to apply to a column for all of the rows in the group. Sampled columns can be existing columns or new columns created by an expression specified with op:as. Often a sampled column might have a constant value within the group such as a title or label closely associated with a numeric identifier used as the grouping key.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

groupToArrays(keys, aggregates) → {planBuilder.ModifyPlan}

This method performs multiple group-by operations on a row set and produces a single row with a column for each group having an array value whose items are the rows for the group. Each item is an object with properties for the group keys and aggregates. Provides a client interface to a server function. See ModifyPlan.prototype.groupToArrays

Parameters:

Name	Type	Argument	Description
`keys`	PlanNamedGroupingKey	<optional>	The sets of grouping keys. Each group is specified with the op:named-group function. Each group must have a unique set of keys but multiple groups can have the same key. As a convenience, the parameter also accepts unnamed groups with the op:group, op:rollup, or op:cube functions or (for a group with a single key) a column named with a string or a column parameter function such as op:col or constructed from an expression with the op:as function. The row objects produced by the group-to-arrays operation include the key columns from each group. A group can be empty to group over all of the rows in the row set.
`aggregates`	PlanAggregateColName	<optional>	This parameter specifies either columns to sample or aggregate functions to apply to a column for all of the rows in the group. Sampled columns can be existing columns or new columns created by an expression specified with op:as. Often a sampled column might have a constant value within the group such as a title or label closely associated with a numeric identifier used as the grouping key.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

intersect(right) → {planBuilder.ModifyPlan}

This method restricts the left row set to rows where a row with the same columns and values exists in the right row set. Provides a client interface to a server function. See ModifyPlan.prototype.intersect

Parameters:

Name	Type	Argument	Description
`right`	PlanModifyPlan	<optional>	The row set from the right view.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

joinCrossProduct(right, condition) → {planBuilder.ModifyPlan}

This method yields one output row set that concatenates every left row with every right row. Matches other than equality matches (for instance, greater-than comparisons between keys) can be implemented with a condition on the cross product. Provides a client interface to a server function. See ModifyPlan.prototype.joinCrossProduct

Parameters:

Name	Type	Argument	Description
`right`	PlanModifyPlan	<optional>	The row set from the right view.
`condition`	XsBoolean	<optional>	A boolean expression that filters the join output rows.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

joinDoc(docCol, sourceCol) → {planBuilder.ModifyPlan}

This function specifies a document column to add to the rows by reading the documents for an existing source column having a value of a document uri (which can be used to read other documents) or a fragment id (which can be used to read the source documents for rows). Provides a client interface to a server function. See ModifyPlan.prototype.joinDoc

Parameters:

Name	Type	Argument	Description
`docCol`	PlanColumnName	<optional>	The document column to add to the rows. This can be a string or column specifying the name of the new column that should have the document as its value.
`sourceCol`	PlanColumn	<optional>	The document uri or fragment id value. This is either the output from op:fragment-id-col specifying a fragment id column or a document uri column. Joining on a fragment id is more efficient than joining on a uri column.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

joinDocAndUri(docCol, uriCol, sourceCol) → {planBuilder.ModifyPlan}

This method adds an uri column and a document column to rows based on an existing source column having a value of a document uri (which can be used to read other documents) or a fragment id (which can be used to read the source documents for rows). If the fragment id column is null in the row, the row is dropped from the rowset. Provides a client interface to a server function. See ModifyPlan.prototype.joinDocAndUri

Parameters:

Name	Type	Argument	Description
`docCol`	PlanColumnName	<optional>	The document column to add to the rows. This can be a string or a column, op:col, op:view-col or op:schema-col, specifying the name of the new column that should have the document as its value.
`uriCol`	PlanColumn	<optional>	The uri column to add to the rows. This can be a string or a column, op:col, op:view-col or op:schema-col, specifying the name of the new column that should have the document uri as its value.
`sourceCol`	PlanColumn	<optional>	The document uri or fragment id value. This is either an op:fragment-id-col specifying a fragment id column or a document uri column as xs:string or as a column using op:col, op:view-col or op:schema-col. Joining on a fragment id is more efficient than joining on a uri column.

Since:

3.4.0

Returns:

Type: planBuilder.ModifyPlan

joinDocCols(cols, docIdCol) → {planBuilder.ModifyPlan}

This function populates the view with the uri, doc, collections, metadata, permissions, and / or quality document descriptor columns for database document values. Provides a client interface to a server function. See ModifyPlan.prototype.joinDocCols

Parameters:

Name	Type	Argument	Description
`cols`	PlanDocColsIdentifier	<optional>	The source column to join. This is either an op:fragment-id-col specifying a fragment id column or a op:col, op:view-col or op:schema-col that contains document uris. Joining on a fragment id is more efficient than joining on an uri column.
`docIdCol`	PlanColumnName	<optional>	The document uri or fragment id value. This is either an op.fragmentIdCol object specifying a fragment id column or a document uri column.

Since:

3.1.0

Returns:

Type: planBuilder.ModifyPlan

joinDocUri(uriCol, fragmentIdCol) → {planBuilder.ModifyPlan}

This method adds a uri column to rows based on an existing fragment id column to identify the source document for each row. The fragmentIdCol must be an op:fragment-id-col specifying a fragment id column. If the fragment id column is null in the row, the row is dropped from the rowset. Provides a client interface to a server function. See ModifyPlan.prototype.joinDocUri

Parameters:

Name	Type	Argument	Description
`uriCol`	PlanColumnName	<optional>	The document uri. This is the output from op:col('uri') that specifies a document uri column.
`fragmentIdCol`	PlanColumn	<optional>	The document fragment id value. This is the output from op:fragment-id-col specifying a fragment id column.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

joinFullOuter(right, keys, condition) → {planBuilder.ModifyPlan}

This method yields one output row set with the rows from an inner join as well as the other rows from both the left and right row sets. Provides a client interface to a server function. See ModifyPlan.prototype.joinFullOuter

Parameters:

Name	Type	Argument	Description
`right`	PlanModifyPlan	<optional>	The row set from the right view.
`keys`	PlanJoinKey	<optional>	The equijoin from one or more calls to the op:on function.
`condition`	XsBoolean	<optional>	A boolean expression that filters the join output rows.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

joinInner(right, keys, condition) → {planBuilder.ModifyPlan}

This method returns all rows from multiple tables where the join condition is met. In the output row set, each row concatenates one left row and one right row for each match between the keys in the left and right row sets. Provides a client interface to a server function. See ModifyPlan.prototype.joinInner

Parameters:

Name	Type	Argument	Description
`right`	PlanModifyPlan	<optional>	The row set from the right view.
`keys`	PlanJoinKey	<optional>	The equijoin from one or more calls to the op:on function.
`condition`	XsBoolean	<optional>	A boolean expression that filters the join output rows.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

joinLeftOuter(right, keys, condition) → {planBuilder.ModifyPlan}

This method yields one output row set with the rows from an inner join as well as the other rows from the left row set. Provides a client interface to a server function. See ModifyPlan.prototype.joinLeftOuter

Parameters:

Name	Type	Argument	Description
`right`	PlanModifyPlan	<optional>	The row set from the right view.
`keys`	PlanJoinKey	<optional>	The equijoin from one or more calls to the op:on function.
`condition`	XsBoolean	<optional>	A boolean expression that filters the join output rows.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

limit(length) → {planBuilder.ModifyPlan}

This method specifies the maximum number of rows to be returned by this Plan. Provides a client interface to a server function. See ModifyPlan.prototype.limit

Parameters:

Name	Type	Argument	Description
`length`	PlanLongParam	<optional>	The number of rows to return.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

lockForUpdate(lockUriCol) → {planBuilder.ModifyPlan}

Gets an early lock on documents that will be updated later in the pipeline with an operation like remove() or write(). Documents are always locked, but for complex pipelines, it can be beneficial to lock the document early, so to minimize the potential for lock contention. Provides a client interface to a server function. See ModifyPlan.prototype.lockForUpdate

Parameters:

Name	Type	Argument	Description
`lockUriCol`	PlanDocIdentifier	<optional>	the column containing URIs to be locked

Since:

3.1.0

Returns:

Type: planBuilder.ModifyPlan

notExistsJoin(right, keys, condition) → {planBuilder.ModifyPlan}

This method is a filtering join that filters based on whether the join exists or not but doesn't add any columns. Provides a client interface to a server function. See ModifyPlan.prototype.notExistsJoin

Parameters:

Name	Type	Argument	Description
`right`	PlanModifyPlan	<optional>	The row set from the right view.
`keys`	PlanJoinKey	<optional>	The equijoin from one or more calls to the op:on function.
`condition`	XsBoolean	<optional>	A boolean expression that filters the join output rows.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

offset(start) → {planBuilder.ModifyPlan}

This method returns a subset of the rows in the result set. The start parameter specifies the index in the result set to use as the starting point for the return, followed by the remaining rows up to the number specified by the op:limit method. Provides a client interface to a server function. See ModifyPlan.prototype.offset

Parameters:

Name	Type	Argument	Description
`start`	PlanLongParam	<optional>	The index in the result set to use as the starting point.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

offsetLimit(start, length) → {planBuilder.ModifyPlan}

This method returns a subset of the rows in the result set by skipping the number of rows specified by start and returning the remaining rows up to the length limit. Provides a client interface to a server function. See ModifyPlan.prototype.offsetLimit

Parameters:

Name	Type	Argument	Description
`start`	PlanLongParam	<optional>	The number of rows to skip. Default is 1.
`length`	PlanLongParam	<optional>	The maximum number of rows to return.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

onError(action, errorColumn) → {planBuilder.ModifyPlan}

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. Provides a client interface to a server function. See ModifyPlan.prototype.onError

Parameters:

Name	Type	Argument	Description
`action`	XsString	<optional>	Valid options are: "fail" - stop processing and "continue" - add an error to the error column and continue processing.
`errorColumn`	PlanExprColName	<optional>	An optional error column which is not used in the plan. If this parameter is not passed in 'sys.errors' is used.

Since:

3.4.0

Returns:

Type: planBuilder.ModifyPlan

orderBy(keys) → {planBuilder.ModifyPlan}

This method sorts the row set by the specified order definition. Provides a client interface to a server function. See ModifyPlan.prototype.orderBy

Parameters:

Name	Type	Argument	Description
`keys`	PlanSortKeyName	<optional>	The specified column or sortdef output from the op:asc or op:desc function.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

patch(docColumn, patchDef) → {planBuilder.ModifyPlan}

Builds a patch operation including a sequence of inserts, replaces, replace-inserts and deletes. Provides a client interface to a server function. See ModifyPlan.prototype.patch

Parameters:

Name	Type	Argument	Description
`docColumn`	PlanExprColName	<optional>	The document column which need to be patched.
`patchDef`	PlanPatchBuilder	<optional>	The patch definition as op:patch-builder

Since:

3.4.0

Returns:

Type: planBuilder.ModifyPlan

prepare(optimize) → {planBuilder.PreparePlan}

This method prepares the specified plan for execution as an optional final step before execution. Provides a client interface to a server function. See ModifyPlan.prototype.prepare

Parameters:

Name	Type	Argument	Description
`optimize`	XsInt	<optional>	The optimization level, which can be 0, 1, or 2 (1 is mostly used).

Since:

2.1.1

Returns:

Type: planBuilder.PreparePlan

remove(removeCol) → {planBuilder.ModifyPlan}

This method deletes a document from the database. If the document does not exist, this method does not throw an error. Delete a node. Provides a client interface to a server function. See ModifyPlan.prototype.remove

Parameters:

Name	Type	Argument	Description
`removeCol`	PlanDocIdentifier	<optional>	the column containing URIs to be removed

Since:

3.1.0

Returns:

Type: planBuilder.ModifyPlan

select(columns, qualifierName) → {planBuilder.ModifyPlan}

This call projects the specified columns from the current row set and / or applies a qualifier to the columns in the row set. Unlike SQL, a select call is not required in an Optic query. Provides a client interface to a server function. See ModifyPlan.prototype.select

Parameters:

Name	Type	Argument	Description
`columns`	PlanExprColName	<optional>	The columns to project from the input rows. The columns can be named with a string or a column parameter function such as op:col or constructed from an expression with op:as.
`qualifierName`	XsString	<optional>	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.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

transformDoc(transformDocCol, transformDef) → {planBuilder.ModifyPlan}

This function applies a transformation to a column that contains documents. This transform module needs to be stored in the modules database. Provides a client interface to a server function. See ModifyPlan.prototype.transformDoc

Parameters:

Name	Type	Argument	Description
`transformDocCol`	PlanDocIdentifier	<optional>	The 'kind' key of the schema map must be 'mjs'(the default), or 'xslt'. The 'path' key specifies the main module in the modules database. The 'params' key specifies parameter values passed to the main module. (refer to xdmp:invoke and xdmp:xslt-invoke).
`transformDef`	PlanTransformDef	<optional>	defines a transform to be used.

Since:

3.1.0

Returns:

Type: planBuilder.ModifyPlan

union(right) → {planBuilder.ModifyPlan}

This method yields all of the rows from the input row sets. Columns that are present only in some input row sets effectively have a null value in the rows from the other row sets. Provides a client interface to a server function. See ModifyPlan.prototype.union

Parameters:

Name	Type	Argument	Description
`right`	PlanModifyPlan	<optional>	The row set from the right view.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

unnestInner(inputColumn, valueColumn, ordinalColumn) → {planBuilder.ModifyPlan}

This function flattens an array value into multiple rows.Then performs a op:join-inner on the rest of the rows. Provides a client interface to a server function. See ModifyPlan.prototype.unnestInner

Parameters:

Name	Type	Argument	Description
`inputColumn`	PlanExprColName	<optional>	The input column, which contains an array, to flatten into rows. This can be a string of the column name or an op:col. Use op:view-col or op:schema-col if you need to identify columns in the two views that have the same column name.
`valueColumn`	PlanExprColName	<optional>	The output column which contains the flattened array values. This can be a string of the column name or an op:col. Use op:view-col or op:schema-col as needed.
`ordinalColumn`	PlanExprColName	<optional>	The ordinalColumn is optional. If specified, an additional column will be added to the rows of flattened array values, starting from 1. This can be a string of the column name or an op:col. Use op:view-col or op:schema-col as needed.

Since:

3.0.0

Returns:

Type: planBuilder.ModifyPlan

unnestLeftOuter(inputColumn, valueColumn, ordinalColumn) → {planBuilder.ModifyPlan}

This function flattens an array value into multiple rows.Then performs a op:join-left-outer on the rest of the rows. Provides a client interface to a server function. See ModifyPlan.prototype.unnestLeftOuter

Parameters:

Name	Type	Argument	Description
`inputColumn`	PlanExprColName	<optional>	The input column, which contains an array, to flatten into rows. This can be a string of the column name or an op:col. Use op:view-col or op:schema-col if you need to identify columns in the two views that have the same column name.
`valueColumn`	PlanExprColName	<optional>	The output column which contains the flattened array values. This can be a string of the column name or an op:col. Use op:view-col or op:schema-col as needed.
`ordinalColumn`	PlanExprColName	<optional>	The ordinalColumn is optional. If specified, an additional column will be added to the rows of flattened array values, starting from 1. This can be a string of the column name or an op:col. Use op:view-col or op:schema-col as needed.

Since:

3.0.0

Returns:

Type: planBuilder.ModifyPlan

validateDoc(validateDocCol, schemaDef) → {planBuilder.ModifyPlan}

Validate the document based on a supplied schema. This schema needs to be stored in the schema database. Check appserver error log for validate errors. Provides a client interface to a server function. See ModifyPlan.prototype.validateDoc

Parameters:

Name	Type	Argument	Description
`validateDocCol`	PlanColumnName	<optional>	The required 'kind' key of the schemaDef map must be 'jsonSchema', 'schematron', or 'xmlSchema'. When 'kind' is 'jsonSchema' or 'schemtron' then a key 'schemaUri' is required. Key 'mode' takes 'strict', 'lax' or 'type' (refer to xdmp:validate).
`schemaDef`	PlanSchemaDef	<optional>	This is an object. The required 'kind' property of the schema object must be 'jsonSchema', 'schematron', or 'xmlSchema'. When 'kind' is 'jsonSchema' or 'schemtron' then a property 'schemaUri' is required. Property 'mode' takes 'strict', 'lax' or 'type' (refer to xdmp.validate).

Since:

3.1.0

Returns:

Type: planBuilder.ModifyPlan

where(condition) → {planBuilder.ModifyPlan}

This method restricts the row set to rows matched by the boolean expression. Use boolean composers such as op:and and op:or to combine multiple expressions. Provides a client interface to a server function. See ModifyPlan.prototype.where

Parameters:

Name	Type	Argument	Description
`condition`	PlanRowFilter	<optional>	This can be a boolean expression, a cts:query to qualify the source documents that produced the rows set, or (where part of the row set was produced by the op:from-triples accessor) a sem:store to restrict or expand the triples that produce the row set.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

whereDistinct() → {planBuilder.ModifyPlan}

This method removes duplicate rows from the row set. Provides a client interface to a server function. See ModifyPlan.prototype.whereDistinct

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

write(docCols) → {planBuilder.ModifyPlan}

Inserts or overwrites the documents identified by the uri column with the data supplied by the other document descriptor columns. Provides a client interface to a server function. See ModifyPlan.prototype.write

Parameters:

Name	Type	Argument	Description
`docCols`	PlanDocColsIdentifier	<optional>	the docCols value.

Since:

3.1.0

Returns:

Type: planBuilder.ModifyPlan