| 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:02 AM | XQuery & XSLT Built-In & Modules Function Reference
Module: Information Studio
The Information Studio API module contains functions that allow you to set policy, load content from a directory, configure databases, specify transformations, and check ticket status. The Information Studio API is installed as the following file: `install_dir/Modules/MarkLogic/appservices/infostudio/info.xqy` where `install_dir` is the directory in which MarkLogic Server is installed. To use the `info.xqy` module in your own XQuery modules, include the following line in your XQuery prolog:
      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";
The library uses the `info:` namespace, which is not predefined in the server. MarkLogic recommends enabling the URI Lexicon when using Information Studio; the URI lexicon will improve performance, especially when the database grows to a large number of documents.
Function Summary
info:database-create | This function creates a database with attached forests.
info:database-delete | This function deletes the specified database and its forest.
info:database-get-feature | This function returns the a node representing support for database features of wildcarding, word positions, and reverse search.
info:database-set-feature | This function adds or removes the related database settings for wildcarding, word positions, and/or reverse search.
info:error-detail | This function returns the error detail associated with the specified error-id.
info:flow-cancel | This function cancels all active tickets associated with a flow.
info:flow-id | This function returns the id of the flow with the specified name.
info:flow-policy | This function returns the name of the policy associated with a flow.
info:flow-start | This function starts (or "plays") the flow.
info:flow-tickets | This function returns a sequence of IDs for all of the tickets started by this flow.
info:load | This function does a one-time scan of the named directory path (local filesystem only), and attempts to load the files, spawning multiple transactions if necessary.
info:policy | This function returns the stored policy matching the specified policy.
info:policy-delete | This function deletes a named policy.
info:policy-names | This function returns the names of all stored policies.
info:policy-set | This function sets an ingestion policy, which consists of a reusable <options> node defining parameters for content loading and transformation.
info:ticket | This function returns a ticket element containing the status information for a long-running process.
info:ticket-delete | This function deletes a ticket and all associated state information.
info:ticket-errors | This function returns any errors that may have occured when loading content.
info:tickets | This function returns a sequence of ticket IDs, optionally narrowed by database name.
info:unload | This function deletes all of the documents associated with the specified $ticket-id from one or more databases.
Function Detail
info:database-create(
| $database-name as xs:string,
| [$forests-per-host as xs:positiveInteger?],
| [$group as xs:string?],
| [$data-directory as xs:string?],
| [$security-db as xs:string?],
| [$schemas-db as xs:string?],
| [$triggers-db as xs:string?]
) as xs:unsignedLong
Summary: This function creates a database with attached forests. Forests are named sequentially using the pattern of databasename-1, databasename-2 and so on. The API checks for database and forest name conflicts, throwing an INFO-DUPLICATENAME error if any name conflicts are encountered. The database is created with default index settings. If `$forests-per-host` is an empty sequence or omitted, only one forest (regardless of number of hosts) is created. If database creation succeeds, the database id is returned.
Parameters:
$database-name : Name of this database.
$forests-per-host (optional): The number of forests to create per host in the group. Defaults to one forest for the database if not provided.
$group (optional): The name of the group to which to add forests. The API determines which hosts are in the group and creates the specified number of forests for each host in the group. If not provided, the Default group is used.
$data-directory (optional): A public data directory to use for forest creation. Default is none, resulting in a private data directory (server default).
$security-db (optional): The name of the security database to use for database creation. Defaults to Security if not provided.
$schemas-db (optional): The name of the schema database to use for database creation. Defaults to Schemas if not provided.
$triggers-db (optional): The name of the triggers database to use for database creation. Defaults to Triggers if not provided.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:database-create(
    	"newDB",
    	2,
    	"Default",
    	"/foobar",
    	"Security",
    	"Schemas",
    	"Triggers")

      (: Creates a new database, named "newDB," and attaches to it two forests. :)
info:database-delete(
| $database-name as xs:string,
| [$delete-data as xs:boolean?]
) as empty-sequence()
Summary: This function deletes the specified database and its forest.
Parameters:
$database-name : The name of the database to delete.
$delete-data (optional): Determines whether to delete the database data. If set to `fn:true()`, both the configuration and the data directory containing all of the documents in the forest are deleted. If set to `fn:false()`, only the configuration information is deleted, leaving the forest data in the data directory on disk.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:database-delete("testDB")

      (: Deletes the testDB database and forest. :)
