Logo ROOT  
Reference Guide
ROOT::Experimental::RNTupleDescriptor Class Reference

The on-storage meta-data of an ntuple.

Represents the on-disk (on storage) information about an ntuple. The meta-data consists of a header and one or several footers. The header carries the ntuple schema, i.e. the fields and the associated columns and their relationships. The footer(s) carry information about one or several clusters. For every cluster, a footer stores its location and size, and for every column the range of element indexes as well as a list of pages and page locations.

The descriptor provide machine-independent (de-)serialization of headers and footers, and it provides lookup routines for ntuple objects (pages, clusters, ...). It is supposed to be usable by all RPageStorage implementations.

The serialization does not use standard ROOT streamers in order to not let it depend on libCore. The serialization uses the concept of frames: header, footer, and substructures have a preamble with version numbers and the size of the writte struct. This allows for forward and backward compatibility when the meta-data evolves.

Definition at line 311 of file RNTupleDescriptor.hxx.

Classes

class  RClusterDescriptorIterable
 Used to loop over all the clusters of an ntuple (in unspecified order) More...
 
class  RColumnDescriptorIterable
 Used to loop over a field's associated columns. More...
 
class  RFieldDescriptorIterable
 Used to loop over a field's child fields. More...
 

Public Member Functions

 RNTupleDescriptor ()=default
 
 RNTupleDescriptor (const RNTupleDescriptor &other)=delete
 
 RNTupleDescriptor (RNTupleDescriptor &&other)=default
 
DescriptorId_t FindClusterId (DescriptorId_t columnId, NTupleSize_t index) const
 
DescriptorId_t FindColumnId (DescriptorId_t fieldId, std::uint32_t columnIndex) const
 
DescriptorId_t FindFieldId (std::string_view fieldName) const
 Searches for a top-level field. More...
 
DescriptorId_t FindFieldId (std::string_view fieldName, DescriptorId_t parentId) const
 
DescriptorId_t FindNextClusterId (DescriptorId_t clusterId) const
 
DescriptorId_t FindPrevClusterId (DescriptorId_t clusterId) const
 
std::unique_ptr< RNTupleModelGenerateModel () const
 Re-create the C++ model from the stored meta-data. More...
 
std::string GetAuthor () const
 
const RClusterDescriptorGetClusterDescriptor (DescriptorId_t clusterId) const
 
RClusterDescriptorIterable GetClusterIterable () const
 
const RColumnDescriptorGetColumnDescriptor (DescriptorId_t columnId) const
 
RColumnDescriptorIterable GetColumnIterable (const RFieldDescriptor &fieldDesc) const
 
RColumnDescriptorIterable GetColumnIterable (DescriptorId_t fieldId) const
 
std::string GetCustodian () const
 
std::string GetDescription () const
 
const RFieldDescriptorGetFieldDescriptor (DescriptorId_t fieldId) const
 
RFieldDescriptorIterable GetFieldIterable (const RFieldDescriptor &fieldDesc) const
 
RFieldDescriptorIterable GetFieldIterable (const RFieldDescriptor &fieldDesc, const std::function< bool(DescriptorId_t, DescriptorId_t)> &comparator) const
 
RFieldDescriptorIterable GetFieldIterable (DescriptorId_t fieldId) const
 
RFieldDescriptorIterable GetFieldIterable (DescriptorId_t fieldId, const std::function< bool(DescriptorId_t, DescriptorId_t)> &comparator) const
 
const RFieldDescriptorGetFieldZero () const
 
DescriptorId_t GetFieldZeroId () const
 Returns the logical parent of all top-level NTuple data fields. More...
 
std::uint32_t GetFooterSize () const
 
RNTupleUuid GetGroupUuid () const
 
std::uint32_t GetHeaderSize () const
 
std::string GetName () const
 
std::size_t GetNClusters () const
 
std::size_t GetNColumns () const
 
NTupleSize_t GetNElements (DescriptorId_t columnId) const
 
