Database Models

The database schema is defined by five Django models in cdb_rest/models.py:

        erDiagram
    GlobalTagStatus ||--o{ GlobalTag : "status"
    GlobalTag |o--o{ PayloadList : "payload_lists"
    PayloadType ||--o{ PayloadList : "payload_type"
    PayloadList |o--o{ PayloadIOV : "payload_iov"

    GlobalTagStatus {
        string name UK "unlocked / locked / frozen"
    }
    GlobalTag {
        string name UK
        string author
    }
    PayloadType {
        string name UK
    }
    PayloadList {
        string name UK "auto-generated: <type>_<id>"
    }
    PayloadIOV {
        string payload_url
        bigint major_iov
        bigint minor_iov
        bigint major_iov_end
        bigint minor_iov_end
        decimal comb_iov
    }
    

Design principles:

Metadata-only storage

The database stores references (URLs) to payload files rather than the payload data itself.

Flexible IOV model

Validity intervals use major/minor IOV pairs with optional end values; a combined decimal field (comb_iov = major_iov + minor_iov / 10^19) supports efficient “latest payload at a point” queries via the covering index (payload_list, comb_iov DESC NULLS LAST).

Version management

Global Tags group payload lists into consistent, immutable-when-locked condition sets.

Model Reference

The following documentation is generated from the model definitions.

class cdb_rest.models.GlobalTagStatus(id, name, description, created)

Bases: Model

Parameters:

• id (BigAutoField) – Primary key: Id

• name (CharField) – Name

• description (CharField) – Description

• created (DateTimeField) – Created

Reverse relationships:

Parameters:

globaltag (Reverse ForeignKey from GlobalTag) – All global tags of this global tag status (related name of status)

id

Type: BigAutoField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

name

Type: CharField

Name

A wrapper for a deferred-loading field. When the value is read from this

description

Type: CharField

Description

A wrapper for a deferred-loading field. When the value is read from this

created

Type: DateTimeField

Created

A wrapper for a deferred-loading field. When the value is read from this

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

get_next_by_created(*, field=<django.db.models.DateTimeField: created>, is_next=True, **kwargs)

Finds next instance based on created. See get_next_by_FOO() for more information.

get_previous_by_created(*, field=<django.db.models.DateTimeField: created>, is_next=False, **kwargs)

Finds previous instance based on created. See get_previous_by_FOO() for more information.

globaltag_set

Type: Reverse ForeignKey from GlobalTag

All global tags of this global tag status (related name of status)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

objects = <django.db.models.Manager object>

class cdb_rest.models.GlobalTag(id, name, author, description, status, created, updated)

Bases: Model

Parameters:

• id (BigAutoField) – Primary key: Id

• name (CharField) – Name

• author (CharField) – Author

• description (CharField) – Description

• created (DateTimeField) – Created

• updated (DateTimeField) – Updated

Relationship fields:

Parameters:

status (ForeignKey to GlobalTagStatus) – Status (related name: globaltag)

Reverse relationships:

Parameters:

payload_lists (Reverse ForeignKey from PayloadList) – All payload lists of this global tag (related name of global_tag)

id

Type: BigAutoField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

name

Type: CharField

Name

A wrapper for a deferred-loading field. When the value is read from this

author

Type: CharField

Author

A wrapper for a deferred-loading field. When the value is read from this

description

Type: CharField

Description

A wrapper for a deferred-loading field. When the value is read from this

status

Type: ForeignKey to GlobalTagStatus

Status (related name: globaltag)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

created

Type: DateTimeField

Created

A wrapper for a deferred-loading field. When the value is read from this

updated

Type: DateTimeField

Updated

A wrapper for a deferred-loading field. When the value is read from this

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

get_next_by_created(*, field=<django.db.models.DateTimeField: created>, is_next=True, **kwargs)

Finds next instance based on created. See get_next_by_FOO() for more information.

get_next_by_updated(*, field=<django.db.models.DateTimeField: updated>, is_next=True, **kwargs)

Finds next instance based on updated. See get_next_by_FOO() for more information.

get_previous_by_created(*, field=<django.db.models.DateTimeField: created>, is_next=False, **kwargs)

Finds previous instance based on created. See get_previous_by_FOO() for more information.

get_previous_by_updated(*, field=<django.db.models.DateTimeField: updated>, is_next=False, **kwargs)

Finds previous instance based on updated. See get_previous_by_FOO() for more information.

objects = <django.db.models.Manager object>

payload_lists

Type: Reverse ForeignKey from PayloadList

All payload lists of this global tag (related name of global_tag)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

status_id

Internal field, use status instead.

class cdb_rest.models.PayloadType(id, name, description, created)

Bases: Model

Parameters:

• id (BigAutoField) – Primary key: Id

• name (CharField) – Name

• description (CharField) – Description

• created (DateTimeField) – Created

Reverse relationships:

Parameters:

payloadlist (Reverse ForeignKey from PayloadList) – All payload lists of this payload type (related name of payload_type)

id

Type: BigAutoField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

name

Type: CharField

Name

A wrapper for a deferred-loading field. When the value is read from this

description

Type: CharField

Description

A wrapper for a deferred-loading field. When the value is read from this

created

Type: DateTimeField

Created

A wrapper for a deferred-loading field. When the value is read from this

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

get_next_by_created(*, field=<django.db.models.DateTimeField: created>, is_next=True, **kwargs)

Finds next instance based on created. See get_next_by_FOO() for more information.

get_previous_by_created(*, field=<django.db.models.DateTimeField: created>, is_next=False, **kwargs)

Finds previous instance based on created. See get_previous_by_FOO() for more information.

objects = <django.db.models.Manager object>

payloadlist_set

Type: Reverse ForeignKey from PayloadList

All payload lists of this payload type (related name of payload_type)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

class cdb_rest.models.PayloadListIdSequence(id)

Bases: Model

Parameters:

id (BigAutoField) – Primary key: Id

id

Type: BigAutoField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

objects = <django.db.models.Manager object>

class cdb_rest.models.PayloadList(id, name, description, global_tag, payload_type, created, updated)

Bases: Model

Parameters:

• id (BigIntegerField) – Primary key: Id

• name (CharField) – Name

• description (CharField) – Description

• created (DateTimeField) – Created

• updated (DateTimeField) – Updated

Relationship fields:

Parameters:

• global_tag (ForeignKey to GlobalTag) – Global tag (related name: payload_lists)

• payload_type (ForeignKey to PayloadType) – Payload type (related name: payloadlist)

Reverse relationships:

Parameters:

payload_iov (Reverse ForeignKey from PayloadIOV) – All payload iov of this payload list (related name of payload_list)

id

Type: BigIntegerField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

name

Type: CharField

Name

A wrapper for a deferred-loading field. When the value is read from this

description

Type: CharField

Description

A wrapper for a deferred-loading field. When the value is read from this

global_tag

Type: ForeignKey to GlobalTag

Global tag (related name: payload_lists)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

payload_type

Type: ForeignKey to PayloadType

Payload type (related name: payloadlist)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

created

Type: DateTimeField

Created

A wrapper for a deferred-loading field. When the value is read from this

updated

Type: DateTimeField

Updated

A wrapper for a deferred-loading field. When the value is read from this

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

get_next_by_created(*, field=<django.db.models.DateTimeField: created>, is_next=True, **kwargs)

Finds next instance based on created. See get_next_by_FOO() for more information.

get_next_by_updated(*, field=<django.db.models.DateTimeField: updated>, is_next=True, **kwargs)

Finds next instance based on updated. See get_next_by_FOO() for more information.

get_previous_by_created(*, field=<django.db.models.DateTimeField: created>, is_next=False, **kwargs)

Finds previous instance based on created. See get_previous_by_FOO() for more information.

get_previous_by_updated(*, field=<django.db.models.DateTimeField: updated>, is_next=False, **kwargs)

Finds previous instance based on updated. See get_previous_by_FOO() for more information.

global_tag_id

Internal field, use global_tag instead.

objects = <django.db.models.Manager object>

payload_iov

Type: Reverse ForeignKey from PayloadIOV

All payload iov of this payload list (related name of payload_list)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

payload_type_id

Internal field, use payload_type instead.

class cdb_rest.models.PayloadIOV(id, payload_url, checksum, size, major_iov, minor_iov, major_iov_end, minor_iov_end, payload_list, extra, inserted, updated, comb_iov)

Bases: Model

Parameters:

• id (BigAutoField) – Primary key: Id

• payload_url (CharField) – Payload url

• checksum (CharField) – Checksum

• size (BigIntegerField) – Size

• major_iov (BigIntegerField) – Major iov

• minor_iov (BigIntegerField) – Minor iov

• major_iov_end (BigIntegerField) – Major iov end

• minor_iov_end (BigIntegerField) – Minor iov end

• extra (CharField) – Extra

• inserted (DateTimeField) – Inserted

• updated (DateTimeField) – Updated

• comb_iov (DecimalField) – Comb iov

Relationship fields:

Parameters:

payload_list (ForeignKey to PayloadList) – Payload list (related name: payload_iov)

id

Type: BigAutoField

Primary key: Id

A wrapper for a deferred-loading field. When the value is read from this

payload_url

Type: CharField

Payload url

A wrapper for a deferred-loading field. When the value is read from this

checksum

Type: CharField

Checksum

A wrapper for a deferred-loading field. When the value is read from this

size

Type: BigIntegerField

Size

A wrapper for a deferred-loading field. When the value is read from this

major_iov

Type: BigIntegerField

Major iov

A wrapper for a deferred-loading field. When the value is read from this

minor_iov

Type: BigIntegerField

Minor iov

A wrapper for a deferred-loading field. When the value is read from this

major_iov_end

Type: BigIntegerField

Major iov end

A wrapper for a deferred-loading field. When the value is read from this

minor_iov_end

Type: BigIntegerField

Minor iov end

A wrapper for a deferred-loading field. When the value is read from this

payload_list

Type: ForeignKey to PayloadList

Payload list (related name: payload_iov)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

extra

Type: CharField

Extra

A wrapper for a deferred-loading field. When the value is read from this

inserted

Type: DateTimeField

Inserted

A wrapper for a deferred-loading field. When the value is read from this

updated

Type: DateTimeField

Updated

A wrapper for a deferred-loading field. When the value is read from this

comb_iov

Type: DecimalField

Comb iov

A wrapper for a deferred-loading field. When the value is read from this

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

get_next_by_inserted(*, field=<django.db.models.DateTimeField: inserted>, is_next=True, **kwargs)

Finds next instance based on inserted. See get_next_by_FOO() for more information.

get_next_by_updated(*, field=<django.db.models.DateTimeField: updated>, is_next=True, **kwargs)

Finds next instance based on updated. See get_next_by_FOO() for more information.

get_previous_by_inserted(*, field=<django.db.models.DateTimeField: inserted>, is_next=False, **kwargs)

Finds previous instance based on inserted. See get_previous_by_FOO() for more information.

get_previous_by_updated(*, field=<django.db.models.DateTimeField: updated>, is_next=False, **kwargs)

Finds previous instance based on updated. See get_previous_by_FOO() for more information.

objects = <django.db.models.Manager object>

payload_list_id

Internal field, use payload_list instead.

Common Query Patterns

Navigating the relationships from Python (the reverse relation names are payload_lists on GlobalTag and payload_iov on PayloadList):

from cdb_rest.models import GlobalTag, PayloadList, PayloadIOV

# Payload lists attached to a Global Tag, with their payload types
gt = GlobalTag.objects.get(name="sPHENIX_ExampleGT_24")
for pl in gt.payload_lists.all():
    print(pl.name, pl.payload_type.name)

# Payload IOVs in a payload list
pl = PayloadList.objects.get(name="Beam_210")
iovs = pl.payload_iov.all()

# Latest payload per list at a given IOV point, filtered by Global Tag
from decimal import Decimal
point = Decimal(major_iov) + Decimal(minor_iov) / 10**19
latest = (PayloadIOV.objects
          .filter(payload_list__global_tag__name="sPHENIX_ExampleGT_24",
                  comb_iov__lte=point)
          .order_by('payload_list_id', '-comb_iov')
          .distinct('payload_list_id'))

Field notes:

• Name fields are unique and limited to 80 characters (255 for PayloadList); description fields to 255 characters.

• IOV values are BigInteger to support large run numbers; open-ended IOVs use sys.maxsize.

• All models carry auto-populated creation (and where relevant, update) timestamps.

• PayloadIOV.extra is a free-form field surfaced as revision by the /payloadiovs/ query.

See Also

• API Documentation - REST API endpoints for model operations

• Django Views - Django views that handle model interactions

• Architecture - Overall system architecture and design decisions