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 279 of file RNTupleDescriptor.hxx.

Classes
class	RColumnDescriptorRange
	Used to loop over a field's associated columns. More...

class	RFieldDescriptorRange
	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.

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< RNTupleModel >	GenerateModel () const
	Re-create the C++ model from the stored meta-data.

std::string	GetAuthor () const

const RClusterDescriptor &	GetClusterDescriptor (DescriptorId_t clusterId) const

const RColumnDescriptor &	GetColumnDescriptor (DescriptorId_t columnId) const

RColumnDescriptorRange	GetColumnRange (const RFieldDescriptor &fieldDesc) const

RColumnDescriptorRange	GetColumnRange (DescriptorId_t fieldId) const

std::string	GetCustodian () const

std::string	GetDescription () const

const RFieldDescriptor &	GetFieldDescriptor (DescriptorId_t fieldId) const

RFieldDescriptorRange	GetFieldRange (const RFieldDescriptor &fieldDesc) const

RFieldDescriptorRange	GetFieldRange (const RFieldDescriptor &fieldDesc, const std::function< bool(DescriptorId_t, DescriptorId_t)> &comparator) const

RFieldDescriptorRange	GetFieldRange (DescriptorId_t fieldId) const

RFieldDescriptorRange	GetFieldRange (DescriptorId_t fieldId, const std::function< bool(DescriptorId_t, DescriptorId_t)> &comparator) const

DescriptorId_t	GetFieldZeroId () const
	Returns the logical parent of all top-level NTuple data fields.

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.

std::chrono::system_clock::time_point	GetTimeStampData () const

std::chrono::system_clock::time_point	GetTimeStampWritten () const

RFieldDescriptorRange	GetTopLevelFields () const

RFieldDescriptorRange	GetTopLevelFields (const std::function< bool(DescriptorId_t, DescriptorId_t)> &comparator) const

RNTupleVersion	GetVersion () const

RNTupleDescriptor &	operator= (const RNTupleDescriptor &other)=delete

