Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
ROOT::Experimental::RNTupleReader Class Reference

Reads RNTuple data from storage.

The RNTupleReader provides access to data stored in the RNTuple binary format as C++ objects, using an RNTupleModel. It infers this model from the RNTuple's on-disk metadata, or uses a model imposed by the user. The latter case allows users to read into a specialized RNTuple model that covers only a subset of the fields in the RNTuple. The RNTuple model is used when reading complete entries through LoadEntry(). Individual fields can be read as well by instantiating a tree view.

#include <iostream>
auto reader = RNTupleReader::Open("myNTuple", "some/file.root");
std::cout << "myNTuple has " << reader->GetNEntries() << " entries\n";
Reads RNTuple data from storage.
static std::unique_ptr< RNTupleReader > Open(std::string_view ntupleName, std::string_view storage, const ROOT::RNTupleReadOptions &options=ROOT::RNTupleReadOptions())
Open an RNTuple for reading.

Definition at line 72 of file RNTupleReader.hxx.

Classes

class  RIterator
 

Public Member Functions

 ~RNTupleReader ()
 
RIterator begin ()
 
std::unique_ptr< RNTupleReaderClone ()
 
std::unique_ptr< ROOT::REntryCreateEntry ()
 
void EnableMetrics ()
 Enable performance measurements (decompression time, bytes read from storage, etc.)
 
RIterator end ()
 
ROOT::RNTupleCollectionView GetCollectionView (ROOT::DescriptorId_t fieldId)
 
ROOT::RNTupleCollectionView GetCollectionView (std::string_view fieldName)
 Raises an exception if:
 
const ROOT::RNTupleDescriptorGetDescriptor ()
 Returns a cached copy of the page source descriptor.
 
template<typename T >
ROOT::RNTupleDirectAccessView< T > GetDirectAccessView (ROOT::DescriptorId_t fieldId)
 
template<typename T >
ROOT::RNTupleDirectAccessView< T > GetDirectAccessView (std::string_view fieldName)
 
ROOT::RNTupleGlobalRange GetEntryRange ()
 Returns an iterator over the entry indices of the RNTuple.
 
const Detail::RNTupleMetricsGetMetrics () const
 
const ROOT::RNTupleModelGetModel ()
 
ROOT::NTupleSize_t GetNEntries () const
 
template<typename T >
ROOT::RNTupleView< T > GetView (ROOT::DescriptorId_t fieldId)
 
template<typename T >
ROOT::RNTupleView< T > GetView (ROOT::DescriptorId_t fieldId, std::shared_ptr< T > objPtr)
 
template<typename T >
ROOT::RNTupleView< T > GetView (ROOT::DescriptorId_t fieldId, T *rawPtr)
 
template<typename T >
ROOT::RNTupleView< T > GetView (std::string_view fieldName)
 Provides access to an individual (sub)field, e.g.
 
template<typename T >
ROOT::RNTupleView< T > GetView (std::string_view fieldName, std::shared_ptr< T > objPtr)
 
template<typename T >
ROOT::RNTupleView< T > GetView (std::string_view fieldName, T *rawPtr)
 
void LoadEntry (ROOT::NTupleSize_t index)
 Fills the default entry of the model.
 
void LoadEntry (ROOT::NTupleSize_t index, ROOT::REntry &entry)
 Fills a user provided entry after checking that the entry has been instantiated from the RNTuple model.
 
void PrintInfo (const ENTupleInfo what=ENTupleInfo::kSummary, std::ostream &output=std::cout) const
 Prints a detailed summary of the RNTuple, including a list of fields.
 
void Show (ROOT::NTupleSize_t index, std::ostream &output=std::cout)
 Shows the values of the i-th entry/row, starting with 0 for the first entry.
 

Static Public Member Functions

static std::unique_ptr< RNTupleReaderOpen (const RNTuple &ntuple, const ROOT::RNTupleReadOptions &options=ROOT::RNTupleReadOptions())
 
static std::unique_ptr< RNTupleReaderOpen (const ROOT::RNTupleDescriptor::RCreateModelOptions &createModelOpts, const RNTuple &ntuple, const ROOT::RNTupleReadOptions &options=ROOT::RNTupleReadOptions())
 
static std::unique_ptr< RNTupleReaderOpen (const ROOT::RNTupleDescriptor::RCreateModelOptions &createModelOpts, std::string_view ntupleName, std::string_view storage, const ROOT::RNTupleReadOptions &options=ROOT::RNTupleReadOptions())
 The caller imposes the way the model is reconstructed.
 
