| XQUERY/XSLT API DOCUMENTATION 4.2 |
All XQuery & XSLT Functions MarkLogic Built-In Functions Admin (xdmp:) AppServer (xdmp:) Classifier (cts:) Debug (dbg:) Document Conversion (xdmp:) Extension (xdmp:) Documents, Directories, Properties, and Locks Functions Extension Functions Function Values Functions HTTP Functions JSON Functions MarkLogic Server Functions Search Functions XML Functions XQuery Context Functions XSLT Functions map (map:) Math (math:) Profile (prof:) Search (cts:) cts:query Constructors Functions Geospatial Functions Geospatial Lexicon Functions Lexicon Functions Search Functions Search Clustering Functions Security (xdmp:) Server Monitoring (xdmp:) Spell (spell:) Update (xdmp:) XQuery Library Modules Admin Library (admin:) Actions Functions Appserver Functions Database Functions Forest Functions Group Functions Host Functions Mimetypes Functions Scheduler Functions Alerting (alert:) Elastic Compute Cloud (ec2:) Entity Enrichment (entity:) Flexible Replication (flexrep:) Geospatial Supporting Functions GEO Functions GeoRSS Functions GML Functions KML Functions MCGM Functions Information Studio (info:) Information Studio Developer (infodev:) Library Services (dls:) cts:query Constructor Functions Document Management Functions Document Update Functions Retention Policy Functions XInclude Functions Modular Documents XInclude Functions XPointer Functions PKI (pki:) Plugin (plugin:) Search (search:) Security-sec (sec:) Spelling Dictionary Management (spell:) Thesaurus (thsr:) Triggers (trgr:) Triggers Library (trgr:) WordProcessingML (ooxml:) ZIP Package (ooxml:) CPF Functions Content Processing Framework (cpf:) CSS Conversion (css:) DocBook Conversion (dbk:) Domains (dom:) Excel Conversion (excel:) Generic Conversion (cvt:) Links (lnk:) MSWord Conversion (msword:) PDF Conversion (pdf:) Pipelines (p:) Powerpoint Conversion (ppt:) XHTML Conversion (xhtml:) W3C-Standard Functions Accessor (fn:) AnyURI (fn:) Boolean (fn:) Context (fn:) DurationDateTime (fn:) Error and Trace (fn:) Node (fn:) Numeric (fn:) QName (fn:) Sequence (fn:) String (fn:) XSLT (fn:) W3C XQuery/XSLT Reference W3C XQuery Functions W3C XQuery Language W3C XSLT Language
This page was generated September 12, 2012 6:01 AM | XQuery & XSLT Built-In & Modules Function Reference
Built-In: Profile
Implements a library of functions which allow developers to profile evaluation of XQuery programs. An XQuery program is defined as an XQuery main module, fully expanded with any XQuery library modules needed for its evaluation. To profile an XQuery program, set the `profile allow` option to `true` in the App Server or task server in which the request is serviced. If you request a profile report for an XQuery program whose App Server does not have profiling enabled (and if `prof:enable` is not called before generating the profile report), then the profile APIs do not profile the request, and the APIs that generate the report return the empty sequence. The profile functions use the `prof:` namespace prefix, which is predefined in the server.
Function Summary
prof:allowed | Returns the value of the Profile Allow setting for the App Server or Task Server upon which the target request is running.
prof:disable | Disable profiling for this request.
prof:enable | Enable profiling for this request.
prof:eval | Evaluate a string as an XQuery for profiling.
prof:invoke | Profiles and returns the result of evaluating a module at the given path.
prof:report | Return a prof:report node containing the current state of profiling statistics for the given request.
prof:reset | Clear any accumulated profiling statistics for the requests.
prof:value | Evaluate an expression in the context of the current evaluating statement and return the profiling report for its evaluation.
prof:xslt-eval | Evaluate a string as an XSLT stylesheet for profiling.
prof:xslt-invoke | Profiles and returns the result of evaluating an XSLT stylesheet at the given path.
Function Detail
prof:allowed(
| $request-id as xs:unsignedLong
) as xs:boolean
Summary: Returns the value of the Profile Allow setting for the App Server or Task Server upon which the target request is running. This function is useful to determine if subsequent calls to profiling functions will be effective.
Parameters:
$request-id : A request ID.
Required Privilege: Either `http://marklogic.com/xdmp/privileges/profile-my-requests` or `http://marklogic.com/xdmp/privileges/profile-any-requests` is required for profiling requests other than the current request, with the `profile-my-requests` privilege allowing profiling of requests issued by the same user ID, and the `profile-any-requests` privilege allowing profiling of requests issued by any user ID. No privilege is required to profile the currently running request (that is, self-profiling is always allowed).
Usage Notes: Use this function to determine if profiling is allowed on the App Server that owns the target request. This will indicate whether the other profiling functions will be effective. If the Profile Allow setting is off on the App Server, then calls to profiling functions do nothing and return the empty sequence. You can use `prof:allow` to test if profiling is allowed on the App Server, and if it is then use the other profiling APIs to profile other requests or to call `prof:eval` or `prof:invoke`; if it is not allowed, then your code does not call them. This type of logic allows you to keep profiling code in your XQuery code and it will only be executed if profiling is allowed in the context in which the code is run, thus allowing you to globally (at the App Server level) switch off profiling without breaking any code. Appropriate privileges are required to call this function, as with the other profiling functions. The return value is the state of the App Server Profile Allow setting. This function does not verify that the target request is stopped for debugging, which is required for one request to profile another.
Example:
      prof:allowed(xdmp:request())
      => true