NTupleSize_t GetNEntries () const
 
std::size_t GetNFields () const
 
RNTupleUuid GetOwnUuid () const
 
std::string GetQualifiedFieldName (DescriptorId_t fieldId) const
 Walks up the parents of the field ID and returns a field name of the form a.b.c.d In case of invalid field ID, an empty string is returned. More...
 
std::chrono::system_clock::time_point GetTimeStampData () const
 
std::chrono::system_clock::time_point GetTimeStampWritten () const
 
RFieldDescriptorIterable GetTopLevelFields () const
 
RFieldDescriptorIterable GetTopLevelFields (const std::function< bool(DescriptorId_t, DescriptorId_t)> &comparator) const
 
RNTupleVersion GetVersion () const
 
RNTupleDescriptoroperator= (const RNTupleDescriptor &other)=delete
 
RNTupleDescriptoroperator= (RNTupleDescriptor &&other)=default
 
bool operator== (const RNTupleDescriptor &other) const
 
void PrintInfo (std::ostream &output) const
 
std::uint32_t SerializeFooter (void *buffer) const
 Serializes cluster meta data. Returns the number of bytes and fills buffer if it is not nullptr. More...
 
std::uint32_t SerializeHeader (void *buffer) const
 We deliberately do not use ROOT's built-in serialization in order to allow for use of RNTuple's without libCore Serializes the global ntuple information as well as the column and field schemata Returns the number of bytes and fills buffer if it is not nullptr. More...
 

Static Public Member Functions

static void LocateMetadata (const void *postscript, std::uint32_t &szHeader, std::uint32_t &szFooter)
 Given kNBytesPostscript bytes, extract the header and footer lengths in bytes. More...
 

Static Public Attributes

static constexpr std::uint16_t kFrameVersionCurrent = 0
 In order to handle changes to the serialization routine in future ntuple versions. More...
 
static constexpr std::uint16_t kFrameVersionMin = 0
 
static constexpr unsigned int kNBytesPostscript = 16
 The last few bytes after the footer store the length of footer and header. More...
 
static constexpr unsigned int kNBytesPreamble = 8
 The preamble is sufficient to get the length of the header. More...
 

Private Attributes

std::string fAuthor
 The origin of the data. More...
 
std::unordered_map< DescriptorId_t, RClusterDescriptorfClusterDescriptors
 May contain only a subset of all the available clusters, e.g. More...
 
std::unordered_map< DescriptorId_t, RColumnDescriptorfColumnDescriptors
 
std::string fCustodian
 The current responsible for storing the data. More...
 
std::string fDescription
 Free text from the user. More...
 
std::unordered_map< DescriptorId_t, RFieldDescriptorfFieldDescriptors
 
RNTupleUuid fGroupUuid
 Column sets that are created as derived sets from existing NTuples share the same group id. More...
 
std::string fName
 The ntuple name needs to be unique in a given storage location (file) More...
 
RNTupleUuid fOwnUuid
 Every NTuple gets a unique identifier. More...
 
std::chrono::system_clock::time_point fTimeStampData
 The time stamp of the ntuple data (immutable) More...
 
std::chrono::system_clock::time_point fTimeStampWritten
 The time stamp of writing the data to storage, which gets updated when re-written. More...
 
RNTupleVersion fVersion
 The version evolves with the ntuple summary meta-data. More...
 

Friends

class RNTupleDescriptorBuilder
 

#include <ROOT/RNTupleDescriptor.hxx>

Constructor & Destructor Documentation

◆ RNTupleDescriptor() [1/3]

ROOT::Experimental::RNTupleDescriptor::RNTupleDescriptor ( )
default

◆ RNTupleDescriptor() [2/3]

ROOT::Experimental::RNTupleDescriptor::RNTupleDescriptor ( const RNTupleDescriptor other)
delete

◆ RNTupleDescriptor() [3/3]

ROOT::Experimental::RNTupleDescriptor::RNTupleDescriptor ( RNTupleDescriptor &&  other)
default

