MarkLogic Node.js Client API

Namespace: documents

documents

Provides functions to write, read, query, or perform other operations on documents in the database. For operations that modify the database, the client must have been created for a user with the rest-writer role. For operations that read or query the database, the user need only have the rest-reader role.

Methods

advanceLsqt(temporalCollection, lag) → {ResultProvider}

Advances the LSQT (Last Stable Query Time) of a temporal collection.
Parameters:
Name Type Argument Description
temporalCollection string The name of the temporal collection for which to advance the LSQT.
lag string <optional>
 The lag (in seconds (???)) to subtract from the maximum system start time in the temporal collection to determine the LSQT.
Since:
  • 2.1.1
Returns:
an object whose result() function takes an object with the new LSQT as an 'lsqt' property.
Type
ResultProvider

createWriteStream(uri, collections, permissions, properties, quality, metadataValues, versionId, txid, transform) → {WritableStream}

Writes a large document (typically a binary) in incremental chunks with a stream; takes a documents.DocumentDescriptor object with the following properties (but not a content property).
Parameters:
Name Type Argument Description
uri string the identifier for the document to write to the database
collections Array.<string> <optional>
 the collections to which the document should belong
permissions Array.<object> <optional>
 the permissions controlling which users can read or write the document
properties Array.<object> <optional>
 additional properties of the document
quality number <optional>
 a weight to increase or decrease the rank of the document
metadataValues Array.<object> <optional>
 the metadata values of the document
versionId number <optional>
 an identifier for the currently stored version of the document (when enforcing optimistic locking)
txid string | transactions.Transaction <optional>
 a string transaction id or Transaction object identifying an open multi-statement transaction
transform string | Array.<mixed> <optional>
 the name of a transform extension to apply to each document or an array with the name of the transform extension and an object of parameter values; the transform must have been installed using the transforms#write function.
Since:
  • 1.0
Returns:
a stream for writing the database document; the stream object also has a result() function that takes a documents#writeResult success callback.
Type
WritableStream

patch(uri, operations, categories, temporalCollection, temporalDocument, sourceDocument, txid, versionId) → {ResultProvider}

Applies changes to a document; takes a configuration object with the following named parameters or, as a shortcut, a uri string and one or more patch operations produced by a patchBuilder.
Parameters:
Name Type Argument Description
uri string the uri
operations patchOperation | Array.<patchOperation> delete, insert, or replace operations produced by a patchBuilder to apply to the document.
categories documents.categories | Array.<documents.categories> <optional>
 the categories of information modified by the patch (typically 'content')
temporalCollection string <optional>
 the name of the temporal collection; use only when patching temporal documents
temporalDocument string <optional>
 the collection URI for the temporal document to be patched; use only when patching temporal documents
sourceDocument string <optional>
 the source collection URI for patching the temporal document; use only when writing temporal documents
txid string | transactions.Transaction <optional>
 a string transaction id or Transaction object identifying an open multi-statement transaction to patch the document as part of a larger multi-statement transaction
versionId number <optional>
 an identifier for the currently stored version of the document (when enforcing optimistic locking)
Since:
  • 1.0
Returns:
an object whose result() function takes a documents#patchResult success callback.
Type
ResultProvider

probe(uri, txid) → {ResultProvider}

Probes whether a document exists; takes a configuration object with the following named parameters or, as a shortcut, a uri string.
Parameters:
Name Type Argument Description
uri string the uri for the database document
txid string | transactions.Transaction <optional>
 a string transaction id or Transaction object identifying an open multi-statement transaction
Since:
  • 1.0
Returns:
an object whose result() function takes a documents#probeResult success callback.
Type
ResultProvider

protect(uri, temporalCollection, duration, expireTime, level, archivePath) → {ResultProvider}

Protects a temporal document from temporal operations for a period of time.
Parameters:
Name Type Argument Description
uri string the uri for the temporal document to protect
temporalCollection string the temporal collection for the document
duration string <optional>
 a protection duration; either a duration or an expire time must be provided
expireTime string <optional>
 an expiration time; either an expiration time or a duration must be provided
level string <optional>
 a protection level of 'noWipe'|'noDelete'|'noUpdate' (default is 'noDelete')
archivePath string <optional>
 an archive path
Since:
  • 2.0.1
Returns:
an object whose result() function takes a documents#protectResult success callback.
Type
ResultProvider

query(query, timestamp) → {ResultProvider}