static std::unique_ptr< RNTupleReaderOpen (std::string_view ntupleName, std::string_view storage, const ROOT::RNTupleReadOptions &options=ROOT::RNTupleReadOptions())
 Open an RNTuple for reading.
 
static std::unique_ptr< RNTupleReaderOpen (std::unique_ptr< ROOT::RNTupleModel > model, const RNTuple &ntuple, const ROOT::RNTupleReadOptions &options=ROOT::RNTupleReadOptions())
 
static std::unique_ptr< RNTupleReaderOpen (std::unique_ptr< ROOT::RNTupleModel > model, std::string_view ntupleName, std::string_view storage, const ROOT::RNTupleReadOptions &options=ROOT::RNTupleReadOptions())
 The caller imposes a model, which must be compatible with the model found in the data on storage.
 

Private Member Functions

 RNTupleReader (std::unique_ptr< Internal::RPageSource > source, const ROOT::RNTupleReadOptions &options)
 The model is generated from the RNTuple metadata on storage.
 
 RNTupleReader (std::unique_ptr< ROOT::RNTupleModel > model, std::unique_ptr< Internal::RPageSource > source, const ROOT::RNTupleReadOptions &options)
 
void ConnectModel (ROOT::RNTupleModel &model)
 
RNTupleReaderGetDisplayReader ()
 
void InitPageSource (bool enableMetrics)
 
ROOT::DescriptorId_t RetrieveFieldId (std::string_view fieldName) const
 

Private Attributes

std::optional< ROOT::RNTupleDescriptorfCachedDescriptor
 The RNTuple descriptor in the page source is protected by a read-write lock.
 
std::optional< ROOT::RNTupleDescriptor::RCreateModelOptionsfCreateModelOptions
 If not nullopt, these will be used when creating the model.
 
std::unique_ptr< RNTupleReaderfDisplayReader
 We use a dedicated on-demand reader for Show().
 
Detail::RNTupleMetrics fMetrics
 
std::unique_ptr< ROOT::RNTupleModelfModel
 Needs to be destructed before fSource.
 
std::unique_ptr< Internal::RPageSourcefSource
 
std::unique_ptr< Internal::RPageStorage::RTaskSchedulerfUnzipTasks
 Set as the page source's scheduler for parallel page decompression if implicit multi-threading (IMT) is on.
 

#include <ROOT/RNTupleReader.hxx>

Constructor & Destructor Documentation

◆ RNTupleReader() [1/2]

ROOT::Experimental::RNTupleReader::RNTupleReader ( std::unique_ptr< ROOT::RNTupleModel > model,
std::unique_ptr< Internal::RPageSource > source,
const ROOT::RNTupleReadOptions & options )
private

Definition at line 60 of file RNTupleReader.cxx.

◆ RNTupleReader() [2/2]

ROOT::Experimental::RNTupleReader::RNTupleReader ( std::unique_ptr< Internal::RPageSource > source,
const ROOT::RNTupleReadOptions & options )
explicitprivate

The model is generated from the RNTuple metadata on storage.

Definition at line 75 of file RNTupleReader.cxx.

◆ ~RNTupleReader()

ROOT::Experimental::RNTupleReader::~RNTupleReader ( )
default

Member Function Documentation

◆ begin()

RIterator ROOT::Experimental::RNTupleReader::begin ( )
inline

Definition at line 358 of file RNTupleReader.hxx.

◆ Clone()

std::unique_ptr< RNTupleReader > ROOT::Experimental::RNTupleReader::Clone ( )
inline

Definition at line 174 of file RNTupleReader.hxx.

◆ ConnectModel()

void ROOT::Experimental::RNTupleReader::ConnectModel ( ROOT::RNTupleModel & model)
private

Definition at line 27 of file RNTupleReader.cxx.

◆ CreateEntry()

std::unique_ptr< ROOT::REntry > ROOT::Experimental::RNTupleReader::CreateEntry ( )

Definition at line 146 of file RNTupleReader.cxx.

◆ EnableMetrics()

void ROOT::Experimental::RNTupleReader::EnableMetrics ( )
inline

Enable performance measurements (decompression time, bytes read from storage, etc.)

Example: inspect the reader metrics after loading every entry

