Namespace: DatabaseClient
DatabaseClient
A client object configured to write, read,
query, and perform other operations on a database as a user. The
client object is created by the marklogic.createDatabaseClient
function.
Members
-
-
#config
-
Provides access to namespaces that configure the REST server for the client. The client must have been created for a user with the rest-admin role.
-
Properties:
-
Name Type Description extlibs
config.extlibs provides functions that maintain the extension libraries on the REST server patch.replace
config.patch.replace provides functions that maintain patch replacement libraries on the REST server query.custom
config.query.custom provides functions that maintain custom query binding or facet extensions on the REST server query.snippet
config.query.snippet provides functions that maintain query snippet extensions on the REST server resources
config.resources provides functions that maintain resource service extensions on the REST server serverprops
config.serverprops provides functions that modify the properties of the REST server transforms
config.transforms provides functions that maintain transform extensions on the REST server
-
- Since:
-
- 1.0
-
-
-
#documents :documents
-
Provides functions that write, read, query, or perform other operations on documents in the database. As a convenience, the same functions are provided on the database client.
Type:
- Since:
-
- 1.0
-
-
#graphs :graphs
-
Provides functions that read, write, merge, remove, list, or query with SPARQL on triple graphs.
Type:
- Since:
-
- 1.0
-
-
#resources :resources
-
Provides functions that submit get, put, post, or remove requests to resource service extensions.
Type:
- Since:
-
- 1.0
-
-
#rows :rows
-
Provides functions for performing relational operations on indexed values and documents in the database.
Type:
- Since:
-
- 2.1.1
-
-
#transactions :transactions
-
Provides functions that open, commit, or rollback multi-statement transactions.
Type:
- Since:
-
- 1.0
-
-
#values :values
-
Provides functions that submit values queries to project tuples (rows) of values from documents.
Type:
- Since:
-
- 1.0
Methods
-
-
checkConnection()
-
Tests if a connection is successful.
- Since:
-
- 2.1
Returns:
an object with a connected property of true or false. In the false case it contains httpStatusCode and httpStatusMessage properties identifying the failure. -
-
createCollection(collection, content) → {ResultProvider}
-
Creates one or more JSON documents for a collection; takes a collection name string and the content for one or more JSON documents (or an array of content). The server assigns uri identifiers to the documents created with the content. The documents#write function is less simple but more complete, accepting a uri identifier and metadata (such as multiple collections) and optionally transforming each document on the server.
Parameters:
Name Type Description collection
string the name of the collection for the documents content
object | Array.<object> the objects with the content for the documents - Since:
-
- 1.0
Returns:
an object whose result() function takes a success callback receiving an array of uri strings for the created documents.- Type
- ResultProvider
-
-
createTimestamp(value) → {Timestamp}
-
Creates a timestamp object.
Parameters:
Name Type Argument Description value
string <optional>
a timestamp value as a string. - Since:
-
- 2.1.1
Returns:
- a Timestamp object.- Type
- Timestamp
-
-
eval(source, variables, txid) → {ResultProvider}
-
Evaluates JavaScript on the server; the user for the database client must have permission to evaluate code on the server and, in addition, permission to execute the actions performed by the source; takes a configuration object with the following named parameters or, as a shortcut, the source with or without variables.
Parameters:
Name Type Argument Description source
string the JavaScript source code variables
object <optional>
an object in which each property has a variable name as a key and a number, string, or boolean value 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 success callback that receives the response- Type
- ResultProvider
-
-
invoke(path, variables, txid) → {ResultProvider}
-
Invokes a JavaScript or XQuery module on the server; the user for the database client must have permission to invoke modules on the server and, in addition, permission to execute the actions performed by the module; takes a configuration object with the following named parameters or, as a shortcut, the path with or without variables.
Parameters:
Name Type Argument Description path
string the path of the module in the modules database for the REST server; the module must have been installed previously (typically with the config.extlibs#write function) using a filename extension (mjs, sjs, or xqy by default) registered for server JavaScript or XQuery in the server mime types table variables
object <optional>
an object in which each property has a variable name as a key and a number, string, or boolean value; the key may be in Clark notation for namespaced XQuery variables 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 success callback that receives the response- Type
- ResultProvider
-
-
probe(uri) → {ResultProvider}
-
Probes whether a document exists; takes a uri string identifying the document. The documents#probe function is less simple but more complete, returning an object with additional information.
Parameters:
Name Type Description uri
string the uri for the database document - Since:
-
- 1.0
Returns:
an object whose result() function takes a success callback that receives a boolean.- Type
- ResultProvider
-
-
queryCollection(collection, query) → {ResultProvider}
-
Executes a query to retrieve the content of documents in a collection, optionally adding a query built by a queryBuilder to retrieve a subset of the collection documents. The documents#query function is less simple but more complete, potentially transforming documents on the server and returning an envelope object for each document with the uri and metadata as well as the content. an object for each document with additional information.
Parameters:
Name Type Argument Description collection
string the name of the document collection query
object <optional>
a query built by a queryBuilder - Since:
-
- 1.0
Returns:
an object whose result() function takes a success callback that receives an array with the content of the documents.- Type
- ResultProvider
-
-
read(uris) → {ResultProvider}
-
Reads one or more documents; takes one or more uri strings or an array of uri strings. The documents#read function is less simple but more complete, potentially transforming documents on the server and returning an envelope object for each document with the uri and metadata as well as the content.
Parameters:
Name Type Description uris
string | Array.<string> the uri string or an array of uri strings for the database documents - Since:
-
- 1.0
Returns:
an object whose result() function takes a success callback that receives an array with the content of the documents.- Type
- ResultProvider
-
-
remove(uris) → {ResultProvider}
-
Removes one or more database documents; takes one or more uri strings identifying the document. The documents#remove function is less simple but more complete.
Parameters:
Name Type Description uris
string | Array.<string> the uri string or an array of uri strings identifying the database documents - Since:
-
- 1.0
Returns:
an object whose result() function takes a success callback that receives an array of the uris identifying the removed documents.- Type
- ResultProvider
-
-
removeCollection(collection) → {ResultProvider}
-
Removes all documents in a collection; takes the uri string identifying the collection. The documents#removeAll function is less simple but more complete, supporting deleting a directory or all documents in the database.
Parameters:
Name Type Description collection
string the collection whose documents should be deleted - Since:
-
- 1.0
Returns:
an object with a result() function takes a success callback that receives the uri string identifying the removed collection.- Type
- ResultProvider
-
-
setAuthToken(token)
-
Supplies a new authentication token to be used in subsequent requests instead of the current authentication token. Note: the token must be a SAML authentication token.
Parameters:
Name Type Description token
string an authentication token - Since:
-
- 2.2.0
-
-
setLogger(logger, isErrorFirst)
-
Supplies a logger to use for database interactions or, instead, takes a logging level from the debug|info|warn|error|silent enumeration (where silent is the initial setting) for the default console logger.
Parameters:
Name Type Argument Description logger
object an object providing debug(), info(), warn(), and error() logging methods such as a logger provided by the Bunyan or Winston logging libraries. isErrorFirst
boolean <optional>
whether an error should be logged as the first parameter; must be provided as true for Bunyan (but not for Winston); defaults to false - Since:
-
- 1.0
-
-
writeCollection(collection, documents) → {ResultProvider}
-
Inserts or updates one or more documents for a collection; takes a collection name string and an object that maps document uris to document content. The documents#write function is less simple but more complete, accepting a uri identifier and metadata (such as multiple collections) and optionally transforming each document on the server.
Parameters:
Name Type Description collection
string the name of the collection for the documents documents
object an object in which every key is the uri string for a document and every value is the content for the document - Since:
-
- 1.0
Returns:
an object whose result() function takes a success callback receiving an array of uri strings for the written documents.- Type
- ResultProvider
-
-
xqueryEval(source, variables, txid) → {ResultProvider}
-
Evaluates XQuery on the server; the user for the database client must have permission to evaluate code on the server and, in addition, permission to execute the actions performed by the source; takes a configuration object with the following named parameters or, as a shortcut, the source with or without variables.
Parameters:
Name Type Argument Description source
string the XQuery source code variables
object <optional>
an object in which each property has a variable name as a key and a number, string, or boolean value; the key may be a namespaced name in Clark notation 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 success callback that receives the response- Type
- ResultProvider
Type Definitions
-
-
Timestamp
-
An object representing a timestamp on the server.
Type:
- object
- Since:
-
- 2.1.1