Executes a query built by a queryBuilder to match one or more documents.
Parameters:
Name Type Argument Description
query object a query built by a queryBuilder or a documents.CombinedQueryDefinition
timestamp DatabaseClient.Timestamp <optional>
 a Timestamp object for point-in-time operations.
Since:
  • 1.0
Returns:
an object whose result() function takes a documents#resultList success callback.
Type
ResultProvider

read(uris, categories, txid, transform, range, timestamp) → {ResultProvider}

Reads one or more documents; takes a configuration object with the following named parameters or, as a shortcut, one or more uri strings or an array of uri strings.
Parameters:
Name Type Argument Description
uris string | Array.<string> the uri string or an array of uri strings for the database documents
categories documents.categories | Array.<documents.categories> <optional>
 the categories of information to retrieve for the documents
txid string | transactions.Transaction <optional>
 a string transaction id or Transaction object identifying an open multi-statement transaction
transform string | Array.<mixed> <optional>
 the name of a transform extension to apply to each document or an array with the name of the transform extension and an object of parameter values; the transform must have been installed using the transforms#write function.
range Array.<number> <optional>
 the range of bytes to extract from a binary document; the range is specified with a zero-based start byte and the position after the end byte as in Array.slice()
timestamp DatabaseClient.Timestamp <optional>
 a Timestamp object for point-in-time operations.
Since:
  • 1.0
Returns:
an object whose result() function takes a documents#resultList success callback.
Type
ResultProvider

remove(uris, txid, temporalCollection, systemTime) → {ResultProvider}

Removes one or more database documents; takes a configuration object with the following named parameters or, as a shortcut, one or more uri strings or an array of uri strings.
Parameters:
Name Type Argument Description
uris string | Array.<string> the uri string or an array of uri strings identifying the database documents
txid string | transactions.Transaction <optional>
 a string transaction id or Transaction object identifying an open multi-statement transaction
temporalCollection string <optional>
 the name of the temporal collection; use only when deleting a document created as a temporal document; sets the system end time to record when the document was no longer active
systemTime string | Date <optional>
 a datetime to use as the system end time instead of the current time of the database server; can only be supplied if the temporalCollection parameter is also supplied
Since:
  • 1.0
Returns:
an object whose result() function takes a documents#removeResult success callback.
Type
ResultProvider

removeAll(collection, directory) → {ResultProvider}

Removes all documents in a collection, directory, or database; takes a configuration object with the following named parameters or no parameters to delete all documents. The user must have the rest-admin role to to delete all documents and the rest-writer role otherwise.
Parameters:
Name Type Argument Description
collection string <optional>
 the collection whose documents should be deleted
directory string <optional>
 a directory whose documents should be deleted
Since:
  • 1.0
Returns:
an object with a result() function taking success and failure callbacks.
Type
ResultProvider

suggest(partial, query, bindings, limit) → {ResultProvider}

For a partial textual value intended for a string search, looks up completions that match documents in the database. The textual value may be prefixed with the constraint name for a string search binding or facet. The textual value may also be an unqualified word or phrase for the default binding. You may pass a configuration object with the following named parameters or, as a shortcut, the partial textual search, the query, and optionally bindings.
Parameters:
Name Type Argument Description
partial string the partial search string to complete
query object a query built by a queryBuilder or a documents.CombinedQueryDefinition that defines bindings in the where and calculate clause and that qualifies the documents supplying the completions for the partial search string
bindings queryBuilder.SuggestBindings <optional>
 bindings returned by the queryBuilder#suggestBindings function that override the query bindings to retrieve completions from a different index
limit number <optional>
 the number of completions to return
Since:
  • 1.0
Returns:
an object whose result() function takes a success callback that receives an array with the candidate completion strings.
Type
ResultProvider

wipe(uri, temporalCollection) → {ResultProvider}

Deletes all versions of a temporal document.
Parameters:
Name Type Description
uri string the uri for the temporal document to wipe
temporalCollection string the name of the temporal collection
Since:
  • 2.0.1
Returns:
an object whose result() function takes a documents#wipeResult success callback.
Type
ResultProvider

write(documents, categories, txid, transform, forestName, temporalCollection, systemTime) → {ResultProvider}

Writes one or more documents; takes a configuration object with the following named parameters or, as a shortcut, a document descriptor.
Parameters:
Name Type Argument Description
documents DocumentDescriptor | Array.<DocumentDescriptor> one descriptor or an array of document descriptors to write
categories documents.categories | Array.<documents.categories> <optional>
 the categories of information to write for the documents
txid string | transactions.Transaction <optional>
 a string transaction id or Transaction object identifying an open multi-statement transaction
