Namespace: planBuilder

planBuilder

A helper for building the definition of a rows query. The helper is created by the marklogic.planBuilder function.

Namespaces

AccessPlan
ModifyPlan
PatchBuilder
Plan
PlanPatchBuilderBase
Prefixer
PreparePlan
cts
fn
geo
json
map
math
rdf
sem
spell
sql
vec
xdmp
xs

Methods

add(left, right) → {XsNumeric}

This function returns the sum of the specified numeric expressions. In expressions, the call should pass the result from an op:col function to identify a column. Provides a client interface to a server function. See op.add

Parameters:

Name	Type	Argument	Description
`left`	XsAnyAtomicType	<optional>	The left value expression.
`right`	XsAnyAtomicType	<optional>	The right value expression.

Since:

2.1.1

Returns:

Type: XsNumeric

and(left, right) → {XsBoolean}

This function returns true if the specified expressions all return true. Otherwise, it returns false. Provides a client interface to a server function. See op.and

Parameters:

Name	Type	Argument	Description
`left`	XsAnyAtomicType	<optional>	The left value expression.
`right`	XsAnyAtomicType	<optional>	The right value expression.

Since:

2.1.1

Returns:

Type: XsBoolean

arrayAggregate(name, column, option) → {planBuilder.PlanAggregateCol}

This function constructs an array whose items are the result of evaluating the column for each row in the group or row set. The result is used for building the parameters used by the op:group-by function. Provides a client interface to a server function. See op.arrayAggregate

Parameters:

Name	Type	Argument	Description
`name`	PlanColumnName	<optional>	The name to be used for the aggregated column.
`column`	PlanExprColName	<optional>	The columns to be aggregated.
`option`	PlanValueOption	<optional>	The options can take a values key with a distinct value to average the distinct values of the column.

Since:

2.1.1

Returns:

Type: planBuilder.PlanAggregateCol

as(column, expression) → {planBuilder.PlanExprCol}

This function defines a column by assigning the value of an expression over the rows in the row set. Provides a client interface to a server function. See op.as

Parameters:

Name	Type	Argument	Description
`column`	PlanColumnName	<optional>	The name of the column to be defined. This can be either a string or the return value from op:col, op:view-col, or op:schema-col.
`expression`	Item	<optional>	The expression used to define the value the column.

Since:

2.1.1

Returns:

Type: planBuilder.PlanExprCol

asc(column) → {planBuilder.PlanSortKey}

This function sorts the rows by the values of the specified column in ascending order. The results are used by the op:order-by function. Provides a client interface to a server function. See op.asc

Parameters:

Name	Type	Argument	Description
`column`	PlanExprColName	<optional>	The column by which order the output.

Since:

2.1.1

Returns:

Type: planBuilder.PlanSortKey

avg(name, column, option) → {planBuilder.PlanAggregateCol}

This function averages the non-null values of the column for the rows in the group or row set. The result is used for building the parameters used by the op:group-by function. Provides a client interface to a server function. See op.avg

Parameters:

Name	Type	Argument	Description
`name`	PlanColumnName	<optional>	The name to be used for the aggregated column.
`column`	PlanExprColName	<optional>	The column to be aggregated.
`option`	PlanValueOption	<optional>	The options can take a values key with a distinct value to average the distinct values of the column.

Since:

2.1.1

Returns:

Type: planBuilder.PlanAggregateCol

bucketGroup(name, key, boundaries, collation) → {planBuilder.PlanNamedGroup}

This function can be used as a named group in functions op:group-to-arrays or op:facet-by. After grouping, the plan can also join a literal table with descriptive metadata based for each bucket number. Developers can handle special cases by taking the same approach as the convenience function and binding a new column on the return value of an sql:bucket expression on a numeric or datetime column to use as a grouping key. Provides a client interface to a server function. See op.bucketGroup

Parameters:

Name	Type	Argument	Description
`name`	XsString	<optional>	The name of both the group and the new grouping key column with numbered buckets.
`key`	PlanExprColName	<optional>	The identifier for the existing column with the values (typically numeric or datetime) to put into buckets. 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.
`boundaries`	XsAnyAtomicType	<optional>	An ordered XQuery sequence of values that specify the boundaries between buckets. The values must have the same type as the existing column.
`collation`	XsString	<optional>	The collation to use when comparing strings as described in 'Collation URI Syntax' in the Application Developer's Guide

Since:

2.1.1

Returns:

Type: planBuilder.PlanNamedGroup

case(when, otherwise) → {Item}

This function returns the specified valueExpression if the specified valueExpression is true. Otherwise, it returns null. Provides a client interface to a server function. See op.case

Parameters:

Name	Type	Argument	Description
`when`	PlanCase	<optional>	One or more op:when expressions.
`otherwise`	Item	<optional>	The value expression to return if none of the op:when expressions is true.

Since:

2.1.1

Returns:

Type: Item

col(column) → {planBuilder.PlanColumn}

Identifies a column where the column name is unique and a qualifier on the column name isn't necessary (and might not exist). Provides a client interface to a server function. See op.col

Parameters:

Name	Type	Argument	Description
`column`	XsString	<optional>	The Optic AccessorPlan created by op:from-view, op:from-triples, or op:from-lexicons.

Since:

2.1.1

Returns:

Type: planBuilder.PlanColumn

count(name, column, option) → {planBuilder.PlanAggregateCol}

This function counts the rows where the specified input column has a value. If the input column is omitted, all rows in the group or row set are counted. The result is used for building the parameters used by the op:group-by function. Provides a client interface to a server function. See op.count

Parameters:

Name	Type	Argument	Description
`name`	PlanColumnName	<optional>	The name to be used for the column values.
`column`	PlanExprColName	<optional>	The columns to be counted.
`option`	PlanValueOption	<optional>	The options can take a values key with a 'distinct' value to count the distinct values of the column.

Since:

