The BABAR Event Store User's Guide
Version Information
Draft: 22nd June 1998
This document is still under development. If you have any questions or comments, please address them to the author.
The BABAR Event Store provides the mechnaism for storage and retrieval of
experimental data from the BABAR detector. Each event, whether it is generated by the detector itself, or by
a Monte Carlo simulation application is saved in the store and can have additional information added to it by reconstruction and analysis programs. Collections of such events can be created and saved. Such collections can later be retrieved by
name.
The event store supports the experiment as a whole, specialized work-groups and the individual user. Thus an individual user may create their own event collections (typically such collections do not cause much or any of the
event data to be replicated) whilst they perform their own exploratory analyses. Once the sample of events or selection criteria are stable, such collections may be made available to groups (typically physics analysis groups) or to the experiment as a
whole.
Access to the events of interest can be optimized by various placement strategies whereby the sections of the interesting events that are most heavily accessed can be clustered together so that prefetching occurs, whilst
still allowing access to the rest of the event data with some performance penalty.
All applications using the Event Store class library access information via a single BdbEventStore class. This
provides access to the named collections of events. Possible processing models include the following:
- Locate an input event collection. Iterate over the events in this collection, building another output event collection of events that satisfy the desired selection criteria. This new collection may itself be used as the
input collection for a further selection process, or may discarded and the selection process repeated with different selection criteria. Eventually a new output collection will be created that contains all the events of interest.
- Locate an input event collection. Iterate over the events in the collection, processing them and adding more information to each event. This new information might comprise a high level summary allowing later rapid event
selection in addition to the detailed information that has been added.
Return to Table of Contents.
Authorization levels are discussed in detail in the context of the BABAR Database Management System. An application can be executed in one of several authorization levels. The level determines certain access rights to the contents of the event store
and may restrict the ability of the application to update the contents. Available authorization levels are:
- System. An application operating at this level has full control over the event store, allowing it read, update, create and delete privileges.
- Group. An application operating at this level has read-only access to the event store apart from databases and contents corresponding to a specified group. Groups are intended to correspond to physics analysis
work-groups and similar. Information from the other authorization levels and other groups may be replicated within the context of the current group.
- User. When operating at this level, the application has read-only access to the event store apart from databases and contents corresponding to a specified user. Users correspond to UNIX accounts [SLAC AFS
Accounts?]. Information from the other authorization levels and other users may be replicated within the context of the current user.
The BABAR database management system is comprised of three basic domains:
Authorization levels are domain-specific, and an application may execute at one authorization level for one domain (e.g. Conditions database access) and at another level within another domain (e.g. Event
Store access).
By default an application operates at User authorization level for the event store domain, granting it restricted access. It may request a higher level of authorization for this domain, but this will only be successful if
previously granted by the database administrator. Note however, that it is always granted read access to all the event store information.
Return to Table of Contents.
Event collections contain references to events within the event store. Multiple types of collections are supported, although they all exhibit the same abstract interface. The multiple collections are designed to accommodate
both vector or small (based on a vector or event references and limited to less than 10^5 events) and tree or large (based on a tree of collections and allowing up to 10^12 events) collections
of events. In either cases, collections may be added to other collections, but the behaviour depends upon whether the collection being added to is a vector or tree collection. In the former case, the event references themselves are added to the
collection, whereas in the latter, the reference collection is itself added to the collection being added to.
Collections are accessed as transient objects, shielding the application progrmmer from the underlying persistent objects. As noted above, all event collections obey the same abstract interface, which is the mechanism by
which new events can be added to an existing collections, or by which all the events within the collection may be accessed. Event collection iterators may be associated with an event collection and used to iterate other the events in the
collection.
Return to Table of Contents.
Collection names are the mechanism by which collections are accessed from the BdbEventStore object. Names can be absolute or relative, the latter being relative to the current authorization level and subdirectory location
(see later) within the event store. The format of the collection name is:
[/<level>/][<groupuser>/][<subdir>/<subdir>/]<name>
Where components in "[]" are optional components. The meaning of the components is:
- /<level>/ is the authorization level within the events store domain, and can be one of /system/, /groups/
or/users/. Case is ignored, although the use of lowercase is recommended. Absolute collection names must begin with this component.
- <groupuser>/ is the group or user name for the/groups/ or/users/ authorization levels respectively. The special string
<user>/ corresponds to the current user name. Group or user names must conform to valid Unix file name syntax.
- <subdir/> is a concept that corresponds to a subdirectory in a Unix file system, and a hierarchy of these may be used to group collections together within an authorization level. Note that
this is a logical grouping only and is not reflected in physical database locations. The special string::/ denotes the immediate parent in the subdirectory tree. Subdirectories must conform to valid Unix file name
syntax.Subdirectories are implemented in releases 6.8.0 onwards.
- <name> is the name of the collection itself. This cannot contain embedded "/" characters.
Other than the <level> and <groupuser> component in the /users/ level, component names and collection names may contain any printable
characher including embedded spaces (but not the "/" or double-quote """ characters). In this case the name must be specified in double-quotes.
The following are examples of collection names.
MyCollection
/group/TauPhysics/GoldTauEvents/TheTauCollection
"/users/quarrie/A collection with embedded spaces"
../becla/HisCollection
Return to Table of Contents.
The following code fragment illustrates how a collection may be located either by absolute or relative name.
#include "BdbEvent/BdbEvent.hh"
#include "BdbEventStore/BdbEventStore.hh"
#include "BdbEventStore/BdbCollection.hh"
[....]
BdbCollection<BdbEvent> aColl1;
BdbCollection<BdbEvent> aColl2;
BdbEventStore theStore;
BdbStatus status;
[....]
// Start an read transaction
theStore.startRead( );
// Locate a collection using its absolute name
status = theStore,collection( aColl1,
"/users/quarrie/MyCollection" );
if ( BdbcSuccess != status ) {
[....]
}
// Locate another collection using its relative name
status = theStore.collection( aColl2,
"../becla/HisCollection" );
if ( aColl2..isNull( ) ) {
[....]
}
Notes:
- The collection classes are templated. Use of classes other than BdbEvent as the template parameter is
not yet fully supported.
- Use of the BdbCollection::isNull( ) member function to test for successful location of the specified collection is an alternative to testing the collection( ) function
return value.
- Refer to the BABAR Event Store Reference Manual for a full description of the BdbEventStore class.
Return to Table of Contents.
The following code fragment illustrates iteration over the events within a collection:
#include "BdbEvent/BdbEvent.hh"
#include "BdbEventStore/BdbEventStore.hh"
#include "BdbEventStore/BdbCollection.hh"
#include "BdbEventStore/BdbCollectionIterator.hh"
[....]
BdbCollection<BdbEvent> aCollection;
BdbEventStore theStore;
BdbRef(BdbEvent) anEvent;
BdbStatus status;
[....]
// Start an read transaction
theStore.startRead( );
// Locate a collection using its absolute name
status = theStore.collection( aCollection,
"/users/quarrie/MyCollection" );
if ( BdbcSuccess != status ) {
// Collection found - iterate over all events
BdbCollectionIterator<BdbEvent> anIter( aCollection );
while ( BdbcSuccess == ( status = anIter.next( anEvent ) ) ) {
// Next event found - deal with it
[....]
}
// Reset the collection & iterate again
anIter.reset( );
[....]
}
Notes:
- The collection classes and iterators are templated. Use of classes other than BdbEvent as the template
parameter is not yet fully supported.
- An iterator may be reset using the reset( ) member function or redirected to another collection through use of the setCollection( ) member function.
- Refer to the BABAR Event Store Reference Manual for a full description of the BdbCollection andBdbCollectionIterator classes.
Return to Table of Contents.
The following code fragment illustrates how a new vector or tree collection may be created.
#include "BdbEvent/BdbEvent.hh"
#include "BdbEventStore/BdbEventStore.hh"
#include "BdbEventStore/BdbTreeCollection.hh"
#include "BdbEventStore/BdbVectorCollection.hh"
[....]
BdbCollection<BdbEvent> aColl1;
BdbCollection<BdbEvent> aColl2;
BdbEventStore theStore;
BdbStatus status;
[....]
// Start an update transaction
theStore.startUpdate( );
// See whether the tree collection already exists and
// create it if required
status = theStore.collection( aColl1,
"/users/quarrie/MyTreeCollection" );
if ( BdbcSuccess != status ) {
status = theStore.treeCollection( aColl1,
"/users/quarrie/MyTreeCollection" );
}
// See whether the vector collection already exists and
// create it if required
status = theStore.collection( aColl2,
"/users/quarrie/MyVectorCollection" );
if ( aColl2..isNull( ) ) {
status = theStore.vectorCollection( aColl2,
"/users/quarrie/MyVectorCollection" );
}
Notes:
- The collection classes are templated. Use of classes other than BdbEvent as the template parameter is
not yet fully supported.
- The treeCollection( ) and vectorCollection( ) member functions will only create the specified collection if it doesn't already exist, returning the reference to an
existing collection otherwise. The return value does not allow these cases to be differentiated. The exaple therefore explicitly tests for the existence of the collection before creating it.
- Use of the BdbCollection::isNull( ) member function to test for successful creation or location of the specified collection is an alternative to testing the function return value.
- Refer to the BABAR Event Store Reference Manual for a full description of the BdbEventStore class.
Return to Table of Contents.
Events are represented as a hierarchy of objects based upon an event header. This header contains references to multiple child objects, each corresponding to a particular processing stage as described earlier. The
information for each processing stage is organized as a tree header with references to further child objects. In addition, a summary or event query tag object is designed to allow for rapid but simple selection tests to be made on the
event. Queries can be made against any object within the event hierarchy, but there is a trade-off between performance and complexity of such queries. Extremely high performance queries can make selections based on the event query tag, while less
performance but more complexity can result from accessing the objects within the trees.
The types of information that can be associated with each event are the following:
- Simulated data (sim). This is specific to events that have been generated as a result of Monte Carlo simulations, and contains the equivalent of the raw data and the underlying physics, absolute position and energy
information (truth).
- Raw data (raw). This is the information that is available at the output of the online system, having been processed within the front-end electronics and possibly within the Online Event Processing (OEP)
farm.
- Reconstructed Data (rec). This is the output of reconstruction. It includes tracks and calorimeter clusters etc.
- Event Query Tag Data (tag). This is a highly compressed summary that classifies the event and allows simple selection queries to be performed without accessing other information.
- Event Header (hdr). The event header contains references to the other information in the event. It is designed to be as compact as possible.
Note that this is not expected to be a complete set of event components. The structure should be designed to be extensible, allowing for new components to be added to the event in a manner that minimizes schema
evolution.
A simplified view of the event object hierarchy is shown below.
Note that the event header, the tree headers & the various tag objects must be located separately from the bulk of the data that makes up the event in order to take advantage of clustering prefetching etc.In order to
allow for separate migration to the mass store, these should be in separate databases files rather than separate containers within the same databases.
Return to Table of Contents.
DB Home | BaBar Home | Computing | Reconstruction | Simulation | Search
 DRQuarrie@LBL.Gov
|