Member Function Documentation

◆ FindClusterId()

ROOT::Experimental::DescriptorId_t ROOT::Experimental::RNTupleDescriptor::FindClusterId ( DescriptorId_t  columnId,
NTupleSize_t  index 
) const

Definition at line 681 of file RNTupleDescriptor.cxx.

◆ FindColumnId()

ROOT::Experimental::DescriptorId_t ROOT::Experimental::RNTupleDescriptor::FindColumnId ( DescriptorId_t  fieldId,
std::uint32_t  columnIndex 
) const

Definition at line 670 of file RNTupleDescriptor.cxx.

◆ FindFieldId() [1/2]

ROOT::Experimental::DescriptorId_t ROOT::Experimental::RNTupleDescriptor::FindFieldId ( std::string_view  fieldName) const

Searches for a top-level field.

Definition at line 663 of file RNTupleDescriptor.cxx.

◆ FindFieldId() [2/2]

ROOT::Experimental::DescriptorId_t ROOT::Experimental::RNTupleDescriptor::FindFieldId ( std::string_view  fieldName,
DescriptorId_t  parentId 
) const

Definition at line 625 of file RNTupleDescriptor.cxx.

◆ FindNextClusterId()

ROOT::Experimental::DescriptorId_t ROOT::Experimental::RNTupleDescriptor::FindNextClusterId ( DescriptorId_t  clusterId) const

Definition at line 697 of file RNTupleDescriptor.cxx.

◆ FindPrevClusterId()

ROOT::Experimental::DescriptorId_t ROOT::Experimental::RNTupleDescriptor::FindPrevClusterId ( DescriptorId_t  clusterId) const

Definition at line 712 of file RNTupleDescriptor.cxx.

◆ GenerateModel()

std::unique_ptr< ROOT::Experimental::RNTupleModel > ROOT::Experimental::RNTupleDescriptor::GenerateModel ( ) const

Re-create the C++ model from the stored meta-data.

Definition at line 724 of file RNTupleDescriptor.cxx.

◆ GetAuthor()

std::string ROOT::Experimental::RNTupleDescriptor::GetAuthor ( ) const
inline

Definition at line 581 of file RNTupleDescriptor.hxx.

◆ GetClusterDescriptor()

const RClusterDescriptor & ROOT::Experimental::RNTupleDescriptor::GetClusterDescriptor ( DescriptorId_t  clusterId) const
inline

Definition at line 536 of file RNTupleDescriptor.hxx.

◆ GetClusterIterable()

RClusterDescriptorIterable ROOT::Experimental::RNTupleDescriptor::GetClusterIterable ( ) const
inline

Definition at line 574 of file RNTupleDescriptor.hxx.

◆ GetColumnDescriptor()

const RColumnDescriptor & ROOT::Experimental::RNTupleDescriptor::GetColumnDescriptor ( DescriptorId_t  columnId) const
inline

Definition at line 533 of file RNTupleDescriptor.hxx.

◆ GetColumnIterable() [1/2]

RColumnDescriptorIterable ROOT::Experimental::RNTupleDescriptor::GetColumnIterable ( const RFieldDescriptor fieldDesc) const
inline

Definition at line 565 of file RNTupleDescriptor.hxx.

◆ GetColumnIterable() [2/2]

RColumnDescriptorIterable ROOT::Experimental::RNTupleDescriptor::GetColumnIterable ( DescriptorId_t  fieldId) const
inline

Definition at line 569 of file RNTupleDescriptor.hxx.

◆ GetCustodian()

std::string ROOT::Experimental::RNTupleDescriptor::GetCustodian ( ) const
inline

Definition at line 582 of file RNTupleDescriptor.hxx.

◆ GetDescription()

std::string ROOT::Experimental::RNTupleDescriptor::GetDescription ( ) const
inline

Definition at line 580 of file RNTupleDescriptor.hxx.

◆ GetFieldDescriptor()