2.1.1

Returns:

Type: planBuilder.PlanAggregateCol

cube(keys) → {planBuilder.PlanGroup}

This function specifies a list of grouping keys for a group and returns that group and every possible larger group (including all rows) formed from any subset of keys. The result is used for building the first parameter for the op:group-by-union or op:group-to-arrays functions. Provides a client interface to a server function. See op.cube

Parameters:

Name	Type	Argument	Description
`keys`	PlanExprColName	<optional>	The columns to use as grouping keys. 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.

Since:

2.1.1

Returns:

Type: planBuilder.PlanGroup

desc(column) → {planBuilder.PlanSortKey}

This function sorts the rows by the values of the specified column in descending order. The results are used by the op:order-by function. Provides a client interface to a server function. See op.desc

Parameters:

Name	Type	Argument	Description
`column`	PlanExprColName	<optional>	The column by which order the output.

Since:

2.1.1

Returns:

Type: planBuilder.PlanSortKey

divide(left, right) → {XsNumeric}

This function divides the left numericExpression by the right numericExpression and returns the value. Provides a client interface to a server function. See op.divide

Parameters:

Name	Type	Argument	Description
`left`	XsAnyAtomicType	<optional>	The left numeric expression.
`right`	XsAnyAtomicType	<optional>	The right numeric expression.

Since:

2.1.1

Returns:

Type: XsNumeric

docColTypes() → {planBuilder.PlanRowColTypes}

Provides the 3rd parameter for op:from-param for row column types. Provides a client interface to a server function. See op.docColTypes

Since:

2.1.1

Returns:

Type: planBuilder.PlanRowColTypes

docCols(qualifier, names) → {planBuilder.PlanDocColsIdentifier}

Constructs a document column identifier object for columns of uri, doc, collections, metadata, permissions, quality and temporalCollection. The document column identifier object can be passed to the op:join-doc-cols or op:write. Provides a client interface to a server function. See op.docCols

Parameters:

Name	Type	Argument	Description
`qualifier`	XsString	<optional>	Specifies a name for qualifying the column names.
`names`	XsString	<optional>	A sequence of columns names, a combination of uri, doc, collections, metadata, permissions, quality and temporalCollection.

Since:

2.1.1

Returns:

Type: planBuilder.PlanDocColsIdentifier

eq(left, right) → {XsBoolean}

This function takes two or more expressions and returns true if all of the expressions return the same value. Otherwise, it returns false. The expressions can include calls to the op:col function to get the value of a column. Provides a client interface to a server function. See op.eq

Parameters:

Name	Type	Argument	Description
`left`	XsAnyAtomicType	<optional>	The left value expression.
`right`	XsAnyAtomicType	<optional>	The right value expression.

Since:

2.1.1

Returns:

Type: XsBoolean

fragmentIdCol(column) → {planBuilder.PlanSystemColumn}

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. Provides a client interface to a server function. See op.fragmentIdCol

Parameters:

Name	Type	Argument	Description
`column`	XsString	<optional>	The name of the fragment ID column.

Since:

2.1.1

Returns:

Type: planBuilder.PlanSystemColumn

fromDocDescriptors(docDescriptor, qualifier) → {planBuilder.AccessPlan}

This function constructs document rows from the docsDescriptors. Provides a client interface to a server function. See op.fromDocDescriptors

Parameters:

Name	Type	Argument	Description
`docDescriptor`	PlanDocDescriptor	<optional>	A map of document descriptors. Each document descriptor describes a document. A document descriptor contains a combination of uri, doc, collections, metadata, permissions, quality and temporalCollection. This is a simpler form of op:from-param.
`qualifier`	XsString	<optional>	Specifies a name for qualifying the column names.

Since:

3.1.0

Returns:

Type: planBuilder.AccessPlan

fromDocUris(querydef, qualifier) → {planBuilder.AccessPlan}

This function matches and returns the uri for documents. Provides a client interface to a server function. See op.fromDocUris

Parameters:

Name	Type	Argument	Description
`querydef`	PlanQueryDef	<optional>	Qualifies a set of documents. The query can be a cts:query or as a sequence of document URI string literals.
`qualifier`	XsString	<optional>	Specifies a name for qualifying the column names.

Since:

3.1.0

Returns:

Type: planBuilder.AccessPlan

fromLexicons(indexes, qualifierName, sysCols) → {planBuilder.AccessPlan}

This function dynamically constructs a view from range indexes or the uri or collection lexicons. This function will only return rows for documents where the first column has a value. The keys in the map specify the names of the columns and the values in the map provide cts:reference objects to specify the lexicon providing the values of the columns. Optic emits rows based on co-occurrence of lexicon values within the same document similar to cts:value-tuples If the cts:reference sets the nullable option to true, the column is optional in the row. Provides a client interface to a server function. See op.fromLexicons

Parameters:

Name	Type	Argument	Description
`indexes`	PlanCtsReferenceMap	<optional>	An object in which each key is a column name and each value specifies a cts:reference for a range index or other lexicon (especially the cts:uri-reference lexicon) with the column values.
`qualifierName`	XsString	<optional>	Specifies a name for qualifying the column names. By default, lexicon rows have no qualification. Use cases for the qualifier include self joins. Using an empty string removes all qualification from the column names.
`sysCols`	PlanSystemColumn	<optional>	An optional named fragment id column returned by the op:fragment-id-col function. The fragment id column can be used for joins.

Since:

2.1.1

Returns:

Type: planBuilder.AccessPlan

fromLiterals(rows, qualifierName) → {planBuilder.AccessPlan}

Constructs a literal row set as in the SQL VALUES or SPARQL VALUES statements. When specifying rows with arrays, values are mapped to column names by position. Provides a client interface to a server function. See op.fromLiterals

Parameters:

