� XStreamDB Reference Guide

Feature	Description	More Information
XQuery support	XQuery is an emerging W3C standard for querying databases. XStreamDB supports most of XQuery and also supports additional functionality not currently in the XQuery specification.	XQuery Language at W3C.org
XQuery extensions	The following list shows features supported in XStreamDB accomplished by extending the XQuery language. Database update: document insert, replace and delete. Document editing: element or attribute insert, replace and delete. Parameterized XQuery statements: prepare, setParam mechanism. Integrated full text search. Wildcard value matching using the LIKE keyword.	Quick Statements in the User Guide Configuration Statements DML Statements
Full Text Search	Full text search allows you to search for words within element and attribute content. A full text index with automatic optimization speeds these searches up significantly.	Full Text Search
Indexing	Full text indexes to optimize full text search. Selective value indexes for indexing element or attribute values. These indexes result in smaller indexes than a full text index. As well, value indexes support the data types supported by XStreamDB which allows, for instance, proper value sorting for numbers.	Indexing in the User Guide
Automatic optimization	One or more full text and value indexes are automatically used to optimize AND and OR selections of data. As well, joins, sorts and distinct operations are optimized through value indexes.	Optimization
Full-featured Java client API	XStreamDB supports multiple servers, each with configuration information and JDBC-like XConnection, XStatement and XResultSet objects.	API
Concurrent transactional database	XStreamDB is built on a multi-transactional concurrent database storage engine. Transactional features include begin, commit, and rollback with deadlock detection.	Transaction
Client/Server architecture	The client can be deployed on a separate machine from the server. This allows multiple clients to access one server regardless of the location of clients. As well, clients can be started and stopped without influencing the server.	Architecture
Web server enabled	XStreamDB is enabled to work well with servlet enabled web and application servers. A simple servlet sample ships with the product.	Deployment in the User Guide
User based Security	XStreamDB has: secure logon. definable users. definable groups for users. Scoped create, read, update, delete and permit functions on resources down to the document level.	Security
Schema utilization and support	Schema utilization and support includes: DTD. W3C Schema. Validation of documents. GUI helpers.	Schema
Product Components	Describes each of the product components in the package that is released to the customer.	Product Components
Remote server Explorer application	Included with XStreamDB is a stand alone explorer application which allows configuration and querying of any XStreamDB database on any server.	Explorer Guide in the User Guide
WebDav Server	On top of the XStreamDB resource system is a webdav server that allows you to store and retrieve any kind of content in XStreamDB.	�
Exposing Documents as Web Resources	XStreamDB has a resource subsystem which allows the exposure of documents as web resources and the access to these through either WebDav or the XdbWeb web applications.	�
Schedulable Hot Backup	Backup is a snapshot as of time T and can be concurrent with other transactions. As well, backup can be scheduled.	�

Object Type	ObjectId	Local Name
Current Server	"/"	Not applicable
Database	"/MyDb	"MyDb"
Root	"/MyDb/MyRoot	"MyRoot"
Collection	"/ColRoot/MyCol1/MyCol2..."	"MyCol2"
Extent (virtual object)	RootId \| CollectionId	Last step in path.
Index	"/MyDb/MyRoot/MyIndex"	"MyIndex"
Document	Various Schemes: DocNum: 0..n - re-used after delete GUID: "a0ff..." CounterId: "0..n" sequential, never re-used. DocId: "$1$BookDB:Book$1-0-0$2" Path: "/ColRo0t/a/b/foo.jpg	�
Group	"/Doctors"	"Doctors"
User	"/Freddy"	"Freddy"
Trigger	"/MyDb/MyRoot/MyTrigger"	"MyTrigger"
Module	"http://www.bluestream.com/a/b" or "RefDoc". Note: the object ID form is parsable as URI as specified in the XQuery Language Specification.	"http://www.bluestream.com/a/b"
Binary	See Document ids above.	�
Schema	See Document ids above.	Most often uses the path form:Path: "/ColRo0t/a/b/FAQ.dtd

Mechanism	Description	Notes
docNum	A system generated integer which is supported inside XStreamDB.	This number is relative to the root. DocNums may be re-used after deletion of the content object, so they are not always a good choice for long lived URIs, but they are OK for foreign key/primary key relationships within the database.
guid	A system generated identifier which is generated for each new insert.	This number is universally unique. It makes a good choice for distributed systems that need universal identity. A guid is longer and more expensive to support than a docNum.
counterId	A system generated integer which is sequentially generated.	This number is relative to the root. This number is not guaranteed to be sequential but counter at time b will be greater than counter assigned at time a, so the counter does represent a sequence in time, unlike DocNum.
fullPath	A string like /a/b/foo.xml. This string is configured by the user by setting a parent collection and a name for the content object.	This identifier is server unique. This identifier is setup by the user but the system ensures that it is unique.
docId/docVerId	A string that qualifies a document according to its database and root as well as its version number. This identifier MUST NOT be persisted and used later as a foreign key or some other form. This is because a restore from backup changes the docId. For persistent keys, use one of the above types. DocNum can be extracted from a DocId, all of the other forms need to be generated and extracted using a function - see below. DocId is, however, used for replace and delete commands.	For example, "1$BookDB:Book$1-0-0$2"

Database Server Configuration

The XStreamDB database server is configured for normal operations by creating, modifying and dropping the following configuration objects:

Databases
Roots
Indexes
Triggers
Stored modules
Backup schedules

The above objects need to be defined and managed by a database administrator before normal production deployment operation of the server commences. The XDBExplorer GUI application offers a user interface to manage these objects. Many of these objects can be managed through the XStreamDB command language. In fact, triggers and stored modules are maintained through the command language only.

This section focuses on the lifecycle of creation, modification and destruction of the above objects, not the use of the objects. The use of the objects, once they are created, is covered in the Basic Command Language and other command language sections.

Concurrency

Configuration operations can only be performed if there are no users currently in an active XConnection transaction involving the database being modified. As well, the transaction doing the configuration statement must only do configuration statements, not mix them with other types of statements. More precisely, there can be no transactions open, including the current one, that have performed operations on the database being modified, where those operations have not been committed - excluding other configuration commands. For example, if a user has a noncommitted transaction which is querying database DB1, then drop database, create root, drop root, create index and drop index will not be possible on DB1 until that active transaction commits.

General Definitions

These BNF definitions are used below in the BNF for the configuration XStreamDB commands . As well, you can consult the machine generated XStreamDB Grammar File .

DatabaseIdStr ::= '"' DatabaseId '"'
RootIdStr ::= '"' RootId '"'
TriggerNameStr ::= '"' TriggerName '"'
TriggerIdStr ::= '"' TriggerId '"'
IndexNameStr ::= '"' IndexName '"'
RootId ::= '/' DatabaseName '/' ShortRootName 
DatabaseId ::= '/' DatabaseName
TriggerId ::= '/' DatabaseName '/' RootName '/' TriggerName
DatabaseName ::= Name 
RootName ::= Name
TriggerName ::= Name
IndexName ::= Name
SchemaSpec ::= '"' SchemaUri '"' /* basically a schema URI inside a string */
SchemaUri :: = "/SysData/SysSchema/" SchemaSubUri SchemaRootElementName
SchemaSubUri ::= (Name '/')* Name       
SchemaRootElementName ::= QName
Name ::= [http://www.w3.org/TR/REC-xml-names/#NT-NCName] 
StringLiteral ::= 
  ('"' (PredefinedEntityRef | CharRef | ('"' '"') | [^"&])* '"') | 
  ("'" (PredefinedEntityRef | CharRef | ("'" "'") | [^'&])* "'")
SetMetaData ::= SetMetaData ::= "set" "metadata" ElementExpr+
ElementExpr ::= /* Any expression that renders an XML element. */

Configuration Object Info

Every configuration object has information associated with it - ConfigInfo. In XStreamDB this information has an XML form - a different form for each configuration object. This configuration information is extracted using a getConfigInfo function as described under the configuration functions section. The different ConfigInfo XML is defined in XdbConfigInfo.xsd . An example of much of the ConfigInfo within the containing DBTree is in ExampleDBTree.xml .

The objectType and objectId are defined in the identity section above.

Database

          CreateDatabaseStmt ::=
          create database
          DatabaseIdStr
DropDatabaseStmt ::=
          drop database
          DatabaseIdStr

Create database creates a named empty database. Drop database removes the named database from the server. Drop database also removes any documents, roots, indexes, resource definitions and triggers for a database.

For example:

create database "/MyDb"

Root

Roots are collections of documents within a database. A root can be accessed in a query using the Root() or collection() functions. A root may or may not have an associated schema. If an alter root command has a SchemaURI and SchemaRootElement, then a Schema of that name must have been previously added to the XStreamDB server and the SchemaRootElement must exist as a global element in that schema. When a root is associated with a schema URI and schema root element, schema validation of documents at insert and replace time will take place automatically. The reason for specifying the schema root element as well as the schema URI is so multi-root element schemas can be restricted to just one schema element in that schema.

Associating a root with a schema URI and schema root element enables a number of schema based features discussed below in the schema section .

          create root
          RootIdStr (
          with schema
          SchemaUri)?
          alter root
          RootIdStr (
          with schema
          (SchemaUri |
          none
          ))?
          drop root
          RootIdStr

For example,

create root "/MyDB/MyRoot" with schema /SysData/SysSchema/MySchema.xsd Person

This example creates a new root and associates the schema /SysData/SysSchema/MySchema.xsd and schema root element Person with that root.

Enabling Root Properties

Some of these root properties affect the space and performance of roots.

Feature	Description	Notes
counter	Generate an incremental counter value for each document 1..n. This implicitly defines unique value index on the root supporting the counter.	�
guid	Generate a guid for each document. Define a unique value index on the root for this guid. Note: The guid must always be enabled before binary content objects can be stored in the root.	�

Feature enablement will be stored as a propertyList and will be stored with the root collection. For example:

<propertyList>
   <property name="guid" value="true"/>
</propertyList>

Functions to set and get root properties are:

SetRootProperty(
   $rootId as xs:string,
   $propName as xs:string,
   $onoff as xs:string)

GetRootProperty($rootId as xs:string) 
   as element(xsdb:propertyList)

Example:

SetRootProperty("db:root","guid","true")

These functions are also described in the Configuration Functions section .

Indexes

There are two kinds of indexes in XStreamDB: full text and path indexes. A full text index is associated with a root and automatically indexes every word in the content of every document inserted into that root. A path index, on the other hand, is more selective. You define a path index by specifying a path to specific data you want to index. For example, if you want to index all the FirstName values in a Person document you would construct a path like /Person/FirstName/data(). This indexes all the FirstName data values under a Person element, for all documents inserted into a root.

There is create index syntax for both kinds of index.

          CreatePathIndex ::=
          create
          unique
          ?
          index
          IndexName
          on
          RootIdStr
          path
          Path
Path ::= '/'Name ('/'Name)* /
          data()
          CreateFullTextIndex ::=
          create fulltext index on
          RootIdStr

When a path index is created the namespaces in the underlying data are ignored. If the local names in the path match the local names in the data elements, then the data is indexed.

The drop index syntax for both types of index is similar:

          DropPathIndex ::=
          drop index
          IndexNameStr
          on
          RootIdStr
DropFullTextIndex ::=
          drop fulltext index on
          RootIdStr

Triggers

Triggers are used to define an XQuery statement to execute whenever root editing occurs. Root editing happens when documents are inserted into, updated on, or deleted from a root. Triggers are useful for enforcing rules on data, such as referential integrity, or for audit logging.

Basics

The requirement of triggers is that they must allow the user to:

Create a named trigger for a root edit event (insert, update, delete). This is done by using CREATE TRIGGER.
Remove a named trigger for a root event. This is done by using DROP TRIGGER.
Describe the triggers on a root. This is done using a query on the SysTrigger root. The SysTrigger root contains XML.

Create Syntax

            CreateTrigger ::=
            create trigger
            TriggerNameStr
            on
            RootIdStr
            priority
            int (
            before
            |
            after
            )
   (
            insert
            |
            update
            |
            delete
            )
            DO
            Expr

Here is an example that logs activity on MyDb:Invoice to MyDb:Log.

create trigger "Trig1" ON "/MyDb/Invoice"
after insert do  
let $a := 
  <LogEntry>
    <Action>InsertOp</Action>
    <id>{$SysDocAfter/id}</id>
    <docid>{GetDocumentId($SysDocAfter)}</docid>
  </LogEntry> 
return insert document $a into "/st1/Log"

Create Trigger Semantics

Create causes a trigger to be added to SysTrigger and causes that trigger to be activated for the root it is created on. Create Trigger is like other DDL commands, which must be done inside a transaction but cannot be rolled back.

If multiple triggers exist for root MyRoot, insert, then they are fired in order of priority with all the ones marked before fired first, and then all the ones marked after fired after the insert.

When a trigger is created the syntax of the DoExpr and WhenExpr is compiled to detect errors.

There are two built in variables in the context of trigger based XQuery. They are:

$SysDocBefore . This is the document as it exists on disk, before the edit operation completes, the old document. For an insert operation $SysDocBefore does not exist.
$SysDocAfter . This is the document after the edit operation completes successfully, the new document. For a delete operation the SysDocAfter does not exist.

The trigger name has to be unique across the database.

Drop Syntax

            drop trigger
            TriggerIdStr

Drop Symantics

Removal of a trigger is done by name for a database since name is unique across the database. As well, when a root is dropped, all the triggers have to be deleted as well. Removal of a trigger causes that trigger to be removed from the "/SysData/SysTrigger" root.

SysTrigger Root

One root per database, called SysTrigger, contains all the trigger descriptions.

Backup/Restore

XStreamDB data can be backed up and restored by directly using the API, by using command syntax, as described here, or by using the Explorer Configuration Tab for Server, Database and Root backup.

When a backup is created, the XStreamDB data goes into a zip archive file on the server. Each DB object in the zip file is given a path and a name, as is common to most zip files.

Definitions

Below are the definitions of both the DB objects that can be backed up and the objects in the zip file.

DBObjectType ::= Server | Database | Root | Schema | User | Document
ZipObjectType ::= Schema | User | Document | ServerInfo | DatabaseInfo | 
                  RootInfo

What Can Be Backed Up

Individual documents cannot be be backed up. You can, however, backup:

Server . An entire server, including all subobjects.
Database . One or more databases, including all roots, indexes and documents.
Root . One or more roots, including all indexes and documents.
A single schema.
A single user.

The path of what can be backed up is defined as the DBObjectPath:

            DBObjectPath ::= UserPath | SchemaPath | 
                 DatabasePath | RootPath 
UserPath ::= '/'
            users
            '/'username
SchemaPath ::= '/'
            schema
            '/'schemaname
DatabasePath ::= '/'dbname
RootPath ::= '/'dbname'/'rootname

Backup Commands

Backup commands are the commands that can be sent to the XStreamDB command processor.

Backup

Syntax

              BackupCmd ::=
              backup item
              '"' DBObjectPath '"' (
              into
              ZipFileName )?

Note The default directory for backups is {InstallDir}/Server/backup.

The following example backs up a database called SomeDB into a zip file named SomeZip.zip:

backup item "/SomeDB" into "SomeZip.zip"

Note If BackupDest specifies a file that already exists, it is overwritten. BackupDest is optional. If not specified, the system chooses a filename based on date and time. The statement returns a text node with the zip file name created.

ListArchives

Syntax

              ListArchives ::=
              List Archives

Returns a collection of text nodes, one for each zip file that exists at the {InstallDir}/Server/backup directory.

Enumerate

Syntax

              Enumerate ::=
              enumerate from
              '"' ZipFileName '"'

Returns a collection of text nodes, one for each importable object in the named archive (same format as before), for example, ENUMERATE FROM "SomeZip.zip".

Restore

Syntax

              Restore Item ::=
              restore item
              RestoreItem From
                 ArchiveName ( Into RestoreDest )?
RestoreItem ::= '"' DbObjectPath '"'
RestoreDest ::= '"' DbObjectPath '"'

The RestoreDest can optionally have different dbname and/or rootname. RestoreDest is optional. If not specified, it defaults to the same name as RestoreItem. RestoreItem and RestoreDest must be at the same level that is, if one specifies a DB then the other must as well. For example,

restore item "/SomeDB" from "SomeZip.zip" into "/SomeOtherDB"

Creating a Scheduled Backup

A scheduled backup can be created, modified and deleted from the XDBExplorer configuration tab, as described in the User Guide. This section describes the low-level API-based method to create, modify and delete scheduled backups. Backup schedules are stored in the root SysData:SysBackup.

To create a new schedule for a backup insert the document following the structure below, into SysData:SysBackup and then issue a BackupSchedulesUpdated() command to notify the scheduler. For example, the following insert causes a database "/InvoiceDB" to be scheduled for backup weekly on Monday at 1:00 A.M.

insert document
<BackupSchedule>
  <Weekday>2</Weekday> 
  <Hour>1</Hour> 
  <Minute>0</Minute> 
  <BackupItem>/InvoiceDB</BackupItem> 
</BackupSchedule> 
into /SysData/SysBackup

For a daily backup every day at 1:00 P.M.:

insert document
<BackupSchedule>
   <Weekday>every</Weekday> 
   <Hour>1</Hour> 
   <Minute>0</Minute> 
   <BackupItem>/InvoiceDB</BackupItem> 
</BackupSchedule> 
into /SysData/SysBackup

For deleting and replacing a schedule use delete document and replace document commands and then use BackupSchedulesUpdated() to notify the scheduler.

Summary Tables

Objects Backed Up/Restored

If an object can be backed up and thus restored, it is shown across the top. A "Y" in the cell indicates objects and sub objects down the left side are also backed up. What sub objects are backed up is mostly determined by whether those objects are "contained" with the parent object. There is, however, exceptions to this with regard to:

Schemas:
- Schemas Bound to Roots: These will be backed up even if just the root is. When the root is restored, the bound schema will also be restored.
- DTDs referred to in Documents: These will be backed up by always backing up the schemas whether the scope of backup is Server, Database or Root. When documents are restored, the referenced DTDs will also be restored.
Resources: Whenever a document is backed up its corresponding resource info is backed up.
Categories: Whenever a Resource is backed up that refers to a category, that category will be backed up.

�	Server	DB	Root
Server	Y	�	�
DB	�	Y	�
Root	�	�	Y
Index	Y	Y	Y
Trigger	Y	Y	Y
Module	Y	�	�
Group	Y	�	�
User	Y	�	�
Document	Y	Y	Y
Binary	Y	Y	Y
Schemas	Y	Y	Y
Resources	Y	Y	Y (as referred to)
Categories	Y	Y	Y (as referred to)

Stored Modules

In XQuery, a module is either a library module or a main module. A library module is a collection of XQuery functions collected together into a module. A main module is a single XQuery expression. If a library module is defined, XStreamDB stores this module so it can be referenced later. XStreamDB supports the creation, replacement and deletion of library modules. Thus the user can create, modify and delete libraries of functions. As well, XStreamDB follows the XQuery standard for importing modules so that functions within that module can be employed in any other XQuery module, whether it be an XQuery expression or another collection of functions module. Modules are described in the W3C XQuery language document . For more particular discussion of Module Management note the sections below.

Create Module

Create an XQuery library module to be stored in XStreamDB.

            CreateModule ::=
            create module
            ModuleUri Prolog 
ModuleUri ::= StringLiteral
Prolog ::= ( ( ContextDecl )* ( ImportModule )* ( DefineFunction )* )

A module is created using the syntax above. For example,

create module "MyModLib" 
define function square(element $val) returns xsd:decimal {$val/data() * $val/data()}
define function wrap(element $nd) returns element {<dummy>{$nd}</dummy> }

The URI of the module is "MyModLib". This URI fills the roles of the name and the target namespace of the module. This URI, or name, can later be used to import the module, replace the module or delete the module. All of the names of the functions are defined in the target namespace defined by the ModuleURI. The ModuleURI is unique within a particular XStreamDB server. The body of the created module is composed of one or more declared functions.

QNames used in XQuery expressions such as XPaths in a library module will be bound to the namespace indicated by the prefix portion of the QName. For example:

create module "MyModLib" 
namespace pre = "http://bluestream.com/myns"
define function foo(element $val) returns xsd:string {$val/pre:a/pre:b/data()}

When foo is later imported and executed it is not necessary to re-define "pre" since the XPaths are now bound to "http://bluestream.com/myns".

Replace Module

To replace the module identified by ModuleURI, use the following line:

            ReplaceModule ::=
            replace module
            ModuleUri Prolog

Drop Module

To drop the module identified by ModuleURI, use the following line:

            DropModule ::=
            drop module
            ModuleUri

Import Module

The Import Module is used to import all the functions of a library module into the importing module. Once imported, all the functions in the module can be used if qualified by the correct namespace prefix. Importing is done as follows:

            ImportModule ::=
            import module
            (
            namespace
            NCName '=' )? ModuleUri

A library module is imported using its ModuleURI, which is both a namespace for that module's functions and a name for the module. To use functions in a module a prefix must be bound to this ModuleURI, or the prefix must be defined in the module prolog namespace declarations in order to access functions in this URI. Consider the following example:

import module namespace chuck = "MyModLib"
let $x := <s>20</s>
return chuck:double($x)

Basic Query Commands

Data is queried by using the XStreamDB command language. The command language is XQuery with some XStreamDB extensions. This section describes the XStreamDB implementation of XQuery with basic extensions noted as necessary.

As well as basic extensions, XStreamDB has made some advanced extensions to XQuery as decribed in the following sections on Update Commands and Full Text Search.

Queries

Syntax

To see the exact BNF of the grammar click on this link Grammar

Other more detailed discussions of the XQuery grammar can be found at W3C XQuery Language .

Lexical Structure

The table below lists any key lexical differences between XSteramDB and the W3C XQuery Language .

Rule	Production	XStreamDB
StringLiteral	::=	(["] [^"]* ["]) \| (['] [^']* ['])	Standard Escapes The following escapes can be used in any XStreamDB string: \" stands for double quotes. \' stands for a single quote. \\ stands for a backslash. \uhhhh - where "h" is a hexidecimal digit - stands for Java unicode escapes. Like Literal Escapes For literals used in LIKE expressions use: \% for a percent sign. \_ for an underscore.

Rule

Production

XStreamDB

StringLiteral

::=

(["] [^"]* ["]) | (['] [^']* ['])

Standard Escapes

The following escapes can be used in any XStreamDB string:

\" stands for double quotes.
\' stands for a single quote.
\\ stands for a backslash.
\uhhhh - where "h" is a hexidecimal digit - stands for Java unicode escapes.

Like Literal Escapes

For literals used in LIKE expressions use:

\% for a percent sign.
\_ for an underscore.

Pattern Matching with LIKE

XStreamDB supports standard "LIKE operator" processing identical to that supported in SQL.

% matches 0..n characters.
_ matches exactly one character.
The escape sequences are:
\% �for �%
\_ �for �_
\\ �for �\

Statement	Meaning
/book/[year like '199%]	Returns all the books published in the 1990s.
LET $d := "abc" WHERE $d LIKE "\u0061%" RETURN $d	Returns "abc" since \u0061 is 'a'.

Implicit Rules for Data()

When using XQuery, it is not always necessary to specify the data() accessor on the path of an element or attribute. data() is applied implicitly for:

Comparison expressions, for example, /Person/City = "Paris" means implicitly /Person/City/data() = "Paris".
Arithmetic expressions, for example, /Person/Age * 2 means implicitly /Person/City/data() * 2.

data() is NOT implied for paths in:

return statements, for example, return $p/City means return $p/City not $p/City/data().
Function bindings, unless the parameter type is a simple value and the argument is an element or attribute.

Predicate Evaluation

In a predicate such as /Person/City = "Paris" spaces are stripped off the underlying data to match "Paris". For example, the underlying XML could show:

<Person> 
  <City>
    Paris
  </City>
</Person>

There is whitespace before and after "Paris", a newline and some spaces before "Paris" and a newline after. When XStreamDB evaluates predicates it trims the City text value to remove whitespace from the beginning and end. Xdb also trims path index keys, so that the behavior is consistent in predicate evaluation whether an index exists or not.

As well, Xdb evaluates predicates in a case insensitive way. So /Person/City = "paris" matches the same documents as /Person/City = "Paris".

Query Optimization

Index Optimization

Index optimization happens automatically when XStreamDB Queries and Updates are executed.

You can detect whether index optimization is taking place by examining the speed of execution of the query on large data sets or by turning on the QueryPlan setting in the {InstallDir}/Server/conf/XDBServer.prop file and restarting the server. A GoXMLDb_QryPlan.html file will then appear in the {InstallDir}/Server/bin directory. This file shows the query plan for each query executed.

Predicate Optimization

Predicates can be expressed in XQuery in either path expressions or in the where clause of the FLWR expression. An example path expression using a predicate would be Root("/MyDB/MyRoot")/Person[City = "Paris"] .

An example where expression is:

for $p IN Root("/MyDB/MyRoot")/Person
where $p/City = "Paris"
return $p

Predicates are evaluated using available indexes. If a path index exists on path /Person/City/data() then the predicates in the above query expressions would be evaluated by seeking in the index. This index seeking can greatly reduce the number of documents the query engine has to consider when evaluating the query thus greatly improving performance.

The following comparison operators are optimized:

> �>=
< �<=
=
like prefix, for example, City like "Par%"

The types of path-index predicate optimizations done are described here. The examples use element values, but attribute values can be substituted where element names are used.

Single element, single index . As described above.
Single element, single index, multiple values . This is an " OR" list. For example, where $p/City = "Paris" or $p/City = "Toronto".
Multiple elements, multiple indexes, multiple values . AND and OR are supported. For example, where $p/City = "Paris" or $p/City = "Toronto" or $p/FirstName = "John" or $p/FirstName = "Frank".
Multiple elements, multiple path indexes, multiple . Values - parenthesis. For example, where ($p/City = "Paris" and $p/FirstName = "John") or ($p/City = "Paris" and $p/FirstName = "Frank").
Only some indexes . Many times some elements referenced in a predicate are indexed, whereas other are not. XStreamDB optimizes with indexes to reduce the set of possible documents and then uses the non-indexed element predicates on that smaller set of documents. However, by its nature, this yields no advantage for OR operations across an indexed element and another non-indexed element.

Order By/Distinct Optimization

XQuery order by expressions order a sequence of XDMValues by the key expression in the sort by clause. For example,

for $a IN Root("/PersonsDB/persons")/Person order by $a/City Return $a

This example orders all the persons by city. If there is a path index on /Person/City/data(), then the order by expression uses this path index to order the sequence of /Person fragments.

As well, since the distinct optimization has to be able to eliminate duplicates, a path index can be used to accomplish this efficiently.

Note If a sort is formulated where there are multiple keys for each value being sorted, then the values being sorted will occur multiple times. In some uses, this error wouldn't be caught, and the error wouldn't be flagged.

Join Optimization

When a query follows a certain pattern such as a nested for, multiple in clauses, or even a LET in the standard XQuery "group by pattern", then the join optimizer attempts to optimize the query using indexes.

The following table contains examples of some of the type of queries that are optimized:

Example	Discussion
FOR $c IN distinct(Root("/PersonDB/Person")/Person/City) LET $CityGroup := Root("/PersonDB/Person")[Person/City = $c] RETURN <City name={$c} count={Count($CityGroup)} />	Self Join with Distinct. Give the count of persons in each city. This optimization assumes an index on /Person/City/data(). The index is used to perform the sort as well as perform the [Person/City = $c] predicate optimization.

Full Text Search Optimization

Full text search optimization is discussed in the next section on full text search .

Functions

All function names are case sensitive. Functions that begin with an upper case letter are XStreamDB functions, functions that begin with a lower case letter are XQuery defined functions.

Functions are documented using the following form:

function-name($parameter-name as parameter-type, ...) as return-type

Notation for parameter-type and return-type in functions follows the XQuery standard for sequence types: Sequence Type Syntax which in turn relies on the XML Schema standard for data types schema data types.

The Sequence Type Syntax can be simplfied as:

SequenceType ::= KindType | AtomicType
KindType ::= KindTest "(" (optqualifiers)* ")"
AtomicType ::= QName  // eg xs:string - taken from XML Schema

Kinds are things like element, attribute, item, node. opt qualifiers are names and XML schema types, either anySimpleType or complexType. For example:

element(po:shipto, po:address) - element named shipto of type address.
element(*, po:address) // element any name of type address
item()+ // sequence of one or more nodes or atomic values
node()* // sequence of zero or more nodes of any kind

Kinds are:

kind	description
document-node	document node
element	element node
attribute	attribute node
processing-instruction	pi node
comment	comment node
text	text node
node	any node
item	any node or atomic

The following prefixes are used to for data types, as taken from XQuery Functions and Operators :

prefix	description	uri
xs	XML Schema data types.	http://www.w3.org/2001/XMLSchema
xdt	Xpath/XQuery data types. These are defined in addition to XML Schema.	http://www.w3.org/2005/02/xpath-datatypes

The following prefixes are sometimes used for functions:

prefix	description	uri
fn	Built in XQuery functions	http://www.w3.org/2005/02/xpath-functions
xsfn	Built in xdb functions	http://www.bluestream.com/xstreamdb/functions

Alphabetical List of Functions

Name . Name of function.
Prototype . Prototype of function.

FunctionName	Prototype
AddGroup	AddGroup($groupName as xs:string)
AddUserToGroup	AddUserToGroup($groupName as xs:string,$userName as xs:string)
AttributeCtor	AttributeCtor($attrName as xs:string,$value as xs:simpleType) as attribute()
avg	avg($seq as xdt:anyAtomicType*) as xdt:anyAtomicType?
CDataCtor	CDataCtor($cdata as xs:string) as cdataNode()
collection	collection( $collectionId as xs:string, [$flag) as xs:string]) as document-node()
CommentCtor	CommentCtor($commentText as xs:string)
concat	concat( $a as xdt:anyAtomicType, $b as xdt:anyAtomicType,... ) as xs:string
count	count($seq as item()*) as xs:integer
DatabaseExists	DatabaseExists($databaseId as xs:string) as xs:boolean
Date	Date() as xs:datetime
DeleteGroup	DeleteGroup($groupName as xs:string)
DeleteUser	DeleteUser($userName as xs:string)
DeleteUserFromGroup	DeleteUserFromGroup($groupName as xs:string,$userName as xs:string)
distinct	distinct($seq as xdt:anyAtomicType) as xdt:anyAtomicType
DocNumFromDocId	DocNumFromDocId($docId as xs:string) as xs:integer
document	document($url as xs:string) document-node()
DocumentByCounter	DocumentByCounter($collectionId as xs:string, $counter as xs:integer,[flags as xs:string*]) as document-node()
DocumentByDocNum	DocumentByDocNum( $collectionId as xs:string, $docNum as xs:integer, [$flags as xs:string*]) as document-node()
DocumentByGuid	DocumentByGuid( $collectionId as xs:string, $guid as xs:string, [$flags as xs:string*]) as document-node()
DocumentById	DocumentById( $documentId as xs:string, [$flags as xs:string*]) as document-node()
DocumentByPath	DocumentByPath( $fullPath as xs:string, [$flags as xs:string*]) as document-node()
DocumentCtor	DocumentCtor( $xmldecl as xs:string, $docType as xs:string, $tree as element(*)) as document-node()
DropBinaryObject	DropBinaryObject( $collectionId as xs:string, $guidStr as xs:string)
empty	empty($arg as item()*) as xs:boolean
exists	exists($arg as item()*) as xs:boolean
GenValues	GenValues($start as xs:integer, $end as xs:integer) as xs:integer*
GetACLSetting	GetACLSetting( $thisObjectType as xs:string, $thisObjectId as xs:string, $actorType as xs:string, $actorName as xs:string) as element(xsdb:Acl)
GetConfigInfo	getConfigInfo($objectType as xs:string,$objectId as xs:string) as element(*,ConfigInfoType)
GetDatabaseInfos	GetDatabaseInfos() as element(xsdb:databaseInfo)*
GetDatabaseTree	GetDatabaseTree() as element(xsdb:databaseTree)
GetDocId	GetDocId($doc as document-node() as xs:string
GetDocumentId	GetDocumentId($doc as document-node() as xs:string
GetDocVerId	GetDocId($doc as document-node() as xs:string
GetEffectiveACL	GetEffectiveACL( $thisObjectType as xs:string, $thisObjectId as xs:string, $actorType as xs:string, $actorName as xs:string) as element(xsdb:Acl)
GetFullTextIndexInfos	GetFullTextIndexInfos($rootId as string) as element(fullTextIndexInfo)
GetGroupInfos	GetGroupInfos() as element(xsdb:groupInfo)*
GetGroupMembers	GetGroupMembers($groupId as xs:string) as element (xsdb:userInfo)*
GetModuleInfos	GetModuleInfos() as element(xsdb:moduleInfo)*
GetRootInfos	GetRootInfos(databaseId as xs:string) as element (xsdb:rootInfo)*
GetRootProperty	GetRootProperty($rootId as xs:string) as element(xsdb:rootProperties)
GetTriggerInfos	GetTriggerInfos($rootId as xs:string) as element(xsdb:triggerInfo)*
GetUserGroups	GetUserGroups($userId as xs:string) as element(xsdb:groupInfo)+
GetUserInfos	GetUserInfos() as element(xsdb:userInfo)*
GetValueIndexInfos	GetValueIndexInfos($rootId as xs:string) as element(xsdb:valueIndexInfo)*
GetVerNum	GetVerNum($doc as document-node() as xs:string
GetXMLResourceText	GetXMLResourceText( $path as xs:string, $name as xs:string, $contentDocId as xs:string, $length as xs:integer) as document-node()
IdDocId	IdDocId($docVerId as xs:string) as xs:string
IdVerNum	IdVerNum($docVerId as xs:string) as xs:string
JDBC	sequence JDBC(String odbcDSN, String sqlQuery, String jdbcDriverName) JDBC( $odbcDSN as xs:string, $sqlQuery as xs:string, $jdbcDriverName as xs:string ) as element()
max	max($seq as xdt:anyAtomicType*) as xdt:anyAtomicType?
min	min($seq as xdt:anyAtomicType*) as xdt:anyAtomicType?
namespace-uri	namespace-uri($arg as node()?) as xs:anyURI
Newline	Newline() as xs:string
not	not($bool as item()*) as xs:boolean
PICtor	PICtor($tag as xs:string, $value as xs:string) as processing-instruction()
RefreshSchemas	RefreshSchemas()
ResourceContent	ResourceContent( $resId as xs:string) as document-node()
Root	Root($rootId as xs:string) as document-node()*
RootExists	RootExists($databaseId as xs:string,$rootId as xs:string) as xs:boolean
SetObjectOwner	SetOwner( $objectType as xs:string, $objectId as xs:string, $userName as xs:string)
SetRootProperty	SetRootProperty( $rootId as xs:string, $propName as xs:string, $onoff as xs:string)
SetUserDescription	SetUserDescription($userName as xs:string,$description as xs:string)
SetUserFullName	SetUserFullName($userName as xs:string,$fullname as xs:string)
SetVar	SetVar($var as variableName,$items as item()*)
Substring	SubString($str as xs:string,$offset as xs:integer,$length as xs:integer)
sum	sum($seq as xdt:anyAtomicType*) as xdt:anyAtomicType
TextLength	TextLength($items as item()*) as xs:integer
translate	translate($str as xs:string,$searchStr as xs:string,$replaceStr as xs:string) as xs:string
Trim	Trim($strIn as xs:string) as xs:string
xdbm:CounterFromDocId	xdbm:CounterFromDocId($docId as xs:string) as xs:integer
xdbm:GuidFromDocId	xdbm:GuidFromDocId($docId as xs:string) as xs:string
XSLTransform	XSLTransform ($xslTemplate as document-node(),$input as document-node()) as document-node()

Aggregation Functions

Aggregate functions are those that perform a computation on a set of values rather than on a single value.

count

Description:

Counts the number of items in a sequence and returns that count as a number.

Prototype:

count($seq as item()*) as xs:integer

Parameters:

$seq: A sequence of 0..n items. Count returns the number of values in s.

Return:

cnt: The number of items in the sequence.

distinct

Description:

(XQuery renamed to distinct-values) Compares values in a sequence and eliminates duplicates. If the sequence is a sequence of Nodes, then the nodes are compared for uniqueness recursively starting with element tag names, attribute names, attribute values, element values and so on as defined in the XQuery Functions and Operators document. On the other hand, if the sequence contains text a simple text compare is done to determine uniqueness.

Prototype:

distinct($seq as xdt:anyAtomicType*) as xdt:anyAtomicType*

Parameters:

$seq: The sequence of items. The sequence can either be a sequence of anySimpleTYpe or a sequence of nodes.

Return:

distinctSeq: The distinct sequence of items is returned.

avg

Description:

Calculates average.

Prototype:

avg($seq as xdt:anyAtomicType*) as xdt:anyAtomicType?

Parameters:

$seq: Compute an average for a sequence of numeric values. sum(V1..Vn)/n.

Return:

averageValue: The average value for this the sequence.

max

Description:

Calculates maximum numeric value in a sequence of values.

Prototype:

max($seq as xdt:anyAtomicType*) as xdt:anyAtomicType?

Parameters:

$seq: A sequence of values of some numeric type.

Return:

maximumValue: The maximum value.

min

Description:

Calculates minimum numeric value in a sequence of numeric values.

Prototype:

min($seq as xdt:anyAtomicType*) as xdt:anyAtomicType?

Parameters:

$seq: This is a sequence of values of some numeric type.

Return:

minimumValue: The minimum value in the sequence.

sum

Description:

Calculates sum.

Prototype:

sum($seq as xdt:anyAtomicType*) as xdt:anyAtomicType

Parameters:

$seq: This is a sequence of values of some numeric type.

Return:

sumValue: The sum of the values in the sequence.

Boolean Functions

Functions that return boolean values.

not

Description:

Negates the passed boolean expression.

Prototype:

not($bool as item()*) as xs:boolean

Parameters:

$bool: A boolean value. It is computed by applying a boolean test to the argument.

Return:

negation: A negation of the passed bool.

exists

Description:

Determines whether a sequence contains any nodes. Returns true for not empty, otherwise false.

Prototype:

exists($arg as item()*) as xs:boolean

Parameters:

$arg: A sequence of one or more items.

Return:

boolExists: True for not empty, false otherwise.

empty

Description:

Tests whether a sequence is empty or not.

Prototype:

empty($arg as item()*) as xs:boolean

Parameters:

$arg: Any sequence of items.

Return:

isEmpty: True for if $arg is empty, false otherwise.

Configuration functions

This group contains functions that are used to setup or get information about the XStreamDB configuration objects.

DatabaseExists

Description:

Check to see if a database exists or not.

Prototype:

DatabaseExists($databaseId as xs:string) as xs:boolean

Parameters:

$databaseId: The id of the database.

Return:

doesExist: true, for does exist, false otherwise.

Example:

DatabaseExists("/PersonDB")

RootExists

Description:

Determines if a root exists.

Prototype:

RootExists($databaseId as xs:string,$rootId as xs:string) as xs:boolean

Parameters:

$databaseId: Identifier for the database.
$rootId: Identifier for the root.

Return:

doesRootExist: true for root exists, false otherwise.

SetRootProperty

Description:

Sets a property on a root.

Prototype:

SetRootProperty(
   $rootId as xs:string,
   $propName as xs:string,
   $onoff as xs:string)

Parameters:

$rootId: A string which identifies a root.
$propName: Name of the root property. Possible values are described at: .
$onoff: A string with the value "true" or "false"

Return:

Example:

SetRootProperty("/PersonDB/Person","guid","true")
SetRootProperty("/PersonDB/Person","counter","true")

GetRootProperty

Description:

Get the properties on a root.

Prototype:

GetRootProperty($rootId as xs:string) as element(xsdb:rootProperties)

Parameters:

$rootId: A string which identifies a root.

Return:

propertyList: A root properties element.

Example:

<rootProperties>
      <propertyList>
         <property name='guid' value='true'>
         </property>
      </propertyList>
   </rootProperties>

GetConfigInfo

Description:

Obtain the information about one of the configuration objects.

Prototype:

getConfigInfo($objectType as xs:string,$objectId as xs:string) as element(*,ConfigInfoType)

Parameters:

$objectType: One of the configuration object types .
$objectId: An identifier for the particular config object in question. The forms of objectId are defined in .

Return:

configXML: Any of the defined ConfigInfo xmls defined in .

Errors:

ObjectNotFound: The identified object was not found.
InvalidType: The passed object type is invalid.
NotAuthorized: The current user is not authorized to perform this operation.

GetDatabaseInfos

Description:

Returns a sequence of DatabaseInfos.

Prototype:

GetDatabaseInfos() as element(xsdb:databaseInfo)*

Parameters:

Return:

databaseInfo: databaseInfo XML as defined in

Errors:

NotAuthorized: The current user is not authorized to perform this operation.

GetRootInfos

Description:

Returns a sequence of RootInfos for the given database.

Prototype:

GetRootInfos(databaseId as xs:string) as element (xsdb:rootInfo)*

Parameters:

databaseId: A database object identifier according to the format described in .

Return:

rootInfo*: zero or more RootInfo XML as described in

Errors:

NotAuthorized: The current user is not authorized to perform this operation.

GetValueIndexInfos

Description:

Returns a sequence of ValueIndexInfos for the given root.

Prototype:

GetValueIndexInfos($rootId as xs:string) as element(xsdb:valueIndexInfo)*

Parameters:

$rootId: A root identifier according to the format described in object

Return:

valueIndexInfo*: zero or more valueIndexInfo XML as decribed in .

Errors:

NotAuthorized: he current user is not authorized to perform this operation.

GetFullTextIndexInfos

Description:

Returns a single fullTextIndexInfo for the given root if one exists.

Prototype:

GetFullTextIndexInfos($rootId as string) as element(fullTextIndexInfo)

Parameters:

$rootId: A root identifier according to the format described in .

Return:

fullTextIndexInfo*: zero or more FullTextIndexInfo XML documents as defined in

Errors:

NotAuthorized: The current user is not authorized to perform this operation.

GetTriggerInfos

Description:

Returns a sequence of TriggerInfos for the given root.

Prototype:

GetTriggerInfos($rootId as xs:string) as element(xsdb:triggerInfo)*

Parameters:

$ rootId: A root identifier according to the format described in .

Return:

TriggerInfo*: zero or more TriggerInfo XML documents as defined in

Errors:

NotAuthorized: The current user is not authorized to perform this operation.

GetModuleInfos

Description:

Returns a sequence of ModuleInfos for the current server.

Prototype:

GetModuleInfos() as element(xsdb:moduleInfo)*

Parameters:

Return:

moduleInfo*: zero or more ModuleInfo XML documents as defined in .

GetGroupInfos

Description:

Returns a sequence of all the security GroupInfo objects on a server. This includes built in groups .

Prototype:

GetGroupInfos() as element(xsdb:groupInfo)*

Parameters:

Return:

groupInfo*: zero or more GroupInfo documents as defined in .

Errors:

NotAuthorized: The current user is not authorized to perform this operation.

GetUserInfos

Description:

Returns the UserInfos of all the users defined on the server.

Prototype:

GetUserInfos() as element(xsdb:userInfo)*

Parameters:

Return:

userInfo+: one or more UserInfo documents as defined in .

Errors:

NotAuthorized: The current user is not authorized to perform this operation.

GetUserGroups

Description:

Returns the groups for which the passed user is a member.

Prototype:

GetUserGroups($userId as xs:string) as element(xsdb:groupInfo)+

Parameters:

userId: The user Id to get groups for -eg: "/administrator".

Return:

groupInfo+: one or more groupInfo documents as defined in .

Errors:

NotFound: The passed userName is not found.
NotAuthorized: The current user is not authorized to perform this operation.

GetGroupMembers

Description:

Returns the user members for the given group.

Prototype:

GetGroupMembers($groupId as xs:string) as element (xsdb:userInfo)*

Parameters:

$groupId: The id of the group to get members for -eg "/xdbadmin".

Return:

userInfo*: Multiple <userInfo> documents

Errors:

NotFound: The passed groupId is not found.
NotAuthorized: The current user is not authorized to perform this operation.

GetDatabaseTree

Description:

Returns the DatabaseTree as defined in . The DatabaseTree is an XML "tree" composed of a list of all the databases on a server, each with its nested roots and each root with its nested indexes and nested triggers.

Prototype:

GetDatabaseTree() as element(xsdb:databaseTree)

Parameters:

Return:

databaseTree: A tree of the database infos and all contained root, trigger and index infos.

Errors:

NotAuthorized: The current user is not authorized to perform this operation.

Constructor Functions

Use these functions to construct different kinds of nodes.

DocumentCtor

Description:

Creates a new XML document complete with a declaration and a document type.

Prototype:

DocumentCtor(
   $xmldecl as xs:string,
   $docType as xs:string,
   $tree as element(*)) as document-node()

Parameters:

$xmldecl: A string which contains the XML declaration at the begining of an XML file.
$docType: A string containing the XML DocType statement which is often used to import a DTD or define entities.
$tree: The tree of XML rooted by the root element.

Return:

document: A newly constructed document.

AttributeCtor

Description:

Constructs an attribute node, which is placed as a child of an element.

Prototype:

AttributeCtor($attrName as xs:string,$value as xs:simpleType) as attribute()

Parameters:

$attrName: The name of the attribute.
$value: The value of the attribute.

Return:

$newAttribute: The newly constructed attribute

Example:

for $p in Root('/PersonsDB/Person')/Person 
where $p/@ID/data() = '12' 
return
<llnode>{AttributeCtor("jack",$p/@ID/data())}</llnode><llnode jack = '12'></llnode>

PICtor

Description:

Puts processing instructions into your XML.

Prototype:

PICtor($tag as xs:string, $value as xs:string) as processing-instruction()

Parameters:

$tag: The processing instruction tag.
$value: The processing instruction value.

Return:

newPI: The newly constructed processing instruction.

Example:

PICtor("mytag","myvalue")

CommentCtor

Description:

Puts comments into your XML.

Prototype:

CommentCtor($commentText as xs:string)

Parameters:

$commentText: The text of your comment.

Return:

$newComment: The newly constructed comment node.

CDataCtor

Description:

Use CDataCtor to put CData sections into your xml.

Prototype:

CDataCtor($cdata as xs:string) as cdataNode()

Parameters:

$cdataText: The character text of the CData.

Return:

newCData: The newly create CData node. In the XQuery data model CData is just a text node with an annotation that it is CData. In XStreamDB it is a separately handled node.

Example:

CDataCtor("here is some CData")

Content Object Identity

Content objects are either XML documents or binary objects. In XStreamDB it is possible to access content objects using a variety of identity schemes. Below are the functions that extract identifiers and convert from one kind of identifer to another. Accessing documents using these documents is handled in the section.

GetDocId

Description:

Get the DocId from the given document - without version.

Prototype:

GetDocId($doc as document-node() as xs:string

Parameters:

$doc: Valid document from XStreamDB.

Return:

docId: The docId for the passed doc - eg 1$PersonDB:Person$1-1-0

Example:<