const RFieldDescriptor & ROOT::Experimental::RNTupleDescriptor::GetFieldDescriptor ( DescriptorId_t  fieldId) const
inline

Definition at line 530 of file RNTupleDescriptor.hxx.

◆ GetFieldIterable() [1/4]

RFieldDescriptorIterable ROOT::Experimental::RNTupleDescriptor::GetFieldIterable ( const RFieldDescriptor fieldDesc) const
inline

Definition at line 540 of file RNTupleDescriptor.hxx.

◆ GetFieldIterable() [2/4]

RFieldDescriptorIterable ROOT::Experimental::RNTupleDescriptor::GetFieldIterable ( const RFieldDescriptor fieldDesc,
const std::function< bool(DescriptorId_t, DescriptorId_t)> &  comparator 
) const
inline

Definition at line 543 of file RNTupleDescriptor.hxx.

◆ GetFieldIterable() [3/4]

RFieldDescriptorIterable ROOT::Experimental::RNTupleDescriptor::GetFieldIterable ( DescriptorId_t  fieldId) const
inline

Definition at line 548 of file RNTupleDescriptor.hxx.

◆ GetFieldIterable() [4/4]

RFieldDescriptorIterable ROOT::Experimental::RNTupleDescriptor::GetFieldIterable ( DescriptorId_t  fieldId,
const std::function< bool(DescriptorId_t, DescriptorId_t)> &  comparator 
) const
inline

Definition at line 551 of file RNTupleDescriptor.hxx.

◆ GetFieldZero()

const RFieldDescriptor & ROOT::Experimental::RNTupleDescriptor::GetFieldZero ( ) const
inline

Definition at line 599 of file RNTupleDescriptor.hxx.

◆ GetFieldZeroId()

ROOT::Experimental::DescriptorId_t ROOT::Experimental::RNTupleDescriptor::GetFieldZeroId ( ) const

Returns the logical parent of all top-level NTuple data fields.

Definition at line 656 of file RNTupleDescriptor.cxx.

◆ GetFooterSize()

std::uint32_t ROOT::Experimental::RNTupleDescriptor::GetFooterSize ( ) const
inline

Definition at line 526 of file RNTupleDescriptor.hxx.

◆ GetGroupUuid()

RNTupleUuid ROOT::Experimental::RNTupleDescriptor::GetGroupUuid ( ) const
inline

Definition at line 587 of file RNTupleDescriptor.hxx.

◆ GetHeaderSize()

std::uint32_t ROOT::Experimental::RNTupleDescriptor::GetHeaderSize ( ) const
inline

Definition at line 523 of file RNTupleDescriptor.hxx.

◆ GetName()

std::string ROOT::Experimental::RNTupleDescriptor::GetName ( ) const
inline

Definition at line 579 of file RNTupleDescriptor.hxx.

◆ GetNClusters()

std::size_t ROOT::Experimental::RNTupleDescriptor::GetNClusters ( ) const
inline

Definition at line 591 of file RNTupleDescriptor.hxx.

◆ GetNColumns()

std::size_t ROOT::Experimental::RNTupleDescriptor::GetNColumns ( ) const
inline

Definition at line 590 of file RNTupleDescriptor.hxx.

◆ GetNElements()

ROOT::Experimental::NTupleSize_t ROOT::Experimental::RNTupleDescriptor::GetNElements ( DescriptorId_t  columnId) const

Definition at line 611 of file RNTupleDescriptor.cxx.

◆ GetNEntries()

ROOT::Experimental::NTupleSize_t ROOT::Experimental::RNTupleDescriptor::GetNEntries ( ) const

Definition at line 602 of file RNTupleDescriptor.cxx.

◆ GetNFields()

std::size_t ROOT::Experimental::RNTupleDescriptor::GetNFields ( ) const
inline

Definition at line 589 of file RNTupleDescriptor.hxx.

◆ GetOwnUuid()

RNTupleUuid ROOT::Experimental::RNTupleDescriptor::GetOwnUuid ( ) const
inline