Name	Type	Argument	Description
`rows`	PlanXsValueMap	<optional>	This parameter is either an array of object literals or sem:binding objects in which the key is a column name string identifying the column and the value is a literal with the value of the column, or this parameter is an object with a columnNames key having a value of an array of column names and a rowValues key having a value of an array of arrays with literal values.
`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.AccessPlan

fromParam(paramName, qualifier, rowColTypes) → {planBuilder.AccessPlan}

This function constructs document rows with rows provided by a parameter. Provides a client interface to a server function. See op.fromParam

Parameters:

Name	Type	Argument	Description
`paramName`	XsString	<optional>	The paramName parameter specifies the placeholder parameter supplying the rows.
`qualifier`	XsString	<optional>	Specifies a name for qualifying the column names.
`rowColTypes`	PlanRowColTypes	<optional>	Describes the columns with a sequence of maps. It's a combinations of column, type and nullable. The 'column' is the column name, which is required. The 'type' is the optional type of the column, which can be an atomic type or the default of none. The 'nullable' is an optional boolean defaulting to false. If your rows contains only uri, doc, collections, metadata, permissions, quality and temporalCollection columns, you could simply use op:doc-col-types instead.

Since:

3.1.0

Returns:

Type: planBuilder.AccessPlan

fromSPARQL(select, qualifierName, option) → {planBuilder.ModifyPlan}

This function dynamically constructs a row set based on a SPARQL SELECT query from triples. Provides a client interface to a server function. See Builder.prototype.fromSPARQL

Parameters:

Name	Type	Argument	Description
`select`	XsString	<optional>	A SPARQL SELECT query expressed as a string.
`qualifierName`	XsString	<optional>	Specifies a name for qualifying the column names. An "@" in front of the name specifies a parameter placeholder. A parameter placeholder in the SPARQL string must be bound to a parameter value in the result() call.
`option`	PlanSparqlOption	<optional>	Options consisting of key-value pairs that set options. At present, the options consist of dedup and base. Option dedup can take an on\|off value to enable or disable deduplication. Deduplication is off by default. Option base takes a string as the initial base IRI for the query.

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

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

This function dynamically constructs a row set based on a SQL SELECT query from views. Provides a client interface to a server function. See Builder.prototype.fromSQL

Parameters:

Name	Type	Argument	Description
`select`	XsString	<optional>	A SQL SELECT query expressed as a string.
`qualifierName`	XsString	<optional>	Specifies a name for qualifying the column names. Placeholder parameters in the SQL string may be bound in the result() call

Since:

2.1.1

Returns:

Type: planBuilder.ModifyPlan

fromSearch(query, columns, qualifierName, option) → {planBuilder.AccessPlan}

This function dynamically constructs a row set based on a cts.query where the columns for the document fragment id and score reflecting the degree of match of the document with the query criteria. Provides a client interface to a server function. See op.fromSearch

Parameters:

Name	Type	Argument	Description
`query`	PlanSearchQuery	<optional>	Qualifies and establishes the scores for a set of documents. The query can be a cts:query or a string as a shortcut for a cts:word-query. The fragments are not filtered to ensure they match the query, but instead selected in the same manner as "unfiltered" cts:search operations.
`columns`	PlanExprColName	<optional>	Specifies which of the available columns to include in the rows. The available columns include the metrics for relevance ('confidence', 'fitness', 'quality', and 'score') and fragmentId for the document identifier. By default, the rows have the fragmentId and score columns. To rename a column, use op:as specifying the new name for an op:col with the old name.
`qualifierName`	XsString	<optional>	Specifies a name for qualifying the column names.
`option`	PlanSearchOption	<optional>	Similar to the options of cts:search, supplies the 'scoreMethod' key with a value of 'logtfidf', 'logtf', 'simple' or 'bm25' to specify the method for assigning a score to matched documents or supplies the 'qualityWeight' key with a numeric value to specify a multiplier for the quality contribution to the score. Specify a value between 0 (exclusive) and 1 (inclusive) for bm25LengthWeight if 'bm25' scoring method is used.

Since:

2.1.1

Returns:

Type: planBuilder.AccessPlan

fromSearchDocs(query, qualifierName, option) → {planBuilder.AccessPlan}

This function matches and returns the uri, content, and score for documents. Provides a client interface to a server function. See op.fromSearchDocs

Parameters:

Name	Type	Argument	Description
`query`	PlanSearchQuery	<optional>	Qualifies and establishes the scores for a set of documents. The query can be a cts:query or a string as a shortcut for a cts:word-query.
`qualifierName`	XsString	<optional>	Specifies a name for qualifying the column names.
`option`	PlanSearchOption	<optional>	Similar to the options of cts:search, supplies the 'scoreMethod' key with a value of 'logtfidf', 'logtf', 'simple', or 'bm25' to specify the method for assigning a score to matched documents or supplies the 'qualityWeight' key with a numeric value to specify a multiplier for the quality contribution to the score. Specify a value between 0 (exclusive) and 1 (inclusive) for bm25LengthWeight if 'bm25' scoring method is used.

Since:

2.1.1

Returns:

Type: planBuilder.AccessPlan

fromTriples(patterns, qualifierName, graphIris, option) → {planBuilder.AccessPlan}

Reads rows by matching patterns in the triple index. Provides a client interface to a server function. See op.fromTriples

Parameters:

Name	Type	Argument	Description
`patterns`	PlanTriplePattern	<optional>	One or more pattern definitions returned by the op:pattern function.
`qualifierName`	XsString	<optional>	Specifies a name for qualifying the column names. By default, triple rows have no qualification. Use cases for the qualifier include self joins. Using an empty string removes all qualification from the column names.
`graphIris`	XsString	<optional>	A list of graph IRIs to restrict the results to triples in the specified graphs. The sem:default-graph-iri function returns the iri that identifies the default graph.
`option`	PlanTripleOption	<optional>	Options consisting of key-value pairs that set options. At present, the options consist of dedup which can take an on\|off value to enable or disable deduplication. Deduplication is off by default.

Since:

2.1.1

Returns:

Type: planBuilder.AccessPlan

fromView(schema, view, qualifierName, sysCols) → {planBuilder.AccessPlan}

This function reads a row set from a configured view over TDE-indexed rows or a predefined view over range indexes. Provides a client interface to a server function. See op.fromView

Parameters:

Name	Type	Argument	Description
`schema`	XsString	<optional>	The name identifying the schema containing the view. If the schema name is null, the engine searches for a view with the specified name.
`view`	XsString	<optional>	The name identifying a configured template or range view for rows projected from documents.
`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.
`sysCols`	PlanSystemColumn	<optional>	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.