transform string | Array.<mixed> <optional>
 the name of a transform extension to apply to each document or an array with the name of the transform extension and an object of parameter values; the transform must have been installed using the transforms#write function.
forestName string <optional>
 the name of a forest in which to write the documents.
temporalCollection string <optional>
 the name of the temporal collection; use only when writing temporal documents that have the JSON properties or XML elements specifying the valid and system start and end times as defined by the valid and system axis for the temporal collection
systemTime string | Date <optional>
 a datetime to use as the system start time instead of the current time of the database server; can only be supplied if the temporalCollection parameter is also supplied
Since:
  • 1.0
Returns:
an object whose result() function takes a documents#writeResult success callback.
Type
ResultProvider

Type Definitions

categories

Categories of information to read or write for documents. The possible values of the enumeration are content|collections|metadataValues|permissions|properties|quality|metadata|none where metadata is an alias for all of the categories other than content.
Type:
  • enum
Since:
  • 1.0

CombinedQueryDefinition

Defines a query in the structure accepted by the REST API.
Type:
  • object
Properties:
Name Type Argument Description
search object a combined query, which can have properties for a structured query, a string query, and query options
categories documents.categories | Array.<documents.categories> <optional>
 the categories of information to retrieve for the result documents
optionsName string <optional>
 query options installed on the REST server to merge with any query options provided in the combined query; provided options take precedence over installed options
pageStart number <optional>
 the position of the first document in the returned page of result documents (also known as the result slice)
pageLength number <optional>
 the number of documents in the returned page of result documents
view string <optional>
 a value from the enumeration all|facets|metadata|none|results|uris controlling whether to generate some or all of a search response summarizing the search response in addition to the result documents; the default is 'none' to return only the result documents
Since:
  • 1.0

DocumentDescriptor

Provides a description of a document to write to the server, after reading from the server, or for another document operation. The descriptor may have more or fewer properties depending on the operation.
Type:
  • object
Properties:
Name Type Argument Description
uri string the identifier for the document in the database
content object | string | Buffer | ReadableStream <optional>
 the content of the document; when writing a ReadableStream for the content, first pause the stream
collections Array.<string> <optional>
 the collections to which the document belongs
permissions Array.<object> <optional>
 the permissions controlling which users can read or write the document
properties Array.<object> <optional>
 additional properties of the document
quality number <optional>
 a weight to increase or decrease the rank of the document
metadataValues Array.<object> <optional>
 the metadata values of the document
versionId number <optional>
 an identifier for the currently stored version of the document
temporalDocument string <optional>
 the collection URI for a temporal document; use only when writing a document to a temporal collection
Since:
  • 1.0

patchResult(document)

A success callback for ResultProvider that receives the result from the documents#patch function.
Parameters:
Name Type Description
document object a sparse documents.DocumentDescriptor object providing the uri of the patched document.
Since:
  • 1.0

probeResult(document)

A success callback for ResultProvider that receives the result from the documents#probe.
Parameters:
Name Type Description
document documents.DocumentDescriptor a sparse document descriptor with an exists property that identifies whether the document exists
Since:
  • 1.0

protectResult(document)

A success callback for ResultProvider that receives the result from the documents#protect.
Parameters:
Name Type Description
document documents.DocumentDescriptor a sparse document descriptor for the protected document
Since:
  • 2.0.1

removeResult(document)

A success callback for ResultProvider that receives the result from the documents#remove.
Parameters:
Name Type Description
document documents.DocumentDescriptor a sparse document descriptor for the removed document
Since:
  • 1.0

resultList(documents)

A success callback for ResultProvider that receives the result from the documents#read.
Parameters:
Name Type Description
documents Array.<documents.DocumentDescriptor> an array of documents.DocumentDescriptor objects with the requested metadata and/or content for the documents
Since:
  • 1.0

wipeResult(document)

A success callback for ResultProvider that receives the result from the documents#wipe.
Parameters:
Name Type Description
document documents.DocumentDescriptor a sparse document descriptor for the wipe command
Since:
  • 2.0.1

writeResult(response)

A success callback for ResultProvider that receives the result from the documents#write or the documents#createWriteStream functions.
Parameters:
Name Type Description
response object a response with a documents property providing a sparse array of array of documents.DocumentDescriptor objects providing the uris of the written documents.
Since:
  • 1.0
Copyright (c) 2020 MarkLogic Corporation Documentation generated by JSDoc 3.6.4 on 2020-08-04T23:55:49-07:00 using the DocStrap template.