Loading TOC...
Getting Started With MarkLogic Server (PDF)

Getting Started With MarkLogic Server — Chapter 6

Getting Started with MarkLogic XQuery Applications

This section describes the following procedures to get started using XQuery in MarkLogic Server:

Be sure to complete each procedure in the order presented.

Exploring the Use Cases

As part of the XQuery standard, the W3C working group has assembled a set of use cases that demonstrate how XQuery can be used to accomplish a variety of sample tasks. As part of its installation process, MarkLogic Server provides a workspace for Query Console containing working demonstrations of these use cases. The use cases provide an excellent starting point for familiarizing yourself with the XQuery language and with some important aspects of MarkLogic Server.

To explore the use cases, complete the following steps:

  1. Go to the following URL (substitute your hostname if MarkLogic is not running on your local machine):

    http://localhost:8000/

  2. Click the Query Console button in the top navigation bar.
  3. In Query Console, click the Workspace link (towards the upper right corner of Query Console) and select Import...
  4. Navigate to <marklogic-dir>/Samples/w3c-use-cases.xml.

    If MarkLogic is running on the same machine as your browser, you can navigate to this directory (for example, c:/Program Files/MarkLogic/Samples on Windows or /opt/MarkLogic/Samples on Linux), but if MarkLogic is installed on a remote server, then you must copy this file from the server to the machine in which your browser is running, and then navigate to the directory where you copied the file.

  5. Click Import. The W3C XQuery use cases are imported into Query Console.
  6. Click Load Source XML query buffer in the workspace pane to display the query into Query Console.

  7. Click the Run button.

    A confirmation message displays indicating the documents have been loaded.

  8. The use cases are divided into the following categories, with each category having several queries:
    • 1.0: Exemplars
    • 2.0: Tree
    • 3.0: Sequence
    • 4.0: Relational
    • 5.0: SGML
    • 6.0: String Search
    • 7.0: Namespace
    • 8.0: Recursive
    • 9.0: Strong
At this point, you have different options to explore the use cases. We recommend you use the following procedures as examples to maximize your experience with the use cases:

You can complete these procedures in any order.

Viewing the Source XML

This procedure focuses on the first use case topic, 1.0: Exemplars. You can view the source XML for any of the use cases.

To view the source XML, complete the following steps:

  1. Click the 1.0 Source XML query buffer in the workspace pane to display the query into Query Console.
  2. View the source code in the query editor tab.
  3. Click Run.
  4. View the source XML at the bottom in the XQuery Results pane.

Viewing a Use Case

This procedure focuses on the first use case in Exemplars. You can view any use case in other topics as well.

To view the use case, complete the following steps:

  1. Click the 1.1 Value constraints query buffer in the workspace pane to display the query into Query Console.
  2. View the source code in the query editor tab.
    Lists books published by Addison-Wesley after 1991 including their year and title.

    Notice that XQuery comments are wrapped in smiley faces: (: comment :)

  3. Click Run.
  4. View your results.

The following shows the results:

Editing a Use Case

This procedure focuses on the first use case in Exemplars. You can edit any use case in the list.

To edit a use case, complete the following steps:

  1. Click the 1.1 Value constraints query buffer in the workspace pane to display the query into Query Console.
  2. View the source code in the query editor tab.
  3. Change the following source from:
    where $b/publisher = "Addison-Wesley" and $b/@year > 1991

    to:

    where $b/publisher = "Addison-Wesley" and $b/@year > 1993 
  4. Click Run.
  5. View the new query results.

    You may change the source as much as you like. Explore and customize each use case as thoroughly as possible. You can reload the workspace from the Sample directory to restore it.

The App-Services App Server

The App-Services App Server at port 8000 hosts Query Console and other MarkLogic applications. The App-Services App Server also serves as an HTTP App Server, an XDBC App Server, and as a REST API instance. XQuery, Node.js, XCC, and REST applications can be run directly on the App-Services App Server.