Since:

2.1.1

Returns:

Type: planBuilder.AccessPlan

ge(left, right) → {XsBoolean}

This function returns true if the value of the left expression is greater than or equal to the value of the right expression. Otherwise, it returns false. Provides a client interface to a server function. See op.ge

Parameters:

Name	Type	Argument	Description
`left`	XsAnyAtomicType	<optional>	The left value expression.
`right`	XsAnyAtomicType	<optional>	The right value expression.

Since:

2.1.1

Returns:

Type: XsBoolean

graphCol(column) → {planBuilder.PlanSystemColumn}

Identifies the graph for a triple providing one or more columns for a row. You pass the graph column as a system column parameter to the op:pattern function. Provides a client interface to a server function. See op.graphCol

Parameters:

Name	Type	Argument	Description
`column`	XsString	<optional>	The name to use for the graph column.

Since:

2.1.1

Returns:

Type: planBuilder.PlanSystemColumn

group(keys) → {planBuilder.PlanGroup}

This function specifies the grouping keys for a group as a list of zero or more columns. The result is used for building the first parameter for the op:group-by-union function. Provides a client interface to a server function. See op.group

Parameters:

Name	Type	Argument	Description
`keys`	PlanExprColName	<optional>	The columns (if any) to use as grouping keys. 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.

Since:

2.1.1

Returns:

Type: planBuilder.PlanGroup

groupConcat(name, column, options) → {planBuilder.PlanAggregateCol}

This function concatenates the non-null values of the column for the rows in the group or row set. The result is used for building the parameters used by the op:group-by function. Provides a client interface to a server function. See op.groupConcat

Parameters:

Name	Type	Argument	Description
`name`	PlanColumnName	<optional>	The name to be used for column with the concatenated values.
`column`	PlanExprColName	<optional>	The name of the column with the values to be concatenated for the group.
`options`	PlanGroupConcatString	<optional>	The options can take a values key with a distinct value to average the distinct values of the column. In addition to the values key, the options can take a separator key specifying a separator character. The value can be a string or placeholder parameter.

Since:

2.1.1

Returns:

Type: planBuilder.PlanAggregateCol

groupKey(name, column) → {planBuilder.PlanAggregateCol}

Provides a client interface to a server function.

Parameters:

Name	Type	Argument	Description
`name`	PlanColumnName	<optional>	-
`column`	PlanExprColName	<optional>	-

Since:

2.1.1

Returns:

Type: planBuilder.PlanAggregateCol

gt(left, right) → {XsBoolean}

This function returns true if the value of the left expression is greater than the value of the right expression. Otherwise, it returns false. Provides a client interface to a server function. See op.gt

Parameters:

Name	Type	Argument	Description
`left`	XsAnyAtomicType	<optional>	The left value expression.
`right`	XsAnyAtomicType	<optional>	The right value expression.

Since:

2.1.1

Returns:

Type: XsBoolean

hasGroupKey(name, column) → {planBuilder.PlanAggregateCol}

This aggregate function adds a flag to a grouped row specifying whether a column acted as a grouping key for the row. Provides a client interface to a server function. See op.hasGroupKey

Parameters:

Name	Type	Argument	Description
`name`	PlanColumnName	<optional>	The name to be used for the aggregated flag column.
`column`	PlanExprColName	<optional>	The column to flag as a grouping key. The column can be named with a string or a column parameter function such as op:col or constructed from an expression with op:as.

Since:

2.1.1

Returns:

Type: planBuilder.PlanAggregateCol

in(value, anyOf) → {XsBoolean}

This function returns true if a test expression evaluates to the same value as any of a list of candidate expressions. Otherwise, it returns false. The expressions can include calls to the op:col function to get the value of a column. Provides a client interface to a server function. See op.in

Parameters:

Name	Type	Argument	Description
`value`	XsAnyAtomicType	<optional>	The expression providing the value to test.
`anyOf`	XsAnyAtomicType	<optional>	One or more expressions providing the candidate values.

Since:

2.1.1

Returns:

Type: XsBoolean

isDefined(operand) → {XsBoolean}

This function tests whether the value of an expression is null in the row where the expression might be as simple as a column identified by op:col. Provides a client interface to a server function. See op.isDefined

Parameters:

Name	Type	Argument	Description
`operand`	Item	<optional>	A boolean expression, such as op:eq or op:not, that might be null.

Since:

2.1.1

Returns:

Type: XsBoolean

jsonArray(property) → {ArrayNode}

This function constructs a JSON array during row processing. The array can be used as the value of a column in a row or passed to a builtin expression function. The node is constructed during processing of the plan, rather than when building the plan. Provides a client interface to a server function. See op.jsonArray

Parameters:

Name	Type	Argument	Description
`property`	PlanJsonContentVal	<optional>	The JSON nodes for the array.

Since:

2.1.1

Returns:

Type: ArrayNode

jsonBoolean(value) → {BooleanNode}

This function constructs a JSON boolean node with the specified value. Provides a client interface to a server function. See op.jsonBoolean

Parameters:

Name	Type	Argument	Description
`value`	XsBoolean	<optional>	The value of the JSON boolean node.

Since:

2.1.1

Returns:

Type: BooleanNode

jsonDocument(root) → {DocumentNode}

This function constructs a JSON document with the root content, which must be exactly one JSON object or array node. Provides a client interface to a server function. See op.jsonDocument

Parameters:

Name	Type	Argument	Description
`root`	JsonRootNode	<optional>	The JSON object or array node used to construct the JSON document.

Since:

2.1.1

Returns:

Type: DocumentNode

jsonNull() → {NullNode}

This function constructs a JSON null node. Provides a client interface to a server function. See op.jsonNull

Since:

2.1.1

Returns:

Type: NullNode

jsonNumber(value) → {NumberNode}

This function constructs a JSON number node with the specified value. Provides a client interface to a server function. See op.jsonNumber

Parameters:

Name	Type	Argument	Description
`value`	XsNumeric	<optional>	The value of the JSON number node.

Since:

2.1.1

Returns:

Type: NumberNode

jsonObject(property) → {ObjectNode}

This function constructs a JSON object with the specified properties. The object can be used as the value of a column in a row or passed to a builtin function. Provides a client interface to a server function. See op.jsonObject

Parameters:

Name	Type	Argument	Description
`property`	PlanJsonProperty	<optional>	The properties to be used to contruct the object. This is constructed by the op:prop function.

Since:

2.1.1

Returns:

Type: ObjectNode

jsonString(value) → {TextNode}

This function constructs a JSON text node with the specified value. Provides a client interface to a server function. See op.jsonString

Parameters:

Name	Type	Argument	Description
`value`	XsAnyAtomicType	<optional>	The value of the JSON text node.

Since:

2.1.1

Returns:

Type: TextNode

le(left, right) → {XsBoolean}

This function returns true if the value of the left expression is less than or equal to the value of the right expression. Otherwise, it returns false. Provides a client interface to a server function. See op.le

Parameters:

Name	Type	Argument	Description
`left`	XsAnyAtomicType	<optional>	The left value expression.
`right`	XsAnyAtomicType	<optional>	The right value expression.

Since:

2.1.1

Returns:

Type: XsBoolean

lt(left, right) → {XsBoolean}

This function returns true if the value of the left expression is less than the value of the right expression. Otherwise, it returns false. Provides a client interface to a server function. See op.lt

Parameters:

Name	Type	Argument	Description
`left`	XsAnyAtomicType	<optional>	The left value expression.
`right`	XsAnyAtomicType	<optional>	The right value expression.

Since:

2.1.1

Returns:

Type: XsBoolean

maskDeterministic(args) → {planBuilder.PlanExprCol}

This function replaces values with masking text that is deterministic. A given input generates the same mask value every time it is applied. Controls features such as the length and type of the generated value.

Parameters:

Name	Type	Description
`args`		with column and options - Column is the name of the column to be defined. This can be either a string or the return value from PlanBuilder.col(), PlanBuilder.viewCol() or PlanBuilder.schemaCol(). Options is an object with name-value pairs specific to the redaction method.

Since:

2.7.0

Returns:

Type: planBuilder.PlanExprCol

maskRandom(args) → {planBuilder.PlanExprCol}

This function replaces values with random text. The masking value can vary across repeated application to the same input value. Controls the length of the generated value and type of replacement text (numbers or letters).

Parameters:

Name	Type	Description
`args`		with column and options - Column is the name of the column to be defined. This can be either a string or the return value from PlanBuilder.col(), PlanBuilder.viewCol() or PlanBuilder.schemaCol(). Options is an object with name-value pairs specific to the redaction method.

Since:

2.7.0

Returns:

Type: planBuilder.PlanExprCol

max(name, column, option) → {planBuilder.PlanAggregateCol}

This function gets the largest non-null value of the column for the rows in the group or row set. The result is used for building the parameters used by the op:group-by function. Provides a client interface to a server function. See op.max

Parameters:

Name	Type	Argument	Description
`name`	PlanColumnName	<optional>	The name to be used for the largest value.
`column`	PlanExprColName	<optional>	The group or row set.
`option`	PlanValueOption	<optional>	The options can take a values key with a distinct value to average the distinct values of the column.

Since:

2.1.1

Returns:

Type: planBuilder.PlanAggregateCol

min(name, column, option) → {planBuilder.PlanAggregateCol}

This function gets the smallest non-null value of the column for the rows in the group or row set. The result is used for building the parameters used by the op:group-by function. Provides a client interface to a server function. See op.min

Parameters:

Name	Type	Argument	Description
`name`	PlanColumnName	<optional>	The name to be used for the smallest value.
`column`	PlanExprColName	<optional>	The group or row set.
`option`	PlanValueOption	<optional>	The options can take a values key with a distinct value to average the distinct values of the column.

Since:

2.1.1

Returns:

Type: planBuilder.PlanAggregateCol

modulo(left, right) → {XsNumeric}

This function returns the remainder afer the division of the dividend and divisor expressions. For example, op:modulo(5, 2) returns 1. Provides a client interface to a server function. See op.modulo

Parameters:

Name	Type	Argument	Description
`left`	XsNumeric	<optional>	The dividend numeric expression.
`right`	XsNumeric	<optional>	The divisor numeric expression.

Since:

2.1.1

Returns:

Type: XsNumeric

multiply(left, right) → {XsNumeric}

This function multiplies the left numericExpression by the right numericExpression and returns the value. Provides a client interface to a server function. See op.multiply

Parameters:

Name	Type	Argument	Description
`left`	XsAnyAtomicType	<optional>	The left numeric expression.
`right`	XsAnyAtomicType	<optional>	The right numeric expression.

Since:

2.1.1

Returns:

Type: XsNumeric

namedGroup(name, keys) → {planBuilder.PlanNamedGroup}

This function specifies the grouping keys for a group as a named list of zero or more columns. The result is used for building the first parameter for the op:group-to-arrays function. Provides a client interface to a server function. See op.namedGroup