Example:
    let $profallowed := prof:allowed(xdmp:request())
    return
    (
      if ( $profallowed )
      then ( prof:eval('fn:current-dateTime()') )
      else ( ),
      "your code here"
    )

      => The profile report (only if profiling is enabled
         on the App Server) followed by the output of your code.
prof:disable(
| $request-id as xs:unsignedLong
) as empty-sequence()
Summary: Disable profiling for this request. Profiling may be enabled or disabled as often as you like. Disabling does not clear accumulated profiling statistics. Disabling while disabled has no effect. If profiling is not allowed for the App Server, this function does nothing.
Parameters:
$request-id : A request ID. Use the `xdmp:request()` function, which returns the request ID for the currently running request, to specify the current request.
Required Privilege: Either `http://marklogic.com/xdmp/privileges/profile-my-requests` or `http://marklogic.com/xdmp/privileges/profile-any-requests` is required for profiling requests other than the current request, with the `profile-my-requests` privilege allowing profiling of requests issued by the same user ID, and the `profile-any-requests` privilege allowing profiling of requests issued by any user ID. No privilege is required to profile the currently running request (that is, self-profiling is always allowed).
Usage Notes: Any expressions evaluated after `prof:disable` is called (but before `prof:enable` is called again) will not be profiled and will not appear in the profile report.
Example:
      prof:disable(xdmp:request())
      => ()
Example:
    prof:enable(xdmp:request()),
    fn:concat("hello", " world"),
    prof:disable(xdmp:request()),
    fn:current-dateTime(),
    prof:report(xdmp:request())

      => A profile report that does not include
         the call to fn:current-dateTime().
prof:enable(
| $request-id as xs:unsignedLong
) as empty-sequence()
Summary: Enable profiling for this request. Profiling may be enabled or disabled as often as you like. Enabling while a request is enabled has no effect. If profiling is not allowed for the App Server, this function does nothing. Note that profiling does not cross eval/invoke boundaries. If the request being profiled calls xdmp:eval or xdmp:invoke, the individual expressions in that code will not be profiled. The overall time taken by the called code will appear as a single call in the caller's profiling report.
Parameters:
$request-id : A request ID. Use the `xdmp:request()` function, which returns the request ID for the currently running request, to specify the current request.
Required Privilege: Either `http://marklogic.com/xdmp/privileges/profile-my-requests` or `http://marklogic.com/xdmp/privileges/profile-any-requests` is required for profiling requests other than the current request, with the `profile-my-requests` privilege allowing profiling of requests issued by the same user ID, and the `profile-any-requests` privilege allowing profiling of requests issued by any user ID. No privilege is required to profile the currently running request (that is, self-profiling is always allowed).
Example:
      prof:enable(xdmp:request())
      => ()
