User

Roles
Anonymous

The Offline Conditions DB framework

Art Work Detector Data baseLast Updated: May 14th, 2014 (R.Grosso)

Content  

Important links

ALICE Detector Calibration Requirement Tables and related documentation

ALICE Calibration and Alignment status table (MS PowerPoint slide)

ALICE Calibration and Alignment status Reports (MS Word document)

 

Introduction

The Offline Conditions Database (OCDB) is the place where the calibration and alignment data is stored. It is not a "database" in the literal sense of the word (like Oracle, MySQL, etc): it is a set of entries in the AliEn file catalog that point to the physical entities (ROOT files stored in the various storage elements of the grid) containing the calibration and alignement data.

The organization of the database is handled by the CDB access framework, an AliRoot-based package.The OCDB was designed under the following principles:

  • The calibration and alignment database contains ROOT TObjects stored into ROOT files;
  • Calibration and alignment objects are RUN DEPENDENT objects;
  • The database is READ-ONLY (automatic versioning of the stored objects);
  • The objects in the OCDB are univocally identified by:
    • a ( logical ) path name (path of the file in the AliEn file catalog);
    • a validity expressed as a run range ;
    • a main (grid) version number;
    • a local subversion number, only for locally stored objects.

The local subversion was introduced to avoid version clashing during tranferral of OCDB object from Grid to local storages and vice versa. In local storage only the local version is increased, while in Grid storage only the Grid version is increased. When the object is transferred from local to Grid the Grid version is increased by one; when the object is transferred from Grid to Local the Grid version is kept fixed and the subVersion is reset to zero. The adopted versioning schema is shown in the following picture.

 

Versioning schema

CDB access framework

The schema of the AliROOT-based CDB access framework is shown in the next picture.

 

CDB Access framework

 

Storage types

Three different database structures are available:
  • a GRID folder in the file catalog containing logical file names, each one pointing to a Root file. Each calibration or alignment object is contained in a single ROOT file;
  • a LOCAL folder containing Root files, each one containing one single Root object, with a structure similar to the Grid one;
  • a local Root file ( DUMP ) containing one or more objects. The objects are stored into Root TDirectories defined by the object's name and run range.

 

 

Storage activation: AliCDBManager

AliCDBManager is the singleton class used for storage activation and conditions data retrieval and storage (see next sections). It allows the instantiation of more than one storage type at a time, keeping tracks of the list of active storages.
A pointer to the single instance of the AliCDBManager class is obtained with:
AliCDBManager::Instance()
Activation of an OCDB storage is done by means of the public AliCDBManager method GetStorage(const char *uri) , which returns a pointer to an AliCDBStorage object. The U.R.I. string sintax depends on the type of storage that is being activated:

 

Grid storages

Grid storages are described by the class AliCDBGrid . The Grid storage URI is a string of question-mark-separated options defining the connection parameters. Each option is a " parameter=value" pair, where the parameters are:
  • grid (the grid host)
  • user (the user name)
  • folder (the path of the base folder)
  • se (the storage element to be used for data storage)
  • cacheFolder (the local folder used to cache the remote files: for the description of this functionality and of its further parameters see later)
The parameters are case insensitive. Example:
"alien://grid=pcapiserv01.cern.ch:10000?user=aliprod?folder= /alice/data/CDB/MainCDB?se=ALICE::CERN::SE01"
In general, however, one desn't need to specify the full set of parameter since Grid connection is done through the API (see the Alice Analysis User Guide for details). If one doesn't specify one of the parameters then the default is taken, and the default is looked for in AliCDBGrid constructor or in the API environment variables. Thus a "typical" connection requires only to specify the base folder name:
" alien://folder="
where is created from the user's home directory if it is not a full path (i.e. if it does not start with a '/'). Example:
AliCDBStorage *gridStorage =
         AliCDBManager::Instance()->GetStorage("alien://folder=/alice/data/CDB?user=aliprod");

 

Local storages

Local storages are described by the class AliCDBLocal . The local storage URI has the form:
" local://"
where is created from the working directory if it is not a full path (i.e. if it does not start with a '/'). Examples:
AliCDBStorage* localStorage = AliCDBManager::Instance()->GetStorage("local://$ALICE_ROOT");
AliCDBStorage* localStorage = AliCDBManager::Instance()->GetStorage("local:///home/colla/CDB");

Dump storages

Dump storages are described by the class AliCDBDump . The dump storage URI has the form:
"dump ://(;ReadOnly)"
where is the ROOT file name. If it doesn not containa full path it is created in the working directory. If ReadOnly option is specified the ROOT file is read only (new objects cannot be stored). Example:
AliCDBStorage* dumpStorage = AliCDBManager::Instance()->GetStorage("dump://CDBfile.root");
AliCDBStorage* dumpStorage = AliCDBManager::Instance()->GetStorage("dump:///home/colla/CDBfile.root;ReadOnly");