Parameters:

Name	Type	Argument	Description
`name`	XsString	<optional>	The name for the list of grouping keys.
`keys`	PlanExprColName	<optional>	The columns (if any) to use as grouping keys. 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.

Since:

2.1.1

Returns:

Type: planBuilder.PlanNamedGroup

ne(left, right) → {XsBoolean}

This function returns true if the value of the left expression is not equal to the value of the right expression. Otherwise, it returns false. Provides a client interface to a server function. See op.ne

Parameters:

Name	Type	Argument	Description
`left`	XsAnyAtomicType	<optional>	The left value expression.
`right`	XsAnyAtomicType	<optional>	The right value expression.

Since:

2.1.1

Returns:

Type: XsBoolean

not(operand) → {XsBoolean}

This function returns true if neither of the specified boolean expressions return true. Otherwise, it returns false. Provides a client interface to a server function. See op.not

Parameters:

Name	Type	Argument	Description
`operand`	XsAnyAtomicType	<optional>	Exactly one boolean expression, such as op:and or op:or, or op:is-defined.

Since:

2.1.1

Returns:

Type: XsBoolean

on(left, right) → {planBuilder.PlanJoinKey}

Specifies an equijoin using one columndef each from the left and right rows. The result is used by the op:join-inner, op:join-left-outer, and op:join-full-outer, and functions. Provides a client interface to a server function. See op.on

Parameters:

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

Since:

2.1.1

Returns:

Type: planBuilder.PlanJoinKey

or(left, right) → {XsBoolean}

This function returns true if the specified expressions all return true. Otherwise, it returns false. Provides a client interface to a server function. See op.or

Parameters:

Name	Type	Argument	Description
`left`	XsAnyAtomicType	<optional>	The left value expression.
`right`	XsAnyAtomicType	<optional>	The right value expression.

Since:

2.1.1

Returns:

Type: XsBoolean

param(name) → {planBuilder.PlanParam}

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. Provides a client interface to a server function. See op.param

Parameters:

Name	Type	Argument	Description
`name`	XsString	<optional>	The name of the parameter.

Since:

2.1.1

Returns:

Type: planBuilder.PlanParam

patchBuilder(contextPath, namespaces) → {planBuilder.PatchBuilder}

Create a patch builder which can be used to chain patch operations. Provides a client interface to a server function. See op.patchBuilder

Parameters:

Name	Type	Argument	Description
`contextPath`	XsString	<optional>	The context path to patch.
`namespaces`	PlanXsStringMap	<optional>	Namespaces prefix (key) and uri (value).

Since:

3.4.0

Returns:

Type: planBuilder.PatchBuilder

pattern(subjects, predicates, objects, sysCols) → {planBuilder.PlanTriplePattern}

This function builds the parameters for the op:from-triples function. The result is passed to op:from-triples to project rows from the graph of triples. The columns in a pattern become the columns of the row. The literals in a pattern are used to match triples. You should specify at least one literal in each pattern, usually the predicate. Where a column appears in more than one pattern, the matched triples are joined to form the row. You can specify optional triples with a op:join-left-outer with a separate op:from-triples. Provides a client interface to a server function. See op.pattern

Parameters:

Name	Type	Argument	Description
`subjects`	PlanTriplePosition	<optional>	One column or one or more literal values, such as the literal returned by a sem:iri call.
`predicates`	PlanTriplePosition	<optional>	One column or one or more literal values, such as the literal returned by a sem.iri call.
`objects`	PlanTriplePosition	<optional>	One column or one or more literal values, such as the literal returned by a sem:iri call.
`sysCols`	PlanSystemColumn	<optional>	Specifies the result of an op:fragment-id-col or op:graph-col function to add columns for the fragment id or graph iri.

Since:

2.1.1

Returns:

Type: planBuilder.PlanTriplePattern

prefixer(base) → {planBuilder.Prefixer}

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. Provides a client interface to a server function. See op.prefixer

Parameters:

Name	Type	Argument	Description
`base`	XsString	<optional>	The base URI to be prepended to the name.

Since:

2.1.1

Returns:

Type: planBuilder.Prefixer

prop(key, value) → {planBuilder.PlanJsonProperty}

This function specifies the key expression and value content for a JSON property of a JSON object constructed by the op:json-object function. Provides a client interface to a server function. See op.prop

Parameters:

Name	Type	Argument	Description
`key`	XsString	<optional>	The key expression. This must evaluate to a string.
`value`	PlanJsonContentVal	<optional>	The value content. This must be exactly one JSON node expression.

Since:

2.1.1

Returns:

Type: planBuilder.PlanJsonProperty

redactDatetime(args) → {planBuilder.PlanExprCol}

This function redacts data that matches the pattern of a dateTime value. Controls the expected input format and the masking dateTime format.

Parameters:

Name	Type	Description
`args`		with column and options - Column is the name of the column to be defined. This can be either a string or the return value from PlanBuilder.col(), PlanBuilder.viewCol() or PlanBuilder.schemaCol(). Options is an object with name-value pairs specific to the redaction method.

Since:

2.7.0

Returns:

Type: planBuilder.PlanExprCol

redactEmail(args) → {planBuilder.PlanExprCol}

This function redacts data that matches the pattern of an email address. Controls whether to mask the entire address, only the username, or only the domain name.

Parameters:

Name	Type	Description
`args`		with column and options - Column is the name of the column to be defined. This can be either a string or the return value from PlanBuilder.col(), PlanBuilder.viewCol() or PlanBuilder.schemaCol(). Options is an object with name-value pairs specific to the redaction method.

Since:

2.7.0

Returns:

Type: planBuilder.PlanExprCol

redactIpv4(args) → {planBuilder.PlanExprCol}

This function redacts data that matches the pattern of an IPv4 address. Controls what character to use as a masking character.

Parameters:

Name	Type	Description
`args`		with column and options - Column is the name of the column to be defined. This can be either a string or the return value from PlanBuilder.col(), PlanBuilder.viewCol() or PlanBuilder.schemaCol(). Options is an object with name-value pairs specific to the redaction method.

Since:

2.7.0

Returns:

Type: planBuilder.PlanExprCol

redactNumber(args) → {planBuilder.PlanExprCol}

This function replaces values with random numbers. Controls the data type, range, and format of the masking values.

Parameters:

Name	Type	Description
`args`		with column and options - Column is the name of the column to be defined. This can be either a string or the return value from PlanBuilder.col(), PlanBuilder.viewCol() or PlanBuilder.schemaCol(). Options is an object with name-value pairs specific to the redaction method.

Since:

2.7.0

Returns:

Type: planBuilder.PlanExprCol

redactRegex(args) → {planBuilder.PlanExprCol}

This function redacts data that matches a given regular expression. You must specify the regular expression and the masking text.

Parameters:

Name	Type	Description
`args`		with column and options - Column is the name of the column to be defined. This can be either a string or the return value from PlanBuilder.col(), PlanBuilder.viewCol() or PlanBuilder.schemaCol(). Options is an object with name-value pairs specific to the redaction method.

Since:

2.7.0

Returns:

Type: planBuilder.PlanExprCol

redactUsPhone(args) → {planBuilder.PlanExprCol}

This function redacts data that matches the pattern of a US telephone number. Controls whether or not to preserve the last 4 digits and what character to use as a masking character.

Parameters:

Name	Type	Description
`args`		with column and options - Column is the name of the column to be defined. This can be either a string or the return value from PlanBuilder.col(), PlanBuilder.viewCol() or PlanBuilder.schemaCol(). Options is an object with name-value pairs specific to the redaction method.

Since:

2.7.0

Returns:

Type: planBuilder.PlanExprCol

redactUsSsn(args) → {planBuilder.PlanExprCol}

This function redacts data that matches the pattern of a US Social Security Number (SSN). Controls whether or not to preserve the last 4 digits and what character to use as a masking character.

Parameters:

Name	Type	Description
`args`		with column and options - Column is the name of the column to be defined. This can be either a string or the return value from PlanBuilder.col(), PlanBuilder.viewCol() or PlanBuilder.schemaCol(). Options is an object with name-value pairs specific to the redaction method.

Since:

2.7.0

Returns:

Type: planBuilder.PlanExprCol

resolveFunction(functionName, modulePath) → {planBuilder.PlanFunction}

Provides a client interface to a server function.

Parameters:

Name	Type	Argument	Description
`functionName`	PlanQualifiableName	<optional>	-
`modulePath`	XsString	<optional>	-

Since:

2.1.1

Returns:

Type: planBuilder.PlanFunction

rollup(keys) → {planBuilder.PlanGroup}

This function specifies a list of grouping keys for a group and returns that group and larger groups (including all rows) formed by dropping columns from right to left. The result is used for building the first parameter for the op:group-by-union or op:group-to-arrays functions. Provides a client interface to a server function. See op.rollup

Parameters:

Name	Type	Argument	Description
`keys`	PlanExprColName	<optional>	The columns to use as grouping keys. 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.

Since:

2.1.1

Returns:

Type: planBuilder.PlanGroup

sample(name, column) → {planBuilder.PlanAggregateCol}

This function randomly selects one non-null value of the column from the rows in the group or row set. The result is used for building the parameters used by the op:group-by function. Provides a client interface to a server function. See op.sample

Parameters:

Name	Type	Argument	Description
`name`	PlanColumnName	<optional>	The name to be used for the value.
`column`	PlanExprColName	<optional>	The group or row set.

Since:

2.1.1

Returns:

Type: planBuilder.PlanAggregateCol

schemaCol(schema, view, column) → {planBuilder.PlanColumn}

Unambiguously identifies a column with the schema name, view name, and column name. Useful only for columns provided by a view. Provides a client interface to a server function. See op.schemaCol

Parameters:

Name	Type	Argument	Description
`schema`	XsString	<optional>	The name of the schema.
`view`	XsString	<optional>	The name of the view.
`column`	XsString	<optional>	The name of the column.

Since:

2.1.1

Returns:

Type: planBuilder.PlanColumn

sequenceAggregate(name, column, option) → {planBuilder.PlanAggregateCol}

This call constructs a sequence whose items are the values of a column for each row in the group or row set. The result is used for building the parameters used by the op:group-by function. Provides a client interface to a server function. See op.sequenceAggregate

Parameters:

Name	Type	Argument	Description
`name`	PlanColumnName	<optional>	The name to be used for the aggregated column.
`column`	PlanExprColName	<optional>	The column with the values to aggregate.
`option`	PlanValueOption	<optional>	The options can take a values key with a distinct value to average the distinct values of the column.

Since:

2.1.1

Returns:

Type: planBuilder.PlanAggregateCol

sqlCondition(expression) → {planBuilder.PlanCondition}

This function returns a filter definition as input for a WHERE operation. As with a cts:query or sem:store, the filter definition cannot be used in an Optic Boolean expression but, instead, must be the only argument to the WHERE call. Add a separate WHERE call to filter based on an Optic Boolean expression. The condition must be a valid simple SQL Boolean expression expressed as a string. Provides a client interface to a server function. See op.sqlCondition

Parameters:

Name	Type	Argument	Description
`expression`	XsString	<optional>	A boolean expression, such as op:eq or op:not, that might be null.

Since:

2.1.1

Returns:

Type: planBuilder.PlanCondition

subtract(left, right) → {XsNumeric}

This function subtracts the right numericExpression from the left numericExpression and returns the value. Provides a client interface to a server function. See op.subtract

Parameters:

Name	Type	Argument	Description
`left`	XsAnyAtomicType	<optional>	The left numeric expression.
`right`	XsAnyAtomicType	<optional>	The right numeric expression.