prof:eval(
| $xquery as xs:string,
| [$vars as item()*],
| [$options as node()?]
) as item()*
Summary: Evaluate a string as an XQuery for profiling. A `prof:report` node will be prepended to any output produced by evaluating the string. If profiling is not allowed for the App Server, this function will throw a `PROF-PROFILEALLOW` exception. Note that profiling does not cross eval/invoke boundaries. If the request being profiled calls xdmp:eval or xdmp:invoke, the individual expressions in that code will not be profiled. The overall time taken by the called code will appear as a single call in the caller's profiling report.
Parameters:
$xquery : The XQuery string to be evaluated. If the XQuery string contains double quotes ("), surround the string with single quotes (').
$vars (optional): The external variable values for this evaluation. This must be a sequence of even length, alternating QNames and items. Each QName and item pair specify a variable name and value.
$options (optional): The options node, as for `xdmp:eval`. Must be in the `xdmp:eval` namespace.
Required Privilege: Either `http://marklogic.com/xdmp/privileges/profile-my-requests` or `http://marklogic.com/xdmp/privileges/profile-any-requests` is required for `prof:eval` (the `profile-my-requests` privilege is suffient because the resulting request is always run by the same user who initiated the call, but the `profile-any-requests` privilege will also work).
Example:
      prof:eval("xdmp:random()")
      => (<prof:report>...</prof:report>,9478952250821284456)
prof:invoke(
| $path as xs:string,
| [$vars as item()*],
| [$options as node()?]
) as item()*
Summary: Profiles and returns the result of evaluating a module at the given path. Any result produced by the evaluation will be prepended with a `prof:report` node containing timing and count information about the evaluation. If profiling is not allowed for the App Server, this function will throw a `PROF-PROFILEALLOW` exception. Note that profiling does not cross eval/invoke boundaries. If the request being profiled calls xdmp:eval or xdmp:invoke, the individual expressions in that code will not be profiled. The overall time taken by the called code will appear as a single call in the caller's profiling report.
Parameters:
$path : The path of the module to be executed. The path is resolved against the root of the App Server evaluating the query. The path must resolve to a main module (not a library module).
$vars (optional): The external variable values for this evaluation. This must be a sequence of even length, alternating QNames and items. Each QName and item pair specify a variable name and value.
$options (optional): The options node. The default value is (). The node must be in the `xdmp:eval` namespace. See the `xdmp:eval` section for a list of options.
Required Privilege: Either `http://marklogic.com/xdmp/privileges/profile-my-requests` or `http://marklogic.com/xdmp/privileges/profile-any-requests` is required for `prof:invoke` (the `profile-my-requests` privilege is suffient because the resulting request is always run by the same user who initiated the call, but the `profile-any-requests` privilege will also work).
Example:
      prof:invoke("http://example.com/modules/foo.xqy")
      => (<prof:report>...</prof:report>,42)
prof:report(
| $request-id as xs:unsignedLong
) as element(prof:report)?
Summary: Return a `prof:report` node containing the current state of profiling statistics for the given request. If profiling has never been enabled for the request, the empty sequence is returned. If profiling is not allowed for the App Server, this function returns an empty sequence.
Parameters:
$request-id : A request ID. Use the `xdmp:request()` function, which returns the request ID for the currently running request, to specify the current request.
Required Privilege: Either `http://marklogic.com/xdmp/privileges/profile-my-requests` or `http://marklogic.com/xdmp/privileges/profile-any-requests` is required for profiling requests other than the current request, with the `profile-my-requests` privilege allowing profiling of requests issued by the same user ID, and the `profile-any-requests` privilege allowing profiling of requests issued by any user ID. No privilege is required to profile the currently running request (that is, self-profiling is always allowed).
Example:
    (: Before running this, make sure profiling is enabled
       on the App Server :)
    prof:enable(xdmp:request()),
    fn:current-dateTime(),
    prof:report(xdmp:request())
    =>

    2007-02-16T19:24:30.093-08:00
    <prof:report xsi:schemaLocation="http://marklogic.com/xdmp/profile
       profile.xsd"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:prof="http://marklogic.com/xdmp/profile">
      <prof:metadata>
        <prof:overall-elapsed>PT0S</prof:overall-elapsed>
        <prof:created>2007-02-16T19:24:30.093-08:00</prof:created>
        <prof:server-version>3.2-20070214</prof:server-version>
      </prof:metadata>
      <prof:histogram>
        <prof:expression>
          <prof:expr-id>11698068205613195480</prof:expr-id>
          <prof:expr-source>prof:report(xdmp:request())</prof:expr-source>
          <prof:uri/>
          <prof:line>3</prof:line>
          <prof:count>0</prof:count>
          <prof:shallow-time>PT0S</prof:shallow-time>
          <prof:deep-time>PT0S</prof:deep-time>
        </prof:expression>
        <prof:expression>
          <prof:expr-id>6277409173981051716</prof:expr-id>
          <prof:expr-source>xdmp:request()</prof:expr-source>
          <prof:uri/>
          <prof:line>3</prof:line>
          <prof:count>1</prof:count>
          <prof:shallow-time>PT0S</prof:shallow-time>
          <prof:deep-time>PT0S</prof:deep-time>
        </prof:expression>
        <prof:expression>
          <prof:expr-id>13716364291188563274</prof:expr-id>
          <prof:expr-source>current-dateTime()</prof:expr-source>
          <prof:uri/>
          <prof:line>2</prof:line>
          <prof:count>1</prof:count>
          <prof:shallow-time>PT0S</prof:shallow-time>
          <prof:deep-time>PT0S</prof:deep-time>
        </prof:expression>
        <prof:expression>
          <prof:expr-id>6174150852679522465</prof:expr-id>
          <prof:expr-source>prof:enable(xdmp:request())</prof:expr-source>
          <prof:uri/>
          <prof:line>1</prof:line>
          <prof:count>1</prof:count>
          <prof:shallow-time>PT0S</prof:shallow-time>
          <prof:deep-time>PT0S</prof:deep-time>
        </prof:expression>
      </prof:histogram>
    </prof:report>
prof:reset(
| $request-id as xs:unsignedLong
) as empty-sequence()
Summary: Clear any accumulated profiling statistics for the requests. If profiling has never been started for the request, nothing is done. If profiling is not allowed for the App Server, this function does nothing.
Parameters:
$request-id : A request ID. Use the `xdmp:request()` function, which returns the request ID for the currently running request, to specify the current request.
Required Privilege: Either `http://marklogic.com/xdmp/privileges/profile-my-requests` or `http://marklogic.com/xdmp/privileges/profile-any-requests` is required for profiling requests other than the current request, with the `profile-my-requests` privilege allowing profiling of requests issued by the same user ID, and the `profile-any-requests` privilege allowing profiling of requests issued by any user ID. No privilege is required to profile the currently running request (that is, self-profiling is always allowed).
Example:
      prof:reset(xdmp:request())
      => ()
prof:value(
| $expr as xs:string
) as item()*
Summary: Evaluate an expression in the context of the current evaluating statement and return the profiling report for its evaluation. This differs from `prof:eval` in that `prof:value` preserves all of the context from the calling query, so you do not need to re-define namespaces, variables, and so on. Although the expression retains the context from the calling query, it is evaluated in its own transaction.
Parameters:
$expr : The string representing an expression to evaluate.
Required Privilege: Either `http://marklogic.com/xdmp/privileges/profile-my-requests` or `http://marklogic.com/xdmp/privileges/profile-any-requests` is required for `prof:invoke` (the `profile-my-requests` privilege is suffient because the resulting request is always run by the same user who initiated the call, but the `profile-any-requests` privilege will also work).
Usage Notes: You can only evaluate and profile expressions with `prof:value`; no prolog definitions (namespace declarations, function definitions, module imports, and so on) are allowed.
Example:
      prof:value("xdmp:random()")
      => (<prof:report>...</prof:report>,9478952250821284456)
prof:xslt-eval(
| $stylesheet as element(),
| $input as node()?,
| [$params as map:map?],
| [$options as node()?]
) as item()*
Summary: Evaluate a string as an XSLT stylesheet for profiling. A `prof:report` node will be prepended to any output produced by evaluating the string. If profiling is not allowed for the App Server, this function will throw a `PROF-PROFILEALLOW` exception. Note that profiling does not cross eval/invoke boundaries. If the request being profiled calls xdmp:eval or xdmp:invoke, the individual expressions in that code will not be profiled. The overall time taken by the called code will appear as a single call in the caller's profiling report.
Parameters:
$stylesheet : The stylesheet to be executed.
$input : The context node to which the stylesheet is applied.
$params (optional): The stylesheet parameter values for this evaluation. Each key in the map is a string representing the name of the parameter in Clark notation: "{namespaceURI}localname". Each entry in the map is the value of the corresponding parameter.
$options (optional): The options node. The default value is (). The node must be in the `xdmp:eval` namespace. See the `xdmp:eval` section for a list of options. Additional options include: <mode> The initial stylesheet mode to use. <template> The name of the initial template to apply.
Required Privilege: Either `http://marklogic.com/xdmp/privileges/profile-my-requests` or `http://marklogic.com/xdmp/privileges/profile-any-requests` is required for `prof:eval` (the `profile-my-requests` privilege is suffient because the resulting request is always run by the same user who initiated the call, but the `profile-any-requests` privilege will also work).
prof:xslt-invoke(
| $path as xs:string,
| $input as node()?,
| [$params as map:map?],
| [$options as node()?]
) as item()*
Summary: Profiles and returns the result of evaluating an XSLT stylesheet at the given path. Any result produced by the evaluation will be prepended with a `prof:report` node containing timing and count information about the evaluation. If profiling is not allowed for the App Server, this function will throw a `PROF-PROFILEALLOW` exception. Note that profiling does not cross eval/invoke boundaries. If the request being profiled calls xdmp:eval or xdmp:invoke, the individual expressions in that code will not be profiled. The overall time taken by the called code will appear as a single call in the caller's profiling report.
Parameters:
$path : The path of the stylesheet to be executed. The path is resolved against the root of the App Server evaluating the query, the Modules directory, or relative to the calling module. For details on resolving paths, see "Importing XQuery Modules and Resolving Paths" in the Developer's Guide.
$input : The context node to which the stylesheet is applied.
$params (optional): The stylesheet parameter values for this evaluation. Each key in the map is a string representing the name of the parameter in Clark notation: "{namespaceURI}localname". Each entry in the map is the value of the corresponding parameter.
$options (optional): The options node. The default value is (). The node must be in the `xdmp:eval` namespace. See the `xdmp:eval` section for a list of options. Additional options include: <mode> The initial stylesheet mode to use. <template> The name of the initial template to apply.
Required Privilege: Either `http://marklogic.com/xdmp/privileges/profile-my-requests` or `http://marklogic.com/xdmp/privileges/profile-any-requests` is required for `prof:invoke` (the `profile-my-requests` privilege is suffient because the resulting request is always run by the same user who initiated the call, but the `profile-any-requests` privilege will also work).
Example:

© Copyright 2002-2012 MarkLogic Corporation. All rights reserved.