By default, the App-Services App Server uses the Documents database. The MarkLogic APIs provide mechanisms for changing the database when necessary.

The Sample XQuery Application described below is run on the App-Services App Server.

Sample XQuery Application that Runs Directly Against an App Server

In this section, you create a sample XQuery application. This is a simple browser-based application that runs against an HTTP App Server, and that allows you to load and modify some data. First you will create the App Server, and then create the application. This procedure includes the following parts:

Creating a New App Server

In this section, you create a new HTTP App Server. An App Server is used to evaluate XQuery code against a MarkLogic database and return the results to a browser. This App Server uses the Documents database, which is installed as part of the MarkLogic Serverinstallation process. In Sample XQuery Application that Runs Directly Against an App Server, you use this App Server to run a sample XQuery application.

To create a new App Server, complete the following steps:

  1. Open a new browser window or tab.
  2. Open the Admin Interface by navigating to the following URL (substitute your hostname if MarkLogic is not running on your local machine):

    http://localhost:8001/

  3. Log in with your admin username and password.
  4. Click the Groups icon on the left.
  5. Click on the Default icon within the Groups branch.
  6. Click on the App Servers icon within the Default group.
  7. Click the Create HTTP tab.
  8. Go to the HTTP Server Name field and enter TestServer.

    This is the name that the Admin Interface uses to reference your server on display screens and in user interface controls.

  9. Go to the Root directory field and enter /space/test (or whatever directory you want for your App Server root, for example c:/space/test on a Windows system).

    By default, the software looks for this directory in your MarkLogic Server program directory, as specified in the Installation Guide. But it is much better practice to specify an absolute path (such as C:\space\test on a Windows platform or /space/test on a Linux platform).

  10. Go to the Port field and enter 8005 (or whatever port you want to use for this App Server).

    The following screen shows an HTTP server with these values:

  11. Scroll down to Authentication and select application-level.

    This makes it so you do not need to enter a username or password against this App Server. If you want to enter a username and password, leave this setting as digest.

  12. Choose an admin user (it has the word admin in parenthesis) as the Default User.
  13. Leave the privilege field blank.

    The following screen shows an HTTP server with these values

  14. Scroll to the top or bottom and click OK.
  15. See that TestServer is added to the HTTP Server branch.

Creating the Sample XQuery Application