Definition at line 586 of file RNTupleDescriptor.hxx.

◆ GetQualifiedFieldName()

std::string ROOT::Experimental::RNTupleDescriptor::GetQualifiedFieldName ( DescriptorId_t  fieldId) const

Walks up the parents of the field ID and returns a field name of the form a.b.c.d In case of invalid field ID, an empty string is returned.

Definition at line 642 of file RNTupleDescriptor.cxx.

◆ GetTimeStampData()

std::chrono::system_clock::time_point ROOT::Experimental::RNTupleDescriptor::GetTimeStampData ( ) const
inline

Definition at line 583 of file RNTupleDescriptor.hxx.

◆ GetTimeStampWritten()

std::chrono::system_clock::time_point ROOT::Experimental::RNTupleDescriptor::GetTimeStampWritten ( ) const
inline

Definition at line 584 of file RNTupleDescriptor.hxx.

◆ GetTopLevelFields() [1/2]

RFieldDescriptorIterable ROOT::Experimental::RNTupleDescriptor::GetTopLevelFields ( ) const
inline

Definition at line 556 of file RNTupleDescriptor.hxx.

◆ GetTopLevelFields() [2/2]

RFieldDescriptorIterable ROOT::Experimental::RNTupleDescriptor::GetTopLevelFields ( const std::function< bool(DescriptorId_t, DescriptorId_t)> &  comparator) const
inline

Definition at line 559 of file RNTupleDescriptor.hxx.

◆ GetVersion()

RNTupleVersion ROOT::Experimental::RNTupleDescriptor::GetVersion ( ) const
inline

Definition at line 585 of file RNTupleDescriptor.hxx.

◆ LocateMetadata()

void ROOT::Experimental::RNTupleDescriptor::LocateMetadata ( const void postscript,
std::uint32_t &  szHeader,
std::uint32_t &  szFooter 
)
static

Given kNBytesPostscript bytes, extract the header and footer lengths in bytes.

Definition at line 590 of file RNTupleDescriptor.cxx.

◆ operator=() [1/2]

RNTupleDescriptor & ROOT::Experimental::RNTupleDescriptor::operator= ( const RNTupleDescriptor other)
delete

◆ operator=() [2/2]

RNTupleDescriptor & ROOT::Experimental::RNTupleDescriptor::operator= ( RNTupleDescriptor &&  other)
default

◆ operator==()

bool ROOT::Experimental::RNTupleDescriptor::operator== ( const RNTupleDescriptor other) const

Definition at line 489 of file RNTupleDescriptor.cxx.

◆ PrintInfo()

void ROOT::Experimental::RNTupleDescriptor::PrintInfo ( std::ostream &  output) const

Definition at line 74 of file RNTupleDescriptorFmt.cxx.

◆ SerializeFooter()

std::uint32_t ROOT::Experimental::RNTupleDescriptor::SerializeFooter ( void buffer) const

Serializes cluster meta data. Returns the number of bytes and fills buffer if it is not nullptr.

Definition at line 542 of file RNTupleDescriptor.cxx.

◆ SerializeHeader()

std::uint32_t ROOT::Experimental::RNTupleDescriptor::SerializeHeader ( void buffer) const

We deliberately do not use ROOT's built-in serialization in order to allow for use of RNTuple's without libCore Serializes the global ntuple information as well as the column and field schemata Returns the number of bytes and fills buffer if it is not nullptr.

TODO(jblomer): instead of runtime testing for nullptr, there should be a template for the case where only the size of the buffer is required.

Definition at line 506 of file RNTupleDescriptor.cxx.

Friends And Related Function Documentation

◆ RNTupleDescriptorBuilder

friend class RNTupleDescriptorBuilder
friend

Definition at line 312 of file RNTupleDescriptor.hxx.

Member Data Documentation

◆ fAuthor

std::string ROOT::Experimental::RNTupleDescriptor::fAuthor
private