RNTupleDescriptor &	operator= (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.

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.

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.

Static Public Attributes
static constexpr std::uint16_t	kFrameVersionCurrent = 0
	In order to handle changes to the serialization routine in future ntuple versions.

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.

static constexpr unsigned int	kNBytesPreamble = 8
	The preamble is sufficient to get the length of the header.

Private Attributes
std::string	fAuthor
	The origin of the data.

std::unordered_map< DescriptorId_t, RClusterDescriptor >	fClusterDescriptors
	May contain only a subset of all the available clusters, e.g.

std::unordered_map< DescriptorId_t, RColumnDescriptor >	fColumnDescriptors

std::string	fCustodian
	The current responsible for storing the data.

std::string	fDescription
	Free text from the user.

std::unordered_map< DescriptorId_t, RFieldDescriptor >	fFieldDescriptors

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

std::string	fName
	The ntuple name needs to be unique in a given storage location (file)

RNTupleUuid	fOwnUuid
	Every NTuple gets a unique identifier.

std::chrono::system_clock::time_point	fTimeStampData
	The time stamp of the ntuple data (immutable)

std::chrono::system_clock::time_point	fTimeStampWritten
	The time stamp of writing the data to storage, which gets updated when re-written.

RNTupleVersion	fVersion
	The version evolves with the ntuple summary meta-data.

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 724 of file RNTupleDescriptor.cxx.

◆ FindColumnId()

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

Definition at line 713 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 706 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 668 of file RNTupleDescriptor.cxx.

◆ FindNextClusterId()

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

Definition at line 737 of file RNTupleDescriptor.cxx.

◆ FindPrevClusterId()

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

Definition at line 751 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 763 of file RNTupleDescriptor.cxx.

◆ GetAuthor()

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

inline

Definition at line 499 of file RNTupleDescriptor.hxx.

◆ GetClusterDescriptor()

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

inline

Definition at line 459 of file RNTupleDescriptor.hxx.

◆ GetColumnDescriptor()

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

inline

Definition at line 456 of file RNTupleDescriptor.hxx.

◆ GetColumnRange() [1/2]

RColumnDescriptorRange ROOT::Experimental::RNTupleDescriptor::GetColumnRange ( const RFieldDescriptor & fieldDesc ) const

inline

Definition at line 488 of file RNTupleDescriptor.hxx.

◆ GetColumnRange() [2/2]

RColumnDescriptorRange ROOT::Experimental::RNTupleDescriptor::GetColumnRange ( DescriptorId_t fieldId ) const

inline

Definition at line 492 of file RNTupleDescriptor.hxx.

◆ GetCustodian()

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

inline

Definition at line 500 of file RNTupleDescriptor.hxx.

◆ GetDescription()

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

inline

Definition at line 498 of file RNTupleDescriptor.hxx.

◆ GetFieldDescriptor()

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

inline

Definition at line 453 of file RNTupleDescriptor.hxx.

◆ GetFieldRange() [1/4]

RFieldDescriptorRange ROOT::Experimental::RNTupleDescriptor::GetFieldRange ( const RFieldDescriptor & fieldDesc ) const

inline

Definition at line 463 of file RNTupleDescriptor.hxx.

◆ GetFieldRange() [2/4]

RFieldDescriptorRange ROOT::Experimental::RNTupleDescriptor::GetFieldRange	(	const RFieldDescriptor &	fieldDesc,
		const std::function< bool(DescriptorId_t, DescriptorId_t)> &	comparator
	)		const

inline

Definition at line 466 of file RNTupleDescriptor.hxx.

◆ GetFieldRange() [3/4]

RFieldDescriptorRange ROOT::Experimental::RNTupleDescriptor::GetFieldRange ( DescriptorId_t fieldId ) const

inline

Definition at line 471 of file RNTupleDescriptor.hxx.

◆ GetFieldRange() [4/4]

RFieldDescriptorRange ROOT::Experimental::RNTupleDescriptor::GetFieldRange	(	DescriptorId_t	fieldId,
		const std::function< bool(DescriptorId_t, DescriptorId_t)> &	comparator
	)		const

inline

Definition at line 474 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 699 of file RNTupleDescriptor.cxx.

◆ GetFooterSize()

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

inline

Definition at line 449 of file RNTupleDescriptor.hxx.

◆ GetGroupUuid()

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

inline

Definition at line 505 of file RNTupleDescriptor.hxx.

◆ GetHeaderSize()

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

inline

Definition at line 446 of file RNTupleDescriptor.hxx.

◆ GetName()

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

inline

Definition at line 497 of file RNTupleDescriptor.hxx.

◆ GetNClusters()

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

inline

Definition at line 509 of file RNTupleDescriptor.hxx.

◆ GetNColumns()

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

inline

Definition at line 508 of file RNTupleDescriptor.hxx.

◆ GetNElements()

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

Definition at line 656 of file RNTupleDescriptor.cxx.

◆ GetNEntries()

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

Definition at line 647 of file RNTupleDescriptor.cxx.

◆ GetNFields()

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

inline

Definition at line 507 of file RNTupleDescriptor.hxx.

◆ GetOwnUuid()

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

inline

Definition at line 504 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 685 of file RNTupleDescriptor.cxx.

◆ GetTimeStampData()

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

inline

Definition at line 501 of file RNTupleDescriptor.hxx.

◆ GetTimeStampWritten()

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

inline

Definition at line 502 of file RNTupleDescriptor.hxx.

◆ GetTopLevelFields() [1/2]

RFieldDescriptorRange ROOT::Experimental::RNTupleDescriptor::GetTopLevelFields ( ) const

inline

Definition at line 479 of file RNTupleDescriptor.hxx.

◆ GetTopLevelFields() [2/2]

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

inline

Definition at line 482 of file RNTupleDescriptor.hxx.

◆ GetVersion()

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

inline

Definition at line 503 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 635 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 535 of file RNTupleDescriptor.cxx.

◆ PrintInfo()

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

Definition at line 98 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 587 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 551 of file RNTupleDescriptor.cxx.

Friends And Related Symbol Documentation

◆ RNTupleDescriptorBuilder

friend class RNTupleDescriptorBuilder

friend

Definition at line 280 of file RNTupleDescriptor.hxx.

Member Data Documentation

◆ fAuthor

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

private

The origin of the data.

Definition at line 288 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 307 of file RNTupleDescriptor.hxx.

◆ fColumnDescriptors

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

private

Definition at line 304 of file RNTupleDescriptor.hxx.

◆ fCustodian

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

private

The current responsible for storing the data.

Definition at line 290 of file RNTupleDescriptor.hxx.

◆ fDescription

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

private

Free text from the user.

Definition at line 286 of file RNTupleDescriptor.hxx.

◆ fFieldDescriptors

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

private

Definition at line 303 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 301 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 284 of file RNTupleDescriptor.hxx.

◆ fOwnUuid

RNTupleUuid ROOT::Experimental::RNTupleDescriptor::fOwnUuid

private

Every NTuple gets a unique identifier.

Definition at line 298 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 292 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 294 of file RNTupleDescriptor.hxx.

◆ fVersion

RNTupleVersion ROOT::Experimental::RNTupleDescriptor::fVersion

private

The version evolves with the ntuple summary meta-data.

Definition at line 296 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 420 of file RNTupleDescriptor.hxx.

◆ kFrameVersionMin

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

staticconstexpr

Definition at line 421 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 425 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 423 of file RNTupleDescriptor.hxx.

Libraries for ROOT::Experimental::RNTupleDescriptor:

[legend]

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

tree/ntuple/v7/inc/ROOT/RNTupleDescriptor.hxx
tree/ntuple/v7/src/RNTupleDescriptor.cxx
tree/ntuple/v7/src/RNTupleDescriptorFmt.cxx

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Attributes

Friends

Constructor & Destructor Documentation

◆ RNTupleDescriptor() [1/3]

◆ RNTupleDescriptor() [2/3]

◆ RNTupleDescriptor() [3/3]

Member Function Documentation

◆ FindClusterId()

◆ FindColumnId()

◆ FindFieldId() [1/2]

◆ FindFieldId() [2/2]

◆ FindNextClusterId()

◆ FindPrevClusterId()

◆ GenerateModel()

◆ GetAuthor()

◆ GetClusterDescriptor()

◆ GetColumnDescriptor()

◆ GetColumnRange() [1/2]

◆ GetColumnRange() [2/2]

◆ GetCustodian()

◆ GetDescription()

◆ GetFieldDescriptor()

◆ GetFieldRange() [1/4]

◆ GetFieldRange() [2/4]

◆ GetFieldRange() [3/4]

◆ GetFieldRange() [4/4]

◆ GetFieldZeroId()

◆ GetFooterSize()

◆ GetGroupUuid()

◆ GetHeaderSize()

◆ GetName()

◆ GetNClusters()

◆ GetNColumns()

◆ GetNElements()

◆ GetNEntries()

◆ GetNFields()

◆ GetOwnUuid()

◆ GetQualifiedFieldName()

◆ GetTimeStampData()

◆ GetTimeStampWritten()

◆ GetTopLevelFields() [1/2]

◆ GetTopLevelFields() [2/2]

◆ GetVersion()

◆ LocateMetadata()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ PrintInfo()

◆ SerializeFooter()

◆ SerializeHeader()

Friends And Related Symbol Documentation

◆ RNTupleDescriptorBuilder

Member Data Documentation

◆ fAuthor

◆ fClusterDescriptors

◆ fColumnDescriptors

◆ fCustodian

◆ fDescription

◆ fFieldDescriptors

◆ fGroupUuid

◆ fName

◆ fOwnUuid

◆ fTimeStampData

◆ fTimeStampWritten

◆ fVersion

◆ kFrameVersionCurrent

◆ kFrameVersionMin

◆ kNBytesPostscript

◆ kNBytesPreamble