XML Content View

The XML Content view is designed to allow a user of DarkLight to view the contents of the XML database by creating an XQuery query that will return and display results to the screen. This gives the opportunity to build a query to be used in a playbook, or simply to explore the database. Queries can be named and saved, and are available to use in the Query XML Step.

DarkLight does not currently have any built-in services to add data to the XML Database. Data can be manually added to the database via the command-line.


Uses XQuery query syntax

The XQuery language follows the FLWOR expression format

  • For - Selects a sequence of nodes
  • Let - Binds a sequence to a variable
  • Where - Filters the nodes
  • Order - Orders the nodes
  • Return - Returns the selected variable

The following examples reference 'xml_data' for the database. This is the name of DarkLight's XML database and will be used in every query.

When the database has content available, the left pane with the headers Element and Count will have a list of the elements that are found in the database with their count. When you click on an element in the list, a base query is created for you that returns the first result.

When observing the query, you see that not all of the FLWOR notation is used. A rule of thumb is that there is at minimum a for statement and a return. Either the let or for statement is first to establish a sequence of nodes for the query to work with which is why the let is used first here even though it does not follow the acronym order.

  1. Run a Query: To run the query, click on the Go button beneath the query box. Results will render in the text box below the query.
  2. Save a Query: To save the query that is currently in the query box, click the Save button. The Manage XQueries dialog will appear with the contents of the Query box pre-filled. Enter a name at the top and click the Save button.
  3. Load a Saved Query: To load a saved query, select its name from the menu to the left of the Go button. This loads the query into the Query box.
  4. Manage Saved Queries: The Manage XQueries dialog can be opened from the triangle menu of the view. Here you can create, rename, update, and delete your saved queries.

XQuery Tips

Counting elements

When you simply need to count a set of results rather than view the results themselves, to you can user the count function on the set.

let $docs := (
   for $doc in db:open('xml_data')
   where $doc[*xpath expression*]
   return $doc
)
return count($docs)

Including namespaces

When working with XML that contains prefixes as part of the element names, you have two options on how to handle these: either declare the namespace of the prefix in the query (can be tedious and more difficult to maintain), or use [name()='pref:element'] to ignore the need to declare namespaces.

declare namespace pred='http://www.mysite.org';

Find documents based on date range

In order for this type of comparison to work appropriately, you will need to make sure that you match the formatting. In this query, timestamp is the name of the attribute of the element returned by the XPath expression on $doc.

let $min := '2014-04-06T12:35:00.000Z'
let $max := '2014-04-08T14:45:00.000Z'
let $docs := (
   for $doc in db:open('xml_data')
   where $doc[*xpath expression*]/[timestamp > $min and timestamp < $max]
   return $doc
)
return $docs

Deleting a single document from the database

Deleting a specific XML document from the database requires the functionality of an XQuery. Using a general XQuery to find the specific XML document you want to delete, you will need to get the base-uri($var) to get the path of the document, which is relative to the database.

let $uri := base-ur($doc) => yields 'xml_data/<doc name>'

Now to remove the '/xml_data/' portion of the uri, you will need to tokenize $uri by the forward slash.

let $name := tokenize($name, '/')[2] => yields '<doc name>'

What you have left is the name of the document to delete from the database.

return db:delete('xml_data', $name)

Delete multiple documents from query results

If the query you run results in documents from the database that you want to be deleted, the methodology is the same as with deleting a single document. For each document result from the query, you will need to follow the procedure above on each document inside your query.

XPath Tips

Find an element anywhere in the document

$doc//some-element

Find an element based on the localname (no namespace)

$doc*[local-name()='element']

Find an element regardless of namespace or where it is in the document

$doc//*[local-name()='element']

Find an element with a specific child element

$doc//some-element/child-element

Find an element with a nested child element (no namespace)

$doc//some-element/*[local-name()='child']

Find an element given the full name

$doc//*[name()='pref:element']

From the console of the server or standalone, use the command xinsert /path/to/file.xml to insert the file as records into the database.

  • help/xml-viewer
  • Last modified: 2019/03/29 22:39