info:database-get-feature(
| $database as xs:string,
| [$preview-settings as element(info:settings)],
| [$delta as xs:boolean]
) as element(info:settings)
Summary: This function returns the a node representing support for database features of wildcarding, word positions, and reverse search. Returns a boolean value for each database feature based on whether its corresponding database settings are on or off. If some settings are on for a feature but others are off, then the feature will be noted as off. A "detail" child node includes the value of each related database setting. The optional `$preview-settings` and `$delta` arguments allow developers to pass in settings to preview the result of a given set of features. If `$delta` is set to `true()`, only values that will change are returned. If not provided, `$delta` is `false()`. This call is read-only, it does not change the state of database features supported.
Parameters:
$database : The name of the database for which to get support information. If a database that comes pre-configured with the server (other than the "Documents" database) is specified, then a "Restricted Database" exception will occur.
$preview-settings (optional): Settings XML representing a desired set of database features to preview. Note: if the incoming XML has a detail section, it is ignored.
$delta (optional): If this parameter is set to true, then on preview the returned information will only include settings that would change on a call to `info:database-set-feature()`. Defaults to false if not specified.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:database-get-feature("Documents")

      (: Returns the current state of the supported database features. :)
info:database-set-feature(
| $database as xs:string,
| $settings as element(info:settings)
) as empty-sequence()
Summary: This function adds or removes the related database settings for wildcarding, word positions, and/or reverse search. Not specifying a feature will leave it in its current state.
Parameters:
$database : The name of the database to add or remove support of specified database feature. If a database that comes pre-configured with the server (other than the "Documents" database) is specified, then a "Restricted Database" exception will occur.
$settings : Settings XML representing desired database features to configure. Valid options are "wildcard", "position", "reverse". If an element is not specified, its setting remains unchanged. Note: if the incoming XML has a detail section (from a verbose call to get-feature) it is ignored.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
         at "/MarkLogic/appservices/infostudio/info.xqy";

      info:database-set-feature("Documents",
        <settings xmlns="http://marklogic.com/appservices/infostudio">
          <wildcard>true</wildcard>
          <position>true></position>
          <reverse>false</reverse>
        </settings> )

      (: Turn on 3 character wildcard, the codepoint word lexicon, word positions,
         and 3 character word position. It will turn off reverse search. :)
info:error-detail(
| $error-id as xs:unsignedLong
) as element(info:error)
Summary: This function returns the error detail associated with the specified `error-id`.
Parameters:
$error-id : The error id from a ticket.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      for $ticket in info:tickets()
        let $error-id := info:ticket-errors($ticket)//info:error/@id
        return info:error-detail($error-id)

      (: Returns error details for all of the tickets. :)
info:flow-cancel(
| $flow-id as xs:string
) as empty-sequence()
Summary: This function cancels all active tickets associated with a flow. If the flow does not exist, an exception is thrown.
Parameters:
$flow-id : The ID of the flow.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:flow-cancel("6184479677280143786")

      (: Cancels all active tickets for the flow.  :)
info:flow-id(
| $flow-name as xs:string
) as xs:string?
Summary: This function returns the id of the flow with the specified name. If no flow exists with this name, an empty sequence is returned.
Parameters:
$flow-name : The name of the flow.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:flow-id("myFlow")

      (: Returns the id of the flow, "myFlow." :)
info:flow-policy(
| $flow-id as xs:string
) as xs:string
Summary: This function returns the name of the policy associated with a flow. If the flow does not exist, an exception is thrown.
Parameters:
$flow-id : The ID of the flow.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:flow-policy("6184479677280143786")

      (: Returns the name of the policy associated with the flow  :)
info:flow-start(
| $flow-id as xs:string
) as xs:string
Summary: This function starts (or "plays") the flow. If the flow does not exist, an exception is thrown.
Parameters:
$flow-id : The ID of the flow.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:flow-start("6184479677280143786")

      (: Starts the specified flow to load the database.  :)
info:flow-tickets(
| $flow-id as xs:string,
| [$include-inactive as xs:boolean?]
) as xs:string*
Summary: This function returns a sequence of IDs for all of the tickets started by this flow. If the flow does not exist, an exception is thrown.
Parameters:
$flow-id : The ID of the flow.
$include-inactive (optional): Determines whether to return inactive tickets. By default, only the active tickets are returned. Set to `fn:true()` to return both active and inactive tickets.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:flow-tickets("6184479677280143786")

      (: Returns all active tickets associated with the flow.  :)
