The shell command is located in the <path where BDB XML is installed>/bin directory and is named dbxml.

To run the shell, simply type dbxml at the command prompt for your operating system. Assuming that you have the dbxml shell in your operating system's command line path, you'll then be greeted by the dbxml> prompt.

user> dbxml
dbxml>

In the examples that follow, you'll see the dbxml> prompt followed by the command that should be entered. Most commands are simple one line commands. However, some are more complicated XQuery examples that will span multiple lines. Each example will show both the command to enter and the resulting output. When the output is too long, ellipsis (...) will be used to abbreviate the intermediate results.

When using BDB XML you will find that document content is stored in a container. This is the first basic concept in BDB XML: containers hold collections of XML documents. The documents within a container may or may not share the same schema.

To begin exploring BDB XML, create a container. Our first example models a simple phonebook database. The container's name will be phone.dbxml.

dbxml> createContainer phone.dbxml      

Creating node storage container with nodes indexed

The command and output in this case was very simple. It was meant to merely confirm command execution. Note that a file named phone.dbxml was created in your working directory. This is the new document storage container. Containers hold the XML data, indices, document metadata, and any other useful information and are managed by BDB XML. Never edit a container directly, always allow the BDB XML library to manage it for you. The '.dbxml' extension helps to identify the BDB XML database on disk, but is simply a naming convention that is not strictly required.

This phonebook example's data model uses XML entries of the following format:

<phonebook>
    <name>
        <first>Tom</first>
        <last>Jones</last>
    </name>   
    <phone type="home">420-203-2032</phone>
</phonebook>

Now add a few phone book entries to the container in the following manner:

dbxml> putDocument phone1 '<phonebook>
    <name>
        <first>Tom</first>
        <last>Jones</last>
    </name>   
    <phone type="home">420-203-2032</phone>
</phonebook>' s

Document added, name = phone1

dbxml> putDocument phone2 '<phonebook>
    <name>
        <first>Lisa</first>
        <last>Smith</last>
    </name>   
    <phone type="home">420-992-4801</phone>
    <phone type="cell">390-812-4292</phone>
</phonebook>' s

Document added, name = phone2

Now the container has a few phonebook entries. The following few examples demonstrate some basic XQuery queries based solely on XPath statements. Subsequent sections will demonstrate more complex XQuery statements.

To retrieve all the last names stored in the container:

dbxml> query '
collection("phone.dbxml")/phonebook/name/last/text()'

2 objects returned for eager expression '
collection("phone.dbxml")/phonebook/name/last/text()'

dbxml> print
Jones
Smith            

To find Lisa's home phone number:

dbxml> query '
collection("phone.dbxml")/phonebook[name/first = "Lisa"]/phone[@type = 
"home"]/text()'

1 objects returned for eager expression '
collection("phone.dbxml")/phonebook[name/first = "Lisa"]/phone[@type = 
"home"]/text()'

dbxml> print
420-992-4801

To find all phone numbers in the 420 area code:

dbxml> query '
collection("phone.dbxml")/phonebook/phone[starts-with(., "420")]/text()'

2 objects returned for eager expression '
collection("phone.dbxml")/phonebook/phone[starts-with(., "420")]/text()'

dbxml> print
420-203-2032
420-992-4801

These queries simply retrieve subsets of data, just like a basic SELECT statement would in a relational database. Each query consists of two parts. The first part of the query identifies the set of documents to be examined (equivalent to a projection). This is done with an XQuery navigation function such as collection(). In this example, collection("phone.dbxml") specifies the container against which we want to apply our query. The second part is an XPath statement (equivalent to a selection). The first example's XPath statement was /phonebook/name/last/text() which, based on our document structure, will retrieve all last names and present them as text.

Understanding XPath is the first step toward understanding XQuery.