Since:

2.1.1

Returns:

Type: XsNumeric

sum(name, column, option) → {planBuilder.PlanAggregateCol}

This function adds the non-null values of the column for the rows in the group or row set. The result is used for building the parameters used by the op:group-by function. Provides a client interface to a server function. See op.sum

Parameters:

Name	Type	Argument	Description
`name`	PlanColumnName	<optional>	The name to be used for the aggregated column.
`column`	PlanExprColName	<optional>	The column with the values to add.
`option`	PlanValueOption	<optional>	The options can take a values key with a distinct value to average the distinct values of the column.

Since:

2.1.1

Returns:

Type: planBuilder.PlanAggregateCol

uda(name, column, module, function, arg) → {planBuilder.PlanAggregateCol}

This function processes the values of column for each row in the group or row set with the specified user-defined aggregate as implemented by an aggregate user-defined function (UDF) plugin. The UDF plugin must be installed on each host. The result is used for building the parameters used by the op:group-by function. Provides a client interface to a server function. See op.uda

Parameters:

Name	Type	Argument	Description
`name`	PlanColumnName	<optional>	The name to be used for the aggregated column.
`column`	PlanExprColName	<optional>	The column with the values to aggregate.
`module`	XsString	<optional>	The path to the installed plugin module.
`function`	XsString	<optional>	The name of the UDF function.
`arg`	XsAnyAtomicType	<optional>	The options can take a values key with a distinct value to average the distinct values of the column and an arg key specifying an argument for the user-defined aggregate. The value can be a string or placeholder parameter.

Since:

2.1.1

Returns:

Type: planBuilder.PlanAggregateCol

viewCol(view, column) → {planBuilder.PlanColumn}

Identifies a column where the combination of view and column name is unique. Identifying the schema isn't necessary (and it might not exist). Provides a client interface to a server function. See op.viewCol

Parameters:

Name	Type	Argument	Description
`view`	XsString	<optional>	The name of the view.
`column`	XsString	<optional>	The name of the column.

Since:

2.1.1

Returns:

Type: planBuilder.PlanColumn

when(condition, value) → {planBuilder.PlanCase}

This function executes the specified expression if the specified condition is true for the row. Otherwise, the expression is not executed and the next 'when' test is checked or, if there is no next 'when' text, the otherwise expression for the op:case expression is executed. Provides a client interface to a server function. See op.when

Parameters:

Name	Type	Argument	Description
`condition`	XsBoolean	<optional>	A boolean expression.
`value`	Item	<optional>	The value expression to return if the boolean expression is true.

Since:

2.1.1

Returns:

Type: planBuilder.PlanCase

xmlAttribute(name, value) → {AttributeNode}

This function constructs an XML attribute with the name (which can be a string or QName) and atomic value. Provides a client interface to a server function. See op.xmlAttribute

Parameters:

Name	Type	Argument	Description
`name`	PlanQualifiableName	<optional>	The attribute name.
`value`	XsAnyAtomicType	<optional>	The attribute value.

Since:

2.1.1

Returns:

Type: AttributeNode

xmlComment(content) → {CommentNode}

This function constructs an XML comment with the atomic value. Provides a client interface to a server function. See op.xmlComment

Parameters:

Name	Type	Argument	Description
`content`	XsAnyAtomicType	<optional>	The comment text.

Since:

2.1.1

Returns:

Type: CommentNode

xmlDocument(root) → {DocumentNode}

This function constructs an XML document with the root content, which must be exactly one node. Provides a client interface to a server function. See op.xmlDocument

Parameters:

Name	Type	Argument	Description
`root`	XmlRootNode	<optional>	The XML node used to construct the XML document.

Since:

2.1.1

Returns:

Type: DocumentNode

xmlElement(name, attributes, content) → {ElementNode}

This function constructs an XML element with the name (which can be a string or QName), zero or more attributes, and child content. The child content can include a sequence or array of atomic values or an element, comment, or processing instruction nodes. Atomic values are converted to text nodes. Provides a client interface to a server function. See op.xmlElement

Parameters:

Name	Type	Argument	Description
`name`	PlanQualifiableName	<optional>	The string or QName for the constructed element.
`attributes`	AttributeNode	<optional>	Any element attributes returned from op:xml-attribute, or null if no attributes.
`content`	PlanXmlContentVal	<optional>	A sequence or array of atomic values or an element, a comment from op:xml-comment, or processing instruction nodes from op:xml-pi.

Since:

2.1.1

Returns:

Type: ElementNode

xmlPi(name, value) → {ProcessingInstructionNode}

This function constructs an XML processing instruction with the atomic value. Provides a client interface to a server function. See xmlPI

Parameters:

Name	Type	Argument	Description
`name`	XsString	<optional>	The name of the processing instruction.
`value`	XsAnyAtomicType	<optional>	The value of the processing instruction.

Since:

2.1.1

Returns:

Type: ProcessingInstructionNode

xmlText(value) → {TextNode}

This function constructs an XML text node with the specified value. Provides a client interface to a server function. See op.xmlText

Parameters:

Name	Type	Argument	Description
`value`	XsAnyAtomicType	<optional>	The value of the XML text node.

Since:

2.1.1

Returns:

Type: TextNode

xpath(column, path, namespaceBindings) → {Node}

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. Provides a client interface to a server function. See op.xpath

Parameters:

Name	Type	Argument	Description
`column`	PlanColumnName	<optional>	The name of the column from which to extract the child nodes.
`path`	XsString	<optional>	An XPath (specified as a string) to apply to each node.
`namespaceBindings`	PlanNamespaceBindings	<optional>	A map of namespace bindings. The keys should be namespace prefixes and the values should be namespace URIs. These namespace bindings will be added to the in-scope namespace bindings in the evaluation of the path.

Since:

2.1.1

Returns:

Type: Node