To create and run the sample XQuery application, complete the following steps:

  1. This procedure assumes you are using the application directory /space/test. If you are using a different directory (for example, c:/space/test), just make everything relative to that directory.
  2. Create a directory on the host in which MarkLogic is running named /space/test (or whatever directory you want).
  3. Open a text editor and create a new file called load.xqy in the /space/test directory.
  4. Copy and save the following code into this .xqy file:
    xquery version "1.0-ml";
    (: load.xqy :)
    xdmp:document-insert("books.xml",
      <books xmlns="http://www.marklogic.com/ns/gs-books">
        <book bookid="1">
          <title>A Quick Path to an Application</title>
          <author>
            <last>Smith</last>
            <first>Jim</first>
          </author>
          <publisher>Scribblers Press</publisher>
          <isbn>1494-3930392-3</isbn>
          <abstract>This book describes in detail the power of how to use XQuery to build powerful web applications that are built on the MarkLogic Server platform.</abstract>
        </book>
      </books>
    ),
    
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
        <title>Database loaded</title>
      </head>
    
      <body>
    <b>Source XML Loaded</b>
    <p>The source XML has been successfully loaded into the database</p>
      </body>
    </html>
  5. Create another file called dump.xqy in the /space/test directory.
  6. Copy and save the following code into this .xqy file:
    xquery version "1.0-ml";
    (: dump.xqy :)
    declare namespace bk = "http://www.marklogic.com/ns/gs-books";
    
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
        <title>Database dump</title>
      </head>
      <body>
      <b>XML Content</b>
    {
        for $book in doc("books.xml")/bk:books/bk:book
        return
        <pre>
            Title: { $book/bk:title/text() }
            Author: { ($book/bk:author/bk:first/text(), " ",
            $book/bk:author/bk:last/text()) }
            Publisher: { $book/bk:publisher/text() }
        </pre>
    }
        <a href="update-form.xqy">Update Publisher</a>
      </body>
    </html>
  7. Create another file called update-form.xqy in the /space/test directory.
  8. Copy and save the following code into this .xqy file:
    xquery version "1.0-ml";
    (: update-form.xqy :)
    declare namespace bk="http://www.marklogic.com/ns/gs-books";
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
        <title>Change Publisher</title>
      </head>
      <body>
        {
          let $book := doc("books.xml")/bk:books/bk:book[1]
          return
          <form action="update-write.xqy">
            <input type="hidden" name="bookid" value="{ $book/@bookid }"/>
            <p><b>
    Change publisher for book <i>{ $book/bk:title/text() }</i>:
            </b></p>
            <input type="text" name="publisher"
                value="{ $book/bk:publisher/text() }"/>
            <input type="submit" value="Update publisher"/>
          </form>
      }
      </body>
    </html>
  9. Create another file called update-write.xqy in the /space/test directory.
  10. Copy and save the following code into this .xqy file:
    xquery version "1.0-ml";
    (: update-write.xqy :)
    declare namespace bk="http://www.marklogic.com/ns/gs-books";
    
    declare function local:updatePublisher()
    {
      if (doc("books.xml")) then
        let $bookid := xdmp:get-request-field("bookid")
        let $publisher := xdmp:get-request-field("publisher")
        let $b := doc("books.xml")/bk:books/bk:book[@bookid = $bookid]
      return
          if ($b) then
        (
          xdmp:node-replace($b/bk:publisher,
                <bk:publisher>{ $publisher }</bk:publisher>)
    ,
           xdmp:redirect-response("dump.xqy")
        )
          else
        <span>Could not locate book with bookid { $bookid }.</span>
          else
        <span>Unable to access parent XML document.</span>
    };
    
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
        <title>Update In Process</title>
      </head>
    
      <body>
    Attempting to complete update and redirect browser to detail page.
        <p>
    If you are seeing this page, either the redirect has failed
    or the update has failed.  The update has failed if there is
    a reason provided below:
          <br/>
          { local:updatePublisher() }
        </p>
      </body>
    </html>
  11. Confirm that you have the following new files in your Test directory:
    • load.xqy
    • dump.xqy
    • update-form.xqy
    • update-write.xqy
  12. Confirm that all files end with the .xqy extension, not the .txt extension.
  13. Using these files, continue to the following procedures:
Loading the Source XML

To load the source XML, complete the following procedure:

  1. Open a new browser window or tab.
  2. Go to the following URL (substitute your hostname if MarkLogic is not running on your local machine):

    http://localhost:8005/Test/load.xqy

    MarkLogic Server runs the new load.xqy file.

  3. View the following confirmation message:

Generating a Simple Report

To generate a simple report from the newly loaded XML, complete the following steps:

  1. Go to the following URL (substitute your hostname if MarkLogic is not running on your local machine):

    http://localhost:8005/Test/dump.xqy

    MarkLogic Server runs the dump.xqy file.

  2. View the new HTML-compatible report:

Submitting New Information

To submit new information to the database, complete the following steps:

  1. Go to the following URL (substitute your hostname if MarkLogic is not running on your local machine):

    http://localhost:8005/Test/update-form.xqy

    MarkLogic Server runs the new update-form.xqy file.

  2. View the simple form to update a publisher:

  3. Enter Menlo Books as the new publisher.
  4. Click Update publisher.

    This action automatically calls update-write.xqy, which updates the publisher element in the database, and then redirects the browser to dump.xqy which displays the updated book information.

  5. (Optional) Continue exploring your new files or write your own code to create new XQuery applications.
« Previous chapter
Next chapter »