info:load(
| $dir-path as xs:string,
| [$policy-name as xs:string?],
| [$policy-deltas as element(info:options)?],
| [$database as xs:string]
) as xs:string
Summary: This function does a one-time scan of the named directory path (local filesystem only), and attempts to load the files, spawning multiple transactions if necessary. This collector should be considered stateless; although some lightweight state information is passed via an external variable to the executing module, it is not persistent. Transactions are asynchronous, and order of insertions is not guaranteed. This function returns a ticket URI that can be used to access status information for that ticket.
Parameters:
$dir-path : Local filesystem path of a set of documents to load.
$policy-name (optional): The name of a stored ingestion policy. If the name is provided but does not exist, an error is thrown. If no name is provided, a stored default policy is used if available. If neither exists, reasonable global defaults are used.
$policy-deltas (optional): An options node with a namespace of `http://marklogic.com/appservices/infostudio`. If it is provided, it is merged with the stored policy, providing the ability to override or supplement stored policy at runtime. See the description of the `info:policy-set` function for an example options node.
$database (optional): Name of a database into which content should be inserted. If not provided, defaults to the current context database.
Usage Notes: All documents loaded with `info:load` are added to a collection with the URI corresponding to the ticket ID returned from the function. For example, if `info:load` returns `/tickets/ticket/123456`, then any documents loaded have the collection `/tickets/ticket/123456` (in addition to any collections added via the options node or options delta).
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:load("C:\docs\mydocs", (), (), "testDB")

      (: Loads the contents of the C:\docs\mydocs directory into the testBD database using
         the default policy. :)
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      let $delta :=
          <options xmlns="http://marklogic.com/appservices/infostudio">
              <uri>
                  <literal>http://mydir/</literal>
                  <filename/>
                  <literal>.</literal>
                  <ext/>
              </uri>
          </options>

      return info:load("C:\docs\mydocs", (), $delta, "testDB")

      (: Loads the contents of the C:\docs\mydocs directory into the testBD database at the
         URI http://mydir/, using the rest of the options specified by the default policy.
         For example, C:\docs\mydocs\mydoc.xml will be loaded into the database with the
         URI http://mydir/mydoc.xml. :)
info:policy(
| $policy-name as xs:string
) as element(info:options)?
Summary: This function returns the stored policy matching the specified policy. If the policy does not exist, this function returns an empty sequence.
Parameters:
$policy-name : Name of the policy to be returned.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:policy("default")

      (: Returns the default policy. :)
info:policy-delete(
| $policy-name as xs:string
) as empty-sequence()
Summary: This function deletes a named policy. If the policy is successfully deleted or does not exist, this function returns an empty sequence.
Parameters:
$policy-name : The name of a stored ingestion policy.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:policy-delete("default")

      (: Deletes the default policy. :)
info:policy-names( ) as xs:string*
Summary: This function returns the names of all stored policies.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:policy-names( )

      (: Returns the names of all of the set policies. :)
info:policy-set(
| [$policy-name as xs:string?],
| [$policy as element(info:options)?]
) as empty-sequence()
Summary: This function sets an ingestion policy, which consists of a reusable <options> node defining parameters for content loading and transformation.
Parameters:
$policy-name (optional): The name of this ingestion policy. If the policy already exists, it is overwritten without warning. If no name or the empty string is provided, the new policy replaces the default policy (named 'default').
$policy (optional): An options node. If provided, it will be merged with a set of global reasonable defaults and stored as the named policy. If no $policy is provided, the content is the set of global defaults.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:policy-set(
        "default",
        <options name="default" xmlns="http://marklogic.com/appservices/infostudio">
          <collection>http://marklogic.com/appservices/infostudio</collection>
          <error-handling>continue-with-warning</error-handling>
          <fab-retention-duration>P30D</fab-retention-duration>
          <file-filter>^[^\.]</file-filter>
          <max-docs-per-transaction>100</max-docs-per-transaction>
          <overwrite>overwrite</overwrite>
          <ticket-retention-duration>P30D</ticket-retention-duration>
          <uri>
            <literal>http://docs/mydocs</literal>
            <filename/>
            <literal>.</literal>
            <ext/>
          </uri>
        </options>)

      (: Defines and sets a default polcy to load all documents with the uri of
         http://docs/mydocs. :)
info:ticket(
| $ticket-id as xs:string+
) as element(info:ticket)+
Summary: This function returns a ticket element containing the status information for a long-running process.
Parameters:
$ticket-id : The id of the ticket associated with the long-running process.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      let $ticket := info:load("C:\docs\mydocs", (), (), "testDB")

      return (
        "Loaded the testDB database with the files from",
        fn:data(info:ticket($ticket)//directory) )

      (: Returns the directory that was loaded into the testDB database. :)
info:ticket-delete(
| $ticket-id as xs:string
) as empty-sequence()
Summary: This function deletes a ticket and all associated state information. If the ticket is successfully deleted or does not exist, returns empty-sequence(). A tickets cannot be deleted if work is in progress.
Parameters:
$ticket-id : The id of the ticket to be deleted.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      for $ticket in info:tickets("testDB")
         return info:ticket-delete($ticket)

      (: Deletes all of the tickets associated with the testDB database. :)
info:ticket-errors(
| $ticket-id as xs:string,
| [$start as xs:unsignedInt?],
| [$page-length as xs:unsignedInt?],
| [$sort-ascending as xs:boolean?],
| [$filter as schema-element(cts:query)?]
) as element(info:errors)
Summary: This function returns any errors that may have occured when loading content. The load operation must be complete before any errors appear in the ticket. You can use the optional parameters, `start` and `page-length`, to paginate through a long list of errors. By default, errors are sorted by descending time. You can set the `sort-ascending` parameter to `true` to return errors in ascending time, which can be useful when paginating on an open ticket where new errors are coming in constantly. The `filter` parameter allows you to annotate errors with metadata. You can create a filter to limit results by anything in the ticket, such as time, some custom annotation, or error code.
Parameters:
$ticket-id : The id of the ticket.
$start (optional): Which error in a list from which to begin the returned list. For example, if dealing with hundreds of errors, you might want to display them in increments of 50. So you would call this function with `start` set to 1, then 50, then 100, and so on.
$page-length (optional): The number of errors returned in each page. In the example described for the `start` parameter, this would be set to 50.
$sort-ascending (optional): By default, errors are sorted by descending time. Set to `true` to return errors in ascending time.
$filter (optional): Any customer query written to filter the list of errors.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:ticket-errors("/tickets/ticket/8850539794189994434")

      (: Returns any errors associated with the specified ticket. :)
info:tickets(
| [$database as xs:string*],
| [$status as xs:string*],
| [$custom-query as schema-element(cts:query)?]
) as xs:string*
Summary: This function returns a sequence of ticket IDs, optionally narrowed by database name.
Parameters:
$database (optional): A database name to narrow the selection of tickets to those associated with that database.
$status (optional): A status name to narrow the selection of tickets to those with the specified status. The valid status values are "aborted", "active", "cancelled", "cleared", "completed", "inactive", "unloading", "unloaded", and "unload-aborted".
$custom-query (optional): Some custom query to further narrow down the list of tickets returned.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:tickets()

      (: Returns the IDs of all of the tickets generated from loads into all of the databases. :)
info:unload(
| $ticket-id as xs:string,
| [$database as xs:string*],
| [$batch-size as xs:positiveInteger?]
) as empty-sequence()
Summary: This function deletes all of the documents associated with the specified `$ticket-id` from one or more databases. The documents are deleted from the database associated with the ticket, as well as any additional databases specified by the `$database` parameter. The ticket status is "unloading" while the delete is in progress and "unloaded" when complete. A ticket may not be unloaded if its status is "active". If errors are encountered during the unloading process, an exception is thrown and the ticket status is set to "unload-aborted".
Parameters:
$ticket-id : The id of the ticket associated with the documents to be deleted.
$database (optional): One or more database names. If no database is specified, only the documents from the database logged in the ticket are cleared. If databases are specified, documents associated with the ticket are deleted from those databases in addition to the database logged in the ticket.
$batch-size (optional): The number of documents to delete in a single transaction. If not specified, the default value of 5,000 is used.
Example:
      xquery version "1.0-ml";

      import module namespace info = "http://marklogic.com/appservices/infostudio"
          at "/MarkLogic/appservices/infostudio/info.xqy";

      info:unload("/tickets/ticket/4920103524656746726")

      (: Deletes all of the documents associated with the ticket from the database
         specified in the ticket. :)

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