MarkLogic 12 EA 2 Product Documentation
xdmp.documentLoadxdmp.documentLoad(
location as String,
[options as Object?]
) as null
Summary
Inserts a new document with the specified URI. If a document already exists
at the URI, the function replaces the content in the existing document as
an update operation.
Parameters |
location |
The location of the input document. If the scheme of the location is
HTTP (that is, if the string starts with "http://"), then the document is
requested over HTTP. If the scheme is file (that is, if the string starts
with "file://"), then the document is requested over file protocol from
the local filesystem.
Otherwise, the document is fetched from the local
filesystem. On the filesystem, the path can be fully qualified or relative.
Relative pathnames are resolved from the directory in which
MarkLogic Server is installed.
|
options |
Options with which to customize this operation.
This function supports the following options, plus the options from the
xdmp.httpGet function.
- uri
- The URI of the document to be loaded. If omitted, then the location
is used for the URI.
- permissions
- Security permission corresponding to the permissions for the
document. If not supplied, the current user's default permissions are
applied. The default value used for $permissions can be obtained by
calling
xdmp.defaultPermissions() . A document that
is created by a non-admin user (that is, by any user who does not have the
admin role) must have at least one update permission,
otherwise the creation will throw an XDMP-MUSTHAVEUPDATE
exception.
- collections
- The collection URIs for collections to which this document belongs.
If not supplied, the document is added to the current user's default
collections (the collections returned from
xdmp.defaultCollections() ). For each
collection that is protected, the user must have permissions to update
that collection or have the any-collection privilege. For
each unprotected collection, the user must have the
unprotected-collections privilege.
This option is an array of collection URIs.
- quality
- The quality of this document. A positive value increases the
relevance score of the document in text search functions. The converse is
true for a negative value. The default value is 0.
defaultNamespace
- (XML only) The namespace to use if there is no namespace at the root
node of the document. The default value is "".
- repair
- A value of
full specifies that malformed XML
content be repaired. A value of none specifies that
malformed XML content is rejected.
If no repair option is explicitly specified, the
default is none .
This option has no effect on binary, text or JSON documents.
- format
- A value of
text specifies to get the document as a text
document, regardless of the URI specified. A value of
binary specifies to get the document as a binary
document, regardless of the URI specified. A value of xml
specifies to get the document as an XML document, regardless of the
URI specified. A value of json
specifies to get the document as a JSON document, regardless of the
URI specified.
defaultLanguage
- The language to specify in an
xml:lang attribute on the
root element node if the root element node does not already have an
xml:lang attribute. This option applies only to XML documents.
If this option is not specified, then nothing is added to the root element
node.
- encoding
- Specifies the encoding to use when reading the document into MarkLogic
Server. The value must either be "auto" or match an encoding name
according to the Unicode Charset Alias Matching rules
(http://www.unicode.org/reports/tr22/#Charset_Alias_Matching).
When the value is "auto", MarkLogic guesses the encoding from
the document content. For a list of character set encodings by language, see
Collations and Character Sets By Language in the Search Developer's Guide.
If you do not set this option, MarkLogic uses the encoding
specified in the HTTP headers, if present. If you do not set this option
and no encoding is available from HTTP headers, the encoding
defaults to UTF-8. For more details, see
Character Encoding in the Search Developer's Guide.
- forests
- Specifies the ID of the forest in which this document is inserted.
This can be a single string or an array of
strings, with each string being a forest ID. . If the document
already exists in the database, it will remain in its existing forest. If
no such forest exists or if no such forest is attached to the context
database, an error is raised. If multiple forests
are specified, the document is inserted into one of the specified
forests. If the document already exists and the forest in which it is
stored is set to delete-only, then you must specify the forest IDs to
include one or more forests that allow updates, otherwise an exception is
thrown.
If you have local disk failover enabled, specify the ID of the master
forest. In the event of a failover, MarkLogic server will automatically
redirect documents to the replica forest. Specify the ID of the replica
forest will result in a "forest not in database" error.
- metadata
- Specifies key-value pairs representing user-defined metadata associated
with the document. Metadata values are strings. Non-string values are
converted to strings.
|
Required Privileges
http://marklogic.com/xdmp/privileges/xdmp-document-load
If a new document is inserted, you also need the
unprotected-uri
privilege (only if the URI is not protected),
the any-uri
privilege, or an appropriate URI privilege.
If adding an unprotected collection to a document, the
unprotected-collections
privilege
(http://marklogic.com/xdmp/privileges/unprotected-collections
)
is needed; if adding a protected collection, the user must have either
permissions to update the collection or the
any-collection
privilege
(http://marklogic.com/xdmp/privileges/any-collection
).
Usage Notes
When selecting documents over HTTP (where the $location
parameter begins with http://
), the response from the webserver
is loaded into the database, regardless of what the headers returned
from the webserver indicate. For example, if the webserver returns a
404 (file not found), then the response page that says "file not found"
is loaded into the database. If you want to examine the headers before
loading the document, use
xdmp.httpGet
(combined with
xdmp.documentInsert
) instead, as
xdmp.httpGet
allows you to examine the headers returned from the HTTP server.
Example
declareUpdate();
xdmp.documentLoad('c:\\myFile.json',
{ 'uri' : '/documents/myFile.json',
'permissions' : xdmp.defaultPermissions()
});
// Loads the document with a URI "/documents/myFile.json".
Example
declareUpdate();
xdmp.documentLoad('http://myCompany.com/file.json',
{
uri : '/documents/myFile.json',
permissions : xdmp.defaultPermissions(),
format : 'json',
authentication : {
username : 'user',
password : 'pass'
metadata: {foo:'bar'}
}
});
// Loads the document with a URI "/documents/myFile.json"
// from the server http://myCompany.com, sending the
// credentials user/pass. The document is loaded as JSON
// with the metadata, 'foo:bar'.
Example
declareUpdate();
xdmp.documentLoad('c:\myFile.json',
{
uri : '/documents/myFile.json',
permissions : xdmp.defaultPermissions(),
collections : ['myCollection1', 'myCollection2'],
forests : xdmp.forest('myForest')
});
// Loads the document with a URI "/documents/myFile.json", adding the
// document to the "myCollection1" and "myCollection2" collections,
// and loading the document into the forest named "myForest".
Stack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.