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
Plan
Prefixer
PreparePlan
cts
fn
geo
json
map
math
rdf
sem
spell
sql
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>
-
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, content, and score 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', or 'simple' 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.
Since:
  • 2.1.1
Returns:
Type
planBuilder.AccessPlan

fromSearchDocs(query, qualifierName) → {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.
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

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
Copyright (c) 2020 MarkLogic Corporation Documentation generated by JSDoc 4.0.0 on 2024-01-04T18:17:58-08:00 using the DocStrap template.