|
|
xdmp:document-get(
|
|
$location as xs:string,
|
|
[$options as node()?]
|
| ) as node() |
|
|
|
Summary:
Returns the document in the file specified by $location.
|
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 qualifed or relative.
Relative pathnames are resolved from the directory in which
MarkLogic Server is installed.
|
$options
(optional):
The options node for getting this document. The default value is ().
The node for the xdmp:document-get options must be in the
xdmp:document-get namespace. This parameter can also include
option elements in the xdmp:http
namespace for the HTTP parameters.
The xdmp:document-get options include:
<default-namespace> - 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
implicitly specified by the XQuery version of the caller.
In XQuery 1.0 and 1.0-ml the default
is none. In XQuery 0.9-ml the
default is full.
This option has no effect on binary or text 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.
<default-language> - 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. If default-language 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. Supported values include
UTF-8,
ISO-8859-1, as well as many other popular encodings.
See the Search Developer's Guide for a list of character
set encodings by
language. All encodings will be translated into UTF-8
from the specified encoding. The string specifed for the
encoding option will be matched to an encoding name according
to the Unicode Charset Alias Matching rules
(http://www.unicode.org/reports/tr22/#Charset_Alias_Matching).
An automatic encoding detector will be used if the value auto
is specified.
If no encoding can be detected, the encoding defaults to UTF-8.
If no encoding option is specified, the encoding defaults to the
encoding specified in the http header (if using with one of the http
functions, for example, xdmp:http-get), otherwise it defaults
to UTF-8; any encoding http headers are ignored if there is any
value specified for the encoding option.
|
|
|
Required Privilege:
http://marklogic.com/xdmp/privileges/xdmp-document-get
|
Usage Notes:
If no format is specified in $options, and the document is from
an HTTP server, the format is specified by the document content type
from the HTTP response.
If no format is specified in $options, and the document is from
the filesystem, the format is specified by the document content type
from the filename extension.
The mimetype extensions and corresponding content types are set in the
Admin Interface.
If no repair option is specified,
the default is specified by the XQuery version of the caller.
In XQuery version 1.0 and 1.0-ml the default is
<repair>none</repair>. In XQuery version
0.9-ml the default is
<repair>full</repair>.
When the document is from an HTTP server,
xdmp:document-get will always return the response from the
HTTP server, even if it is an error response such as 404 or 500. If you
want to be able to examine the response header in your application, use
the xdmp:http-get instead, which
returns both the response header and the response.
|
Example:
xdmp:document-get("myDocument.xml")
=> the xml contained in myDocument.xml,
for example, <myDocument/>
|
Example:
xdmp:document-get("myDocument.html",
<options xmlns="xdmp:document-get">
<repair>full</repair>
</options>)
=> myDocument.html as an XML document that has gone
through any needed tag repair
|
Example:
xdmp:document-get("http://myCompany.com/file.xml",
<options xmlns="xdmp:document-get"
xmlns:http="xdmp:http">
<format>xml</format>
<http:authentication>
<http:username>user</http:username>
<http:password>pass</http:password>
</http:authentication>
</options>)
=> gets an XML document named file.xml, sending the
authentication credentials user/pass to the
http://myCompany.com server
|
|
|
|
xdmp:elapsed-time( ) as xs:dayTimeDuration
|
|
|
|
Summary:
Returns the elapsed time since the start of processing of this query. Gives
the same information as the elapsed-time element of the
xdmp:query-meters output, but has less overhead than calling
xdmp:query-meters.
|
Usage Notes:
Certain operations are run concurrently with the timing operations,
and if those operations are not actually used in the query, they might not
be included in the timings. This occurs for operations like
xdmp:estimate, xdmp:exists, and lexicon calls
(for example, cts:element-values). If you want to see the
total timings that include calls that are not used, you can form some other
expression with the results of the calls. For example, if you have an
expression that calls xdmp:estimate in a let
expression, you can add 0 to the output, which causes it to be included in
the timings (something like xdmp:estimate($query) + 0).
|
Example:
xquery version "1.0-ml";
fn:count(collection()),
xdmp:elapsed-time()
=> The count of the number of documents in the database followed by
the elapsed-time of the query:
153
PT0.04S
|
|
|
|
xdmp:get(
|
|
$path as xs:string,
|
|
[$default-namespace as xs:string?],
|
|
[$options as xs:string*]
|
| ) as node() |
|
|
Summary:
[DEPRECATED: use xdmp:document-get
instead] Returns the document in the XML file specified by $path.
This function is deprecated and will be removed from a future release.
Use xdmp:document-get instead.
|
Parameters:
|
$path
:
The path to the input file. The path can be fully qualifed or relative.
Relative pathnames are resolved from the directory in which MarkLogic
Server is installed.
|
|
$default-namespace
(optional):
Default namespace for nodes in the first parameter. If $default-namespace is
specified and the root node of the loaded document does not explicitly
specify a namespace, $default-namespace will be applied to the root node.
The default value for $default-namespace is "".
|
$options
(optional):
The options for getting this document.
The default value is ().
Options include:
- "repair-full"
- Specifies that malformed XML content be repaired.
This option has no effect on binary or text documents.
- "repair-none"
- Specifies that malformed XML content be rejected.
This option has no effect on binary or text documents.
- "format-text"
- Specifies to get the document as a text document,
regardless of the URI specified.
- "format-binary"
- Specifies to get the document as a binary document,
regardless of the URI specified.
- "format-xml"
- Specifies to get the document as an XML document,
regardless of the URI specified.
- "lang=en"
- Specifies that the document is in english.
|
|
Usage Notes:
If no format is specified in $options, it is specified by the
document content type specified by the extension of the document URI.
The mimetype extensions and corresponding content types are set in the
Admin Interface.
If neither "repair-full" nor "repair-none" is present,
the default is specified by the XQuery version of the caller.
In XQuery version 1.0 and 1.0-ml the default is
"repair-none". In XQuery version 0.9-ml the default is
"repair-full".
|
Example:
xdmp:get("foo.xml")
=> <foo/>
|
Example:
xdmp:get("foo.html", "", ("repair-full", "format-xml"))
=> foo.html as an XML document that has gone through any
needed tag repair
|
|
|
|
xdmp:log(
|
|
$msg as item()*,
|
|
[$level as xs:string?]
|
| ) as empty-sequence() |
|
|
|
Summary:
Logs a debug message to the log file
<install_dir>/Logs/ErrorLog.txt.
|
Parameters:
|
$msg
:
Message for logging.
|
|
$level
(optional):
One of: emergency, alert, critical, error, warning, notice, info,
config, debug, fine, finer, or finest. The default level is "info".
|
|
|
Example:
|
|
|
|
xdmp:query-meters( ) as element()
|
|
|
|
Summary:
Returns the current value of the resource meters for this
query sequence.
|
Usage Notes:
The resource meters returned include:
- elapsed-time
- The time elapsed since the start of the processing of this query,
in the form of a duration.
- requests
- The number of requests.
- list-cache-hits
- The number of successful list cache lookups. The list
cache holds search termlists used to accelerate path expressions and
text searches.
- list-cache-misses
- The number of unsuccessful list cache lookups. Each
unsuccessful list cache lookup was followed by a disk access to load the
search termlist into the cache.
- in-memory-list-hits
- The number of successful list lookups in in-memory
stands.
- expanded-tree-cache-hits
- The number of successful expanded tree cache lookups.
The expanded tree cache cache holds XML document data in the expanded
representation used by the XQuery evaluator.
- expanded-tree-cache-misses
- The number of unsuccessful expanded tree cache lookups.
Each unsuccessful expanded tree lookup was followed by a compressed tree
cache lookup to load the expanded tree into the cache.
- compressed-tree-cache-hits
- The number of successful compressed tree cache lookups.
The compressed tree cache holds XML document data in the compressed
representation stored on disk.
- compressed-tree-cache-misses
- The number of unsuccessful compressed tree cache lookups.
Each unsuccessful compressed tree cache lookup was followed by a disk
access to load the compressed tree into the cache.
- in-memory-compressed-tree-hits
- The number of successful compressed tree lookups in
in-memory stands.
- value-cache-hits
- The number of successful value cache lookups. The value
cache is a transient cache that exists only for the duration of one
query. It holds typed values, and is used to accelerate the frequent
conversion of nodes to typed values.
- value-cache-misses
- The number of unsuccessful value cache lookups. Each
unsuccessful value cache lookup was followed by a conversion of an XML
node to a typed value.
- regexp-cache-hits
- The number of successful regular expression cache
lookups. The regular expression cache is a transient cache that exists
only for the duration of one query. It holds compiled regular
expressions, and is used to accelerate the frequent use of regular
expressions during the evaluation of a query.
- regexp-cache-misses
- The number of unsuccessful regular expression cache
lookups. Each unsuccessful regular expression cache lookup was followed
by a compilation of a regular expression from source text.
- link-cache-hits
- The number of successful link cache lookups. The link
cache is a transient cache that exists only for the duration of one
query. It holds pointers to expanded trees, and is used to accelerate
the frequent dereferencing of link nodes.
- link-cache-misses
- The number of unsuccessful link cache lookups. Each
unsuccessful link cache lookup was followed by a search for the
link target tree.
- filter-hits
- The number of successful search filter matches.
- filter-misses
- The number of unsuccessful search filter matches.
- fragments-added
- The number of XML fragments added to the database by an
update.
- fragments-deleted
- The number of XML fragments deleted from the database by
an update.
- fs-program-cache-hits
- The number of module cache hits from the entire program made from
modules on the file system.
- fs-program-cache-misses
- The number of module cache misses from the entire program made from
modules on the file system.
- db-program-cache-hits
- The number of module cache hits from the entire program made from
modules in a database (may contain library modules from the special
Modules directory).
- db-program-cache-misses
- The number of module cache misses from the entire program made from
modules in a database (may contain library modules from the special
Modules directory).
- env-program-cache-hits
- The number of module cache hits from the entire program made from
ad hoc XSLT stylesheet nodes.
- env-program-cache-misses
- The number of module cache misses from the entire program made from
ad hoc XSLT stylesheet nodes.
- fs-main-module-sequence-cache-hits
- The number of main module cache hits from main modules on the
file system.
- fs-main-module-sequence-cache-misses
- The number of main module cache misses from main modules on the
file system.
- db-main-module-sequence-cache-hits
- The number of main module cache hits from main modules in a
database.
- db-main-module-sequence-cache-misses
- The number of main module cache misses from main modules in a
database.
- fs-library-module-cache-hits
- The number of library module cache hits from library modules on the
file system.
- fs-library-module-cache-misses
- The number of library module cache misses from library modules on the
file system.
- db-library-module-cache-hits
- The number of library module cache hits from library modules from the
modules database.
- db-library-module-cache-misses
- The number of library module cache misses from library modules from the
modules database.
Some meters are broken down by fragment root and document URI:
- fragments
- A sequence of fragment elements, each containing:
- root
- The fragment root name.
- expanded-tree-cache-hits
- A count of successful expanded tree cache lookups for this fragment
root.
- expanded-tree-cache-misses
- A count of unsuccessful expanded tree cache lookups for this
fragment root.
- documents
- A sequence of document elements, each containing:
- uri
- The document URI.
- expanded-tree-cache-hits
- A count of successful expanded tree cache lookups
for this document URI.
- expanded-tree-cache-misses
- A count of unsuccessful expanded tree cache lookups
for this document URI.
There are also meters that measure the query activity per host. There is
a qm:hosts element with one qm:host child per
host that participates in the query. Each qm:host element
contains meters showing the round-trip-time and round-trip-count for
communications between the evaluator host and the host referenced in the
xdmp:query-meters output. The qm:hosts element is
empty for a single-node cluster.
Certain operations are run concurrently with the timing operations,
and if those operations are not actually used in the query, they might not
be included in the timings. This occurs for operations like
xdmp:estimate, xdmp:exists, and lexicon calls
(for example, cts:element-values). If you want to see the
total timings that include calls that are not used, you can form some other
expression with the results of the calls. For example, if you have an
expression that calls xdmp:estimate in a let
expression, you can add 0 to the output, which causes it to be included in
the timings (something like xdmp:estimate($query) + 0).
|
Example:
xdmp:query-meters();
=>
<qm:query-meters
xsi:schemaLocation="http://marklogic.com/xdmp/query-meters
query-meters.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:qm="http://marklogic.com/xdmp/query-meters">
<qm:elapsed-time>PT0.22S</qm:elapsed-time>
<qm:requests>1</qm:requests>
<qm:list-cache-hits>0</qm:list-cache-hits>
<qm:list-cache-misses>0</qm:list-cache-misses>
<qm:in-memory-list-hits>0</qm:in-memory-list-hits>
<qm:expanded-tree-cache-hits>0
</qm:expanded-tree-cache-hits>
<qm:expanded-tree-cache-misses>0
</qm:expanded-tree-cache-misses>
<qm:compressed-tree-cache-hits>0
</qm:compressed-tree-cache-hits>
<qm:compressed-tree-cache-misses>0
</qm:compressed-tree-cache-misses>
<qm:in-memory-compressed-tree-hits>0
</qm:in-memory-compressed-tree-hits>
<qm:value-cache-hits>0</qm:value-cache-hits>
<qm:value-cache-misses>0</qm:value-cache-misses>
<qm:regexp-cache-hits>0</qm:regexp-cache-hits>
<qm:regexp-cache-misses>0</qm:regexp-cache-misses>
<qm:link-cache-hits>0</qm:link-cache-hits>
<qm:link-cache-misses>0</qm:link-cache-misses>
<qm:fragments-added>0</qm:fragments-added>
<qm:fragments-deleted>0</qm:fragments-deleted>
<qm:fs-program-cache-hits>1</qm:fs-program-cache-hits>
<qm:fs-program-cache-misses>0</qm:fs-program-cache-misses>
<qm:db-program-cache-hits>0</qm:db-program-cache-hits>
<qm:db-program-cache-misses>0</qm:db-program-cache-misses>
<qm:env-program-cache-hits>0</qm:env-program-cache-hits>
<qm:env-program-cache-misses>0</qm:env-program-cache-misses>
<qm:fs-main-module-sequence-cache-hits>0
</qm:fs-main-module-sequence-cache-hits>
<qm:fs-main-module-sequence-cache-misses>0
</qm:fs-main-module-sequence-cache-misses>
<qm:db-main-module-sequence-cache-hits>0
</qm:db-main-module-sequence-cache-hits>
<qm:db-main-module-sequence-cache-misses>0
</qm:db-main-module-sequence-cache-misses>
<qm:fs-library-module-cache-hits>0
</qm:fs-library-module-cache-hits>
<qm:fs-library-module-cache-misses>0
</qm:fs-library-module-cache-misses>
<qm:db-library-module-cache-hits>0
</qm:db-library-module-cache-hits>
<qm:db-library-module-cache-misses>0
</qm:db-library-module-cache-misses>
<qm:fragments/>
<qm:documents/>
<qm:hosts/>
</qm:query-meters>
|
Example:
xquery version "1.0-ml";
declare namespace qm="http://marklogic.com/xdmp/query-meters";
fn:count(collection()),
xdmp:query-meters()/qm:elapsed-time
=> The count of the number of documents in the database followed by
the elapsed-time element of the xdmp:query-trace XML output:
153
<qm:elapsed-time xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:qm="http://marklogic.com/xdmp/query-meters">
PT0.04S</qm:elapsed-time>
|
|
|