#include <iostream>
auto ntuple = RNTupleReader::Open("myNTuple", "some/file.root");
// metrics must be turned on beforehand
reader->EnableMetrics();
for (auto i : ntuple->GetEntryRange()) {
reader->LoadEntry(i);
}
ROOT::RNTupleGlobalRange GetEntryRange()
Returns an iterator over the entry indices of the RNTuple.
ENTupleInfo
Listing of the different options that can be printed by RNTupleReader::GetInfo()

Definition at line 380 of file RNTupleReader.hxx.

◆ end()

RIterator ROOT::Experimental::RNTupleReader::end ( )
inline

Definition at line 359 of file RNTupleReader.hxx.

◆ GetCollectionView() [1/2]

ROOT::RNTupleCollectionView ROOT::Experimental::RNTupleReader::GetCollectionView ( ROOT::DescriptorId_t fieldId)
inline

Definition at line 353 of file RNTupleReader.hxx.

◆ GetCollectionView() [2/2]

ROOT::RNTupleCollectionView ROOT::Experimental::RNTupleReader::GetCollectionView ( std::string_view fieldName)
inline

Raises an exception if:

  • there is no field with the given name or,
  • the field is not a collection

Definition at line 343 of file RNTupleReader.hxx.

◆ GetDescriptor()

const ROOT::RNTupleDescriptor & ROOT::Experimental::RNTupleReader::GetDescriptor ( )

Returns a cached copy of the page source descriptor.

The returned pointer remains valid until the next call to LoadEntry() or to any of the views returned from the reader.

Definition at line 251 of file RNTupleReader.cxx.

◆ GetDirectAccessView() [1/2]

template<typename T >
ROOT::RNTupleDirectAccessView< T > ROOT::Experimental::RNTupleReader::GetDirectAccessView ( ROOT::DescriptorId_t fieldId)
inline

Definition at line 333 of file RNTupleReader.hxx.

◆ GetDirectAccessView() [2/2]

template<typename T >
ROOT::RNTupleDirectAccessView< T > ROOT::Experimental::RNTupleReader::GetDirectAccessView ( std::string_view fieldName)
inline

Definition at line 327 of file RNTupleReader.hxx.

◆ GetDisplayReader()

ROOT::Experimental::RNTupleReader * ROOT::Experimental::RNTupleReader::GetDisplayReader ( )
private

Definition at line 222 of file RNTupleReader.cxx.

◆ GetEntryRange()

ROOT::RNTupleGlobalRange ROOT::Experimental::RNTupleReader::GetEntryRange ( )
inline

Returns an iterator over the entry indices of the RNTuple.

Example: iterate over all entries and print each entry in JSON format

using ROOT::Experimental::ENTupleShowFormat;
#include <iostream>
auto reader = RNTupleReader::Open("myNTuple", "some/file.root");
for (auto i : ntuple->GetEntryRange()) {
reader->Show(i);
}

Definition at line 261 of file RNTupleReader.hxx.

◆ GetMetrics()

const Detail::RNTupleMetrics & ROOT::Experimental::RNTupleReader::GetMetrics ( ) const
inline

Definition at line 381 of file RNTupleReader.hxx.

◆ GetModel()

const ROOT::RNTupleModel & ROOT::Experimental::RNTupleReader::GetModel ( )

Definition at line 136 of file RNTupleReader.cxx.

◆ GetNEntries()

ROOT::NTupleSize_t ROOT::Experimental::RNTupleReader::GetNEntries ( ) const
inline

Definition at line 182 of file RNTupleReader.hxx.

◆ GetView() [1/6]

template<typename T >
ROOT::RNTupleView< T > ROOT::Experimental::RNTupleReader::GetView ( ROOT::DescriptorId_t fieldId)
inline

Definition at line 303 of file RNTupleReader.hxx.

◆ GetView() [2/6]

template<typename T >
ROOT::RNTupleView< T > ROOT::Experimental::RNTupleReader::GetView ( ROOT::DescriptorId_t fieldId,
std::shared_ptr< T > objPtr )
inline

Definition at line 311 of file RNTupleReader.hxx.

◆ GetView() [3/6]

template<typename T >
ROOT::RNTupleView< T > ROOT::Experimental::RNTupleReader::GetView ( ROOT::DescriptorId_t fieldId,
T * rawPtr )
inline

Definition at line 319 of file RNTupleReader.hxx.

◆ GetView() [4/6]

