The on-storage metadata of an RNTuple.
Represents the on-disk (on storage) information about an RNTuple. The metadata consists of a header, a footer, and potentially multiple page lists. The header carries the RNTuple schema, i.e. the fields and the associated columns and their relationships. The footer carries information about one or several cluster groups and links to their page lists. For every cluster group, a page list envelope stores cluster summaries and page locations. For every cluster, it stores for every column the range of element indexes as well as a list of pages and page locations.
The descriptor provides machine-independent (de-)serialization of headers and footers, and it provides lookup routines for RNTuple 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 envelopes and frames: header, footer, and page list envelopes have a preamble with a type ID and length. Substructures are serialized in frames and have a size and number of items (for list frames). This allows for forward and backward compatibility when the metadata evolves.
Definition at line 649 of file RNTupleDescriptor.hxx.
Classes | |
class | RClusterDescriptorIterable |
Used to loop over all the clusters of an RNTuple (in unspecified order) More... | |
class | RClusterGroupDescriptorIterable |
Used to loop over all the cluster groups of an RNTuple (in unspecified order) More... | |
class | RColumnDescriptorIterable |
Used to loop over a field's associated columns. More... | |
struct | RCreateModelOptions |
Modifiers passed to CreateModel() More... | |
class | RExtraTypeInfoDescriptorIterable |
Used to loop over all the extra type info record of an RNTuple (in unspecified order) More... | |
class | RFieldDescriptorIterable |
Used to loop over a field's child fields. More... | |
class | RHeaderExtension |
Summarizes information about fields and the corresponding columns that were added after the header has been serialized. More... | |
Static Public Attributes | |
static constexpr unsigned int | kFeatureFlagTest = 137 |
Private Member Functions | |
RNTupleDescriptor | CloneSchema () const |
Creates a descriptor containing only the schema information about this RNTuple, i.e. | |
ROOT::DescriptorId_t | FindClusterId (ROOT::NTupleSize_t entryIdx) const |
Private Attributes | |
std::unordered_map< ROOT::DescriptorId_t, RClusterDescriptor > | fClusterDescriptors |
Potentially a subset of all the available clusters. | |
std::unordered_map< ROOT::DescriptorId_t, RClusterGroupDescriptor > | fClusterGroupDescriptors |
std::unordered_map< ROOT::DescriptorId_t, RColumnDescriptor > | fColumnDescriptors |
std::string | fDescription |
Free text from the user. | |
std::vector< RExtraTypeInfoDescriptor > | fExtraTypeInfoDescriptors |
std::set< unsigned int > | fFeatureFlags |
std::unordered_map< ROOT::DescriptorId_t, RFieldDescriptor > | fFieldDescriptors |
ROOT::DescriptorId_t | fFieldZeroId = ROOT::kInvalidDescriptorId |
Set by the descriptor builder. | |
std::uint64_t | fGeneration = 0 |
The generation of the descriptor. | |
std::unique_ptr< RHeaderExtension > | fHeaderExtension |
std::string | fName |
The RNTuple name needs to be unique in a given storage location (file) | |
std::uint64_t | fNClusters = 0 |
Updated by the descriptor builder when the cluster groups are added. | |
std::uint64_t | fNEntries = 0 |
Updated by the descriptor builder when the cluster groups are added. | |
std::uint64_t | fNPhysicalColumns = 0 |
Updated by the descriptor builder when columns are added. | |
std::uint64_t | fOnDiskFooterSize = 0 |
Like fOnDiskHeaderSize, contains both cluster summaries and page locations. | |
std::uint64_t | fOnDiskHeaderSize = 0 |
Set by the descriptor builder when deserialized. | |
std::uint64_t | fOnDiskHeaderXxHash3 = 0 |
Set by the descriptor builder when deserialized. | |
std::vector< ROOT::DescriptorId_t > | fSortedClusterGroupIds |
References cluster groups sorted by entry range and thus allows for binary search. | |
std::uint16_t | fVersionEpoch = 0 |
Set by the descriptor builder when deserialized. | |
std::uint16_t | fVersionMajor = 0 |
Set by the descriptor builder when deserialized. | |
std::uint16_t | fVersionMinor = 0 |
Set by the descriptor builder when deserialized. | |
std::uint16_t | fVersionPatch = 0 |
Set by the descriptor builder when deserialized. | |
Friends | |
RNTupleDescriptor | Internal::CloneDescriptorSchema (const RNTupleDescriptor &desc) |
class | Internal::RNTupleDescriptorBuilder |
#include <ROOT/RNTupleDescriptor.hxx>
|
default |
|
delete |
|
default |
ROOT::RResult< void > ROOT::RNTupleDescriptor::AddClusterGroupDetails | ( | ROOT::DescriptorId_t | clusterGroupId, |
std::vector< RClusterDescriptor > & | clusterDescs ) |
Methods to load and drop cluster group details (cluster IDs and page locations)
Definition at line 650 of file RNTupleDescriptor.cxx.
ROOT::RNTupleDescriptor ROOT::RNTupleDescriptor::Clone | ( | ) | const |
Definition at line 786 of file RNTupleDescriptor.cxx.
|
private |
Creates a descriptor containing only the schema information about this RNTuple, i.e.
all the information needed to create a new RNTuple with the same schema as this one but not necessarily the same clustering. This is used when merging two RNTuples.
Definition at line 761 of file RNTupleDescriptor.cxx.
std::unique_ptr< ROOT::RNTupleModel > ROOT::RNTupleDescriptor::CreateModel | ( | const RCreateModelOptions & | options = RCreateModelOptions() | ) | const |
Re-create the C++ model from the stored metadata.
Definition at line 692 of file RNTupleDescriptor.cxx.
ROOT::RResult< void > ROOT::RNTupleDescriptor::DropClusterGroupDetails | ( | ROOT::DescriptorId_t | clusterGroupId | ) |
Definition at line 678 of file RNTupleDescriptor.cxx.
ROOT::DescriptorId_t ROOT::RNTupleDescriptor::FindClusterId | ( | ROOT::DescriptorId_t | physicalColumnId, |
ROOT::NTupleSize_t | index ) const |
Definition at line 455 of file RNTupleDescriptor.cxx.
|
private |
Definition at line 517 of file RNTupleDescriptor.cxx.
ROOT::DescriptorId_t ROOT::RNTupleDescriptor::FindFieldId | ( | std::string_view | fieldName | ) | const |
Searches for a top-level field.
Definition at line 424 of file RNTupleDescriptor.cxx.
ROOT::DescriptorId_t ROOT::RNTupleDescriptor::FindFieldId | ( | std::string_view | fieldName, |
ROOT::DescriptorId_t | parentId ) const |
Definition at line 380 of file RNTupleDescriptor.cxx.
ROOT::DescriptorId_t ROOT::RNTupleDescriptor::FindLogicalColumnId | ( | ROOT::DescriptorId_t | fieldId, |
std::uint32_t | columnIndex, | ||
std::uint16_t | representationIndex ) const |
Definition at line 429 of file RNTupleDescriptor.cxx.
ROOT::DescriptorId_t ROOT::RNTupleDescriptor::FindNextClusterId | ( | ROOT::DescriptorId_t | clusterId | ) | const |
Definition at line 569 of file RNTupleDescriptor.cxx.
ROOT::DescriptorId_t ROOT::RNTupleDescriptor::FindPhysicalColumnId | ( | ROOT::DescriptorId_t | fieldId, |
std::uint32_t | columnIndex, | ||
std::uint16_t | representationIndex ) const |
Definition at line 444 of file RNTupleDescriptor.cxx.
ROOT::DescriptorId_t ROOT::RNTupleDescriptor::FindPrevClusterId | ( | ROOT::DescriptorId_t | clusterId | ) | const |
Definition at line 580 of file RNTupleDescriptor.cxx.
|
inline |
Definition at line 781 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 777 of file RNTupleDescriptor.hxx.
ROOT::RNTupleDescriptor::RClusterGroupDescriptorIterable ROOT::RNTupleDescriptor::GetClusterGroupIterable | ( | ) | const |
Definition at line 1481 of file RNTupleDescriptor.cxx.
ROOT::RNTupleDescriptor::RClusterDescriptorIterable ROOT::RNTupleDescriptor::GetClusterIterable | ( | ) | const |
Definition at line 1486 of file RNTupleDescriptor.cxx.
|
inline |
Definition at line 773 of file RNTupleDescriptor.hxx.
ROOT::RNTupleDescriptor::RColumnDescriptorIterable ROOT::RNTupleDescriptor::GetColumnIterable | ( | ) | const |
Definition at line 1464 of file RNTupleDescriptor.cxx.
ROOT::RNTupleDescriptor::RColumnDescriptorIterable ROOT::RNTupleDescriptor::GetColumnIterable | ( | const RFieldDescriptor & | fieldDesc | ) | const |
Definition at line 1470 of file RNTupleDescriptor.cxx.
ROOT::RNTupleDescriptor::RColumnDescriptorIterable ROOT::RNTupleDescriptor::GetColumnIterable | ( | ROOT::DescriptorId_t | fieldId | ) | const |
Definition at line 1476 of file RNTupleDescriptor.cxx.
|
inline |
Definition at line 810 of file RNTupleDescriptor.hxx.
ROOT::RNTupleDescriptor::RExtraTypeInfoDescriptorIterable ROOT::RNTupleDescriptor::GetExtraTypeInfoIterable | ( | ) | const |
Definition at line 1491 of file RNTupleDescriptor.cxx.
std::vector< std::uint64_t > ROOT::RNTupleDescriptor::GetFeatureFlags | ( | ) | const |
Definition at line 630 of file RNTupleDescriptor.cxx.
|
inline |
Definition at line 769 of file RNTupleDescriptor.hxx.
ROOT::RNTupleDescriptor::RFieldDescriptorIterable ROOT::RNTupleDescriptor::GetFieldIterable | ( | const RFieldDescriptor & | fieldDesc | ) | const |
Definition at line 1428 of file RNTupleDescriptor.cxx.
ROOT::RNTupleDescriptor::RFieldDescriptorIterable ROOT::RNTupleDescriptor::GetFieldIterable | ( | const RFieldDescriptor & | fieldDesc, |
const std::function< bool(ROOT::DescriptorId_t, ROOT::DescriptorId_t)> & | comparator ) const |
Definition at line 1433 of file RNTupleDescriptor.cxx.
ROOT::RNTupleDescriptor::RFieldDescriptorIterable ROOT::RNTupleDescriptor::GetFieldIterable | ( | ROOT::DescriptorId_t | fieldId | ) | const |
Definition at line 1441 of file RNTupleDescriptor.cxx.
ROOT::RNTupleDescriptor::RFieldDescriptorIterable ROOT::RNTupleDescriptor::GetFieldIterable | ( | ROOT::DescriptorId_t | fieldId, |
const std::function< bool(ROOT::DescriptorId_t, ROOT::DescriptorId_t)> & | comparator ) const |
Definition at line 1446 of file RNTupleDescriptor.cxx.
|
inline |
Definition at line 826 of file RNTupleDescriptor.hxx.
|
inline |
Returns the logical parent of all top-level RNTuple data fields.
Definition at line 825 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 856 of file RNTupleDescriptor.hxx.
|
inline |
Return header extension information; if the descriptor does not have a header extension, return nullptr
Definition at line 849 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 817 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 809 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 815 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 816 of file RNTupleDescriptor.hxx.
ROOT::NTupleSize_t ROOT::RNTupleDescriptor::GetNElements | ( | ROOT::DescriptorId_t | physicalColumnId | ) | const |
Definition at line 349 of file RNTupleDescriptor.cxx.
|
inline |
We know the number of entries from adding the cluster summaries.
Definition at line 821 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 818 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 812 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 813 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 814 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 767 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 766 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 765 of file RNTupleDescriptor.hxx.
std::string ROOT::RNTupleDescriptor::GetQualifiedFieldName | ( | ROOT::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 399 of file RNTupleDescriptor.cxx.
ROOT::RNTupleDescriptor::RFieldDescriptorIterable ROOT::RNTupleDescriptor::GetTopLevelFields | ( | ) | const |
Definition at line 1453 of file RNTupleDescriptor.cxx.
ROOT::RNTupleDescriptor::RFieldDescriptorIterable ROOT::RNTupleDescriptor::GetTopLevelFields | ( | const std::function< bool(ROOT::DescriptorId_t, ROOT::DescriptorId_t)> & | comparator | ) | const |
Definition at line 1458 of file RNTupleDescriptor.cxx.
std::string ROOT::RNTupleDescriptor::GetTypeNameForComparison | ( | const RFieldDescriptor & | fieldDesc | ) | const |
Adjust the type name of the passed RFieldDescriptor for comparison with another renormalized type name.
Definition at line 411 of file RNTupleDescriptor.cxx.
Definition at line 845 of file RNTupleDescriptor.hxx.
|
inline |
Definition at line 857 of file RNTupleDescriptor.hxx.
|
delete |
|
default |
bool ROOT::RNTupleDescriptor::operator== | ( | const RNTupleDescriptor & | other | ) | const |
Definition at line 334 of file RNTupleDescriptor.cxx.
void ROOT::RNTupleDescriptor::PrintInfo | ( | std::ostream & | output | ) | const |
Definition at line 79 of file RNTupleDescriptorFmt.cxx.
|
friend |
|
friend |
Definition at line 650 of file RNTupleDescriptor.hxx.
|
private |
Potentially a subset of all the available clusters.
Definition at line 703 of file RNTupleDescriptor.hxx.
|
private |
Definition at line 697 of file RNTupleDescriptor.hxx.
|
private |
Definition at line 668 of file RNTupleDescriptor.hxx.
|
private |
Free text from the user.
Definition at line 660 of file RNTupleDescriptor.hxx.
|
private |
Definition at line 670 of file RNTupleDescriptor.hxx.
|
private |
Definition at line 666 of file RNTupleDescriptor.hxx.
|
private |
Definition at line 667 of file RNTupleDescriptor.hxx.
|
private |
Set by the descriptor builder.
Definition at line 662 of file RNTupleDescriptor.hxx.
|
private |
The generation of the descriptor.
Once constructed by an RNTupleDescriptorBuilder, the descriptor is mostly immutable except for the set of active page locations. During the lifetime of the descriptor, page location information for clusters can be added or removed. When this happens, the generation should be increased, so that users of the descriptor know that the information changed. The generation is increased, e.g., by the page source's exclusive lock guard around the descriptor. It is used, e.g., by the descriptor cache in RNTupleReader.
Definition at line 695 of file RNTupleDescriptor.hxx.
|
private |
Definition at line 671 of file RNTupleDescriptor.hxx.
|
private |
The RNTuple name needs to be unique in a given storage location (file)
Definition at line 658 of file RNTupleDescriptor.hxx.
|
private |
Updated by the descriptor builder when the cluster groups are added.
Definition at line 686 of file RNTupleDescriptor.hxx.
|
private |
Updated by the descriptor builder when the cluster groups are added.
Definition at line 685 of file RNTupleDescriptor.hxx.
|
private |
Updated by the descriptor builder when columns are added.
Definition at line 664 of file RNTupleDescriptor.hxx.
|
private |
Like fOnDiskHeaderSize, contains both cluster summaries and page locations.
Definition at line 683 of file RNTupleDescriptor.hxx.
|
private |
Set by the descriptor builder when deserialized.
Definition at line 681 of file RNTupleDescriptor.hxx.
|
private |
Set by the descriptor builder when deserialized.
Definition at line 682 of file RNTupleDescriptor.hxx.
|
private |
References cluster groups sorted by entry range and thus allows for binary search.
Note that this list is empty during the descriptor building process and will only be created when the final descriptor is extracted from the builder.
Definition at line 701 of file RNTupleDescriptor.hxx.
|
private |
Set by the descriptor builder when deserialized.
Definition at line 676 of file RNTupleDescriptor.hxx.
|
private |
Set by the descriptor builder when deserialized.
Definition at line 677 of file RNTupleDescriptor.hxx.
|
private |
Set by the descriptor builder when deserialized.
Definition at line 678 of file RNTupleDescriptor.hxx.
|
private |
Set by the descriptor builder when deserialized.
Definition at line 679 of file RNTupleDescriptor.hxx.
Definition at line 714 of file RNTupleDescriptor.hxx.