Activation of Default, Specific, Drain storages

AliCDBManager's method  SetDefaultStorage("const char* uri") is used to activate the particular storage used by the manager's Get and Put functions (see later). Example: 

AliCDBManager::Instance()->SetDefaultStorage("alien://folder=");

A pointer to the default storage is returned by the function GetDefaultStorage() , and the default storage is unset by the function UnsetDefaultStorage() . To check activation of the default storage use Bool_t IsDefaultStorageSet() .

AliCDBManager::SetSpecificStorage(const char* calibPath, const char* uri) allows to activate one or more "calibration-specific" storages. Specific storages are useful in case a detector expert wants to test a particular set of conditions data, stored (say) on a local disk, while leaving the reconstruction algorithms use the main OCDB locations for all the other objects.

The implementation of SetSpecificStorage goes through the mapping of the detector name (or calibration type) string with the parameters ( AliCDBParam object) describing the storage. When a conditions object is stored/retrieved using AliCDBManager 's Put/Get functions, the object path name is parsed and if a match in the list of the specific storages is found, then the corresponding storage is returned and used. If not, then the default storage (which should be activated first) is used. For more details, see later.

Examples of specific storage activation:

AliCDBManager::Instance()->SetSpecificStorage("TPC/*","alien://folder=");

AliCDBManager::Instance()->SetSpecificStorage("ITS/Calib/DeadPixelMaps","alien://folder=");

AliCDBManager::Instance()->SetSpecificStorage("*/Align/*","alien://folder=");

AliCDBManager's SetDrain(const char* uri) activates the drain storage. When activated, the drain storage stores every object retrieved from the OCDB. The drain storage is unset by UnsetDrain() ; to check activation of the default storage use Bool_t IsDrainSet() .

AliCDBManager's Print(option_t *option) prints the URI's of the default storages and of the specific storages activated.

 

AliCDBEntry, AliCDBId, AliCDBMetaData

AliCDBEntry is the container class of a single OCDB object. The container is the key object in the ROOT file that constitutes the element of the OCDB.
AliCDBEntry contains:

  • The calibration/alignment object container class (anything inheriting from ROOT's TObject class);

  • The parameters that univoquely identify the conditions data, described by the class AliCDBId ;

  • The object's metadata , described by the class AliCDBMetaData .

AliCDBEntry 's public functions:
  • SetObject(TObject*) , TObject* GetObject() ;

     

  • SetId(const AliCDBId&) , AliCDBId& GetId( ) ;
  • SetMetaData(AliCDBMetaData*) , AliCDBMetaData* GetMetaData() ;
  • PrintId() , PrintMetaData() ;
  • SetOwner(Bool_t) , Bool_t IsOwner();

     

If AliCDBEntry is owner of the contained objects, they are deleted when AliCDBEntry is deleted. WARNING: Always check the ownership of the contained object before deleting AliCDBEntry !
 
The AliCDBId object has two functions:
  1. during storage it is used to specify the path and run range of the object;
  2. during retrieval it is used as a "query": it contains the path of the object, the required run and (if needed) the version and subversion to be retrieved (if version and/or subversion are not specified the highest ones are looked for).
AliCDBId contains:
  • an object describing the name (path) of the object (AliCDBPath ). The path name must have a fixed, three-level directory structure: " level1/level2/level3" ;
  • an object describing the run validity range of the object (AliCDBRunRange );
  • the version and subversion numbers (automatically set during storage).
AliCDBId 's public functions:
  • TString& GetPath(), SetPath(const char* path), Tstring& GetLevel(int lev): return the full object's path or one of its levels;
  • AliCDBRunRange& GetAliCDBRunRange() + run number setters/getters;
    • Note: "Infinity" in the OCDB is 999999999 and is returned by static function: AliCDBRunRange::Infinity() ;
  • version/subVersion getters/setters ( GetVersion( ) , etc.);
 
AliCDBMetaData contains a further set of parameters that describe the object but that are not used for object storage/retrieval:
  • The object class name (automatically set during storage);
  • The name of the person who created the object (related methods: SetResponsible(const char*) , GetResponsible() );
  • The LHC beam period (related methods: SetBeamPeriod(Int_t*) , GetBeamPeriod() );
  • The AliROOT version used to create the object (related methods: SetAliRootVersion(const char*) , GetAliRootVersion() );
  • Any comment (related methods: SetComment(const char*) , GetComment() );
More information can be set using method SetProperty(const char* propertyName, TObject* object) . The method adds an entry (propertyName, object) to a TMap . To get the "property" related to the string