template<typename T >
ROOT::RNTupleView< T > ROOT::Experimental::RNTupleReader::GetView ( std::string_view fieldName)
inline

Provides access to an individual (sub)field, e.g.

GetView<Particle>("particle"), GetView<double>("particle.pt") or GetView<std::vector<Particle>>("particles"). It is possible to directly get the size of a collection (without reading the collection itself) using RNTupleCardinality: GetView<ROOT::RNTupleCardinality<std::uint64_t>>("particles").

Raises an exception if there is no field with the given name.

Example: iterate over a field named "pt" of type float

#include <iostream>
auto reader = RNTupleReader::Open("myNTuple", "some/file.root");
auto pt = reader->GetView<float>("pt");
for (auto i : reader->GetEntryRange()) {
std::cout << i << ": " << pt(i) << "\n";
}
TPaveText * pt

Definition at line 285 of file RNTupleReader.hxx.

◆ GetView() [5/6]

template<typename T >
ROOT::RNTupleView< T > ROOT::Experimental::RNTupleReader::GetView ( std::string_view fieldName,
std::shared_ptr< T > objPtr )
inline

Definition at line 291 of file RNTupleReader.hxx.

◆ GetView() [6/6]

template<typename T >
ROOT::RNTupleView< T > ROOT::Experimental::RNTupleReader::GetView ( std::string_view fieldName,
T * rawPtr )
inline

Definition at line 297 of file RNTupleReader.hxx.

◆ InitPageSource()

void ROOT::Experimental::RNTupleReader::InitPageSource ( bool enableMetrics)
private

Definition at line 45 of file RNTupleReader.cxx.

◆ LoadEntry() [1/2]

void ROOT::Experimental::RNTupleReader::LoadEntry ( ROOT::NTupleSize_t index)
inline

Fills the default entry of the model.

Raises an exception when index is greater than the number of entries present in the RNTuple

Definition at line 227 of file RNTupleReader.hxx.

◆ LoadEntry() [2/2]

void ROOT::Experimental::RNTupleReader::LoadEntry ( ROOT::NTupleSize_t index,
ROOT::REntry & entry )
inline

Fills a user provided entry after checking that the entry has been instantiated from the RNTuple model.

Definition at line 238 of file RNTupleReader.hxx.

◆ Open() [1/6]

std::unique_ptr< ROOT::Experimental::RNTupleReader > ROOT::Experimental::RNTupleReader::Open ( const RNTuple & ntuple,
const ROOT::RNTupleReadOptions & options = ROOT::RNTupleReadOptions() )
static

Definition at line 101 of file RNTupleReader.cxx.

◆ Open() [2/6]

std::unique_ptr< ROOT::Experimental::RNTupleReader > ROOT::Experimental::RNTupleReader::Open ( const ROOT::RNTupleDescriptor::RCreateModelOptions & createModelOpts,
const RNTuple & ntuple,
const ROOT::RNTupleReadOptions & options = ROOT::RNTupleReadOptions() )
static

Definition at line 127 of file RNTupleReader.cxx.

◆ Open() [3/6]

std::unique_ptr< ROOT::Experimental::RNTupleReader > ROOT::Experimental::RNTupleReader::Open ( const ROOT::RNTupleDescriptor::RCreateModelOptions & createModelOpts,
std::string_view ntupleName,
std::string_view storage,
const ROOT::RNTupleReadOptions & options = ROOT::RNTupleReadOptions() )
static

The caller imposes the way the model is reconstructed.

Definition at line 116 of file RNTupleReader.cxx.

◆ Open() [4/6]

std::unique_ptr< ROOT::Experimental::RNTupleReader > ROOT::Experimental::RNTupleReader::Open ( std::string_view ntupleName,
std::string_view storage,
const ROOT::RNTupleReadOptions & options = ROOT::RNTupleReadOptions() )
static

Open an RNTuple for reading.

Throws an RException if there is no RNTuple with the given name.

Example: open an RNTuple and print the number of entries

#include <iostream>
auto reader = RNTupleReader::Open("myNTuple", "some/file.root");
std::cout << "myNTuple has " << reader->GetNEntries() << " entries\n";

Definition at line 93 of file RNTupleReader.cxx.

◆ Open() [5/6]

std::unique_ptr< ROOT::Experimental::RNTupleReader > ROOT::Experimental::RNTupleReader::Open ( std::unique_ptr< ROOT::RNTupleModel > model,
const RNTuple & ntuple,
const ROOT::RNTupleReadOptions & options = ROOT::RNTupleReadOptions() )
static

Definition at line 108 of file RNTupleReader.cxx.

◆ Open() [6/6]

std::unique_ptr< ROOT::Experimental::RNTupleReader > ROOT::Experimental::RNTupleReader::Open ( std::unique_ptr< ROOT::RNTupleModel > model,
std::string_view ntupleName,
std::string_view storage,
const ROOT::RNTupleReadOptions & options = ROOT::RNTupleReadOptions() )
static

The caller imposes a model, which must be compatible with the model found in the data on storage.

Definition at line 85 of file RNTupleReader.cxx.

◆ PrintInfo()

void ROOT::Experimental::RNTupleReader::PrintInfo ( const ENTupleInfo what = ENTupleInfo::kSummary,
std::ostream & output = std::cout ) const

Prints a detailed summary of the RNTuple, including a list of fields.

Example: print summary information to stdout

#include <iostream>
auto reader = RNTupleReader::Open("myNTuple", "some/file.root");
reader->PrintInfo();
// or, equivalently:
reader->PrintInfo(ENTupleInfo::kSummary, std::cout);

Example: print detailed column storage data to stderr

#include <iostream>
auto reader = RNTupleReader::Open("myNTuple", "some/file.root");
reader->PrintInfo(ENTupleInfo::kStorageDetails, std::cerr);

For use of ENTupleInfo::kMetrics, see EnableMetrics.

Definition at line 151 of file RNTupleReader.cxx.

◆ RetrieveFieldId()

ROOT::DescriptorId_t ROOT::Experimental::RNTupleReader::RetrieveFieldId ( std::string_view fieldName) const
private

Definition at line 259 of file RNTupleReader.cxx.

◆ Show()

void ROOT::Experimental::RNTupleReader::Show ( ROOT::NTupleSize_t index,
std::ostream & output = std::cout )

Shows the values of the i-th entry/row, starting with 0 for the first entry.

By default, prints the output in JSON format. Uses the visitor pattern to traverse through each field of the given entry.

Definition at line 229 of file RNTupleReader.cxx.

Member Data Documentation

◆ fCachedDescriptor

std::optional<ROOT::RNTupleDescriptor> ROOT::Experimental::RNTupleReader::fCachedDescriptor
private

The RNTuple descriptor in the page source is protected by a read-write lock.

We don't expose that to the users of RNTupleReader::GetDescriptor(). Instead, if descriptor information is needed, we clone the descriptor. Using the descriptor's generation number, we know if the cached descriptor is stale. Retrieving descriptor data from an RNTupleReader is supposed to be for testing and information purposes, not on a hot code path.

Definition at line 90 of file RNTupleReader.hxx.

◆ fCreateModelOptions

std::optional<ROOT::RNTupleDescriptor::RCreateModelOptions> ROOT::Experimental::RNTupleReader::fCreateModelOptions
private

If not nullopt, these will be used when creating the model.

Definition at line 93 of file RNTupleReader.hxx.

◆ fDisplayReader

std::unique_ptr<RNTupleReader> ROOT::Experimental::RNTupleReader::fDisplayReader
private

We use a dedicated on-demand reader for Show().

Printing data uses all the fields from the full model even if the analysis code uses only a subset of fields. The display reader is a clone of the original reader.

Definition at line 84 of file RNTupleReader.hxx.

◆ fMetrics

Detail::RNTupleMetrics ROOT::Experimental::RNTupleReader::fMetrics
private

Definition at line 91 of file RNTupleReader.hxx.

◆ fModel

std::unique_ptr<ROOT::RNTupleModel> ROOT::Experimental::RNTupleReader::fModel
private

Needs to be destructed before fSource.

Definition at line 80 of file RNTupleReader.hxx.

◆ fSource

std::unique_ptr<Internal::RPageSource> ROOT::Experimental::RNTupleReader::fSource
private

Definition at line 78 of file RNTupleReader.hxx.

◆ fUnzipTasks

std::unique_ptr<Internal::RPageStorage::RTaskScheduler> ROOT::Experimental::RNTupleReader::fUnzipTasks
private

Set as the page source's scheduler for parallel page decompression if implicit multi-threading (IMT) is on.

Needs to be destructed after the page source is destructed (and thus be declared before)

Definition at line 76 of file RNTupleReader.hxx.

Libraries for ROOT::Experimental::RNTupleReader:

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