Overview: IOV Versions and Folder Tags

The basic guideline behind the COOL versioning mechanism is that it should be possible to define a set of versions, or "tag", such that for any given data item and at any given validity time only one conditions data object (or none at all) is valid in that tag. The name of one such tag (rather than individual version numbers) must be specified when retrieving data from COOL. This guideline, which is meant to remove any ambiguities in IOV lookup, imposes some constraints on data insertion, which are discussed in the following paragraphs.

Single-version (SV) folders

For SV folders, there are no versions or tags: by definition, in any channel there can be only one conditions object that is valid at a given validity time. Data insertion must therefore ensure that there are no overlaps between any two IOVs in the same channel: the software throws an exception if the user attempts to store a conditions data object whose IOV covers a time range where another conditions data object is already defined

Multi-version (MV) folders

For MV folders, when a user inserts a conditions data object whose IOV is the same as that of an already existing one, COOL stores it as a new version of that object. The situation is more complex when the user inserts an object which only partially overlaps an already existing IOV: in this case, COOL automatically creates some IOVs to maintain a special "HEAD" tag of the data, which for any given validity time contains the most recent version of the payload. For instance, if an IOV with payload A exists in [0,2] and a new IOV with payload B is inserted in [0,1], COOL automatically creates a new IOV with payload A in [1,2]: the new HEAD contains B in [0,1] and A in [1,2]. In the COOL relational schema, the information necessary to manage the HEAD of a folder is entirely contained in its IOV table, using some special columns.

While the HEAD of a folder can always be queried directly, its contents change as new data are inserted. For this reason, COOL allows users at all times to copy the current HEAD into their own tags: these tags are referred to as "standard tags", or just "tags" (as they were originally the only type of tags supported). In the COOL relational schema, the information necessary to manage "standard tags" of a folder is contained in a special IOV2TAG table, which maintains the many-to-many relationship between tags and the associated IOVs.

In addition to "standard tags", COOL supports another tagging mechanism, that was introduced more recently. Whenever users insert an IOV, they may immediately specify that this IOV should be associated to one "user tag" of their choice. In this case, COOL automatically creates some IOVs to maintain the HEAD of the subset of all IOVs in the folder that were inserted with that user tag. The resulting list of IOVs, which may vary as new IOVs are inserted, can be queried by specifying the name of the user tag. In the COOL relational schema, the information necessary to manage user tags inside a folder is entirely contained in its IOV table, using some special columns similar to those needed for managing the global HEAD of the folder.

Examples (documentation for end-users)

A simple MV example (no validity range overlap between IOVs)

Alice and Bob need to compute and store the calibration of the same detector in the same IOV [10,20]. They use different algorithms from each other, and each of them individually tries out different versions of his/her algorithm over time. In particular, Alice first computes and stores a version A1 of the data at time t1, followed by Bob that computes and stores B1 at time t2, then they both recompute and store new versions A2 and B2 respectively and in this order at times t3 and t4.

COOL MV folders offer several ways to store (and later retrieve) the calibration valid in [10,20] using the IFolder::storeObject interface:

1. Alice and Bob can store their data without associating "user tags" to them (userTagName=""), and later retrieving them using "standard tags". If Carl retrieves the HEAD calibration at a time between t3 and t4, he will retrieve the A2 inserted by Alice. If we assume that David had tagged the HEAD as "PROD" (by calling tagCurrentHead) at a time between t2 and t3, when Carl queries the "PROD" tag after time t4 he will retrieve the B1 data inserted by Bob.
2. Alice and Bob can store their data associating "user tags" such as "ALICE" and "BOB" to them (userTagName!="") as well as "standard tags (userTagOnly=false), and later retrieving them using "user tags" or "standard tags". If Carl retrieves the HEAD calibration at a time between t3 and t4, he will still retrieve the A2 inserted by Alice. If we assume that David had tagged the HEAD as "PROD" (by calling tagCurrentHead) at a time between t2 and t3, when Carl queries the "PROD" tag after time t4 he will still retrieve the B1 data inserted by Bob. In addition, if Carl queries the "ALICE" tag after time t4 he will retrieve the last version A2 inserted by Alice.
3. Alice and Bob can store their data associating "user tags" such as "ALICE" and "BOB" to them (userTagName!="") but no "standard tags (userTagOnly=true), and later retrieving them using "user tags". If Carl queries the HEAD calibration at a time between t3 and t4, he will not retrieve any IOV, as neither Alice's nor Bob's IOVs have been inserted to the shared HEAD common to all user tags. Conversely, if Carl queries the "ALICE" tag after time t4 he will still retrieve the last version A2 inserted by Alice.

Relational implementation (documentation for developers and DBAs)

...not yet documented...

Checking the versioning mode of existing data (documentation for data managers)

...not yet documented...

-- AndreaValassi - 13-Jan-2012