The origin of the data.

Definition at line 320 of file RNTupleDescriptor.hxx.

◆ fClusterDescriptors

std::unordered_map<DescriptorId_t, RClusterDescriptor> ROOT::Experimental::RNTupleDescriptor::fClusterDescriptors
private

May contain only a subset of all the available clusters, e.g.

the clusters of the current file from a chain of files

Definition at line 339 of file RNTupleDescriptor.hxx.

◆ fColumnDescriptors

std::unordered_map<DescriptorId_t, RColumnDescriptor> ROOT::Experimental::RNTupleDescriptor::fColumnDescriptors
private

Definition at line 336 of file RNTupleDescriptor.hxx.

◆ fCustodian

std::string ROOT::Experimental::RNTupleDescriptor::fCustodian
private

The current responsible for storing the data.

Definition at line 322 of file RNTupleDescriptor.hxx.

◆ fDescription

std::string ROOT::Experimental::RNTupleDescriptor::fDescription
private

Free text from the user.

Definition at line 318 of file RNTupleDescriptor.hxx.

◆ fFieldDescriptors

std::unordered_map<DescriptorId_t, RFieldDescriptor> ROOT::Experimental::RNTupleDescriptor::fFieldDescriptors
private

Definition at line 335 of file RNTupleDescriptor.hxx.

◆ fGroupUuid

RNTupleUuid ROOT::Experimental::RNTupleDescriptor::fGroupUuid
private

Column sets that are created as derived sets from existing NTuples share the same group id.

NTuples in the same group have the same number of entries and are supposed to contain associated data.

Definition at line 333 of file RNTupleDescriptor.hxx.

◆ fName

std::string ROOT::Experimental::RNTupleDescriptor::fName
private

The ntuple name needs to be unique in a given storage location (file)

Definition at line 316 of file RNTupleDescriptor.hxx.

◆ fOwnUuid

RNTupleUuid ROOT::Experimental::RNTupleDescriptor::fOwnUuid
private

Every NTuple gets a unique identifier.

Definition at line 330 of file RNTupleDescriptor.hxx.

◆ fTimeStampData

std::chrono::system_clock::time_point ROOT::Experimental::RNTupleDescriptor::fTimeStampData
private

The time stamp of the ntuple data (immutable)

Definition at line 324 of file RNTupleDescriptor.hxx.

◆ fTimeStampWritten

std::chrono::system_clock::time_point ROOT::Experimental::RNTupleDescriptor::fTimeStampWritten
private

The time stamp of writing the data to storage, which gets updated when re-written.

Definition at line 326 of file RNTupleDescriptor.hxx.

◆ fVersion

RNTupleVersion ROOT::Experimental::RNTupleDescriptor::fVersion
private

The version evolves with the ntuple summary meta-data.

Definition at line 328 of file RNTupleDescriptor.hxx.

◆ kFrameVersionCurrent

constexpr std::uint16_t ROOT::Experimental::RNTupleDescriptor::kFrameVersionCurrent = 0
staticconstexpr

In order to handle changes to the serialization routine in future ntuple versions.

Definition at line 497 of file RNTupleDescriptor.hxx.

◆ kFrameVersionMin

constexpr std::uint16_t ROOT::Experimental::RNTupleDescriptor::kFrameVersionMin = 0
staticconstexpr

Definition at line 498 of file RNTupleDescriptor.hxx.

◆ kNBytesPostscript

constexpr unsigned int ROOT::Experimental::RNTupleDescriptor::kNBytesPostscript = 16
staticconstexpr

The last few bytes after the footer store the length of footer and header.

Definition at line 502 of file RNTupleDescriptor.hxx.

◆ kNBytesPreamble

constexpr unsigned int ROOT::Experimental::RNTupleDescriptor::kNBytesPreamble = 8
staticconstexpr

The preamble is sufficient to get the length of the header.

Definition at line 500 of file RNTupleDescriptor.hxx.


The documentation for this class was generated from the following files: