An RNTuple that is used to read data from storage.

An input ntuple provides data from storage as C++ objects. The ntuple model can be created from the data on storage or it can be imposed by the user. The latter case allows users to read into a specialized ntuple model that covers only a subset of the fields in the ntuple. The ntuple model is used when reading complete entries. Individual fields can be read as well by instantiating a tree view.

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

Definition at line 71 of file RNTupleReader.hxx.

Classes
class	RIterator

Public Member Functions
	~RNTupleReader ()

RIterator	begin ()

std::unique_ptr< RNTupleReader >	Clone ()

std::unique_ptr< REntry >	CreateEntry ()

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

RIterator	end ()

RNTupleCollectionView	GetCollectionView (ROOT::DescriptorId_t fieldId)

RNTupleCollectionView	GetCollectionView (std::string_view fieldName)
	Raises an exception if:

const ROOT::RNTupleDescriptor &	GetDescriptor ()
	Returns a cached copy of the page source descriptor.

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

template<typename T >
RNTupleDirectAccessView< T >	GetDirectAccessView (std::string_view fieldName)

ROOT::RNTupleGlobalRange	GetEntryRange ()
	Returns an iterator over the entry indices of the RNTuple.

const Detail::RNTupleMetrics &	GetMetrics () const

const RNTupleModel &	GetModel ()

ROOT::NTupleSize_t	GetNEntries () const

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

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

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

template<typename T >
RNTupleView< T >	GetView (std::string_view fieldName)
	Provides access to an individual field that can contain either a scalar value or a collection, e.g.

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

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

void	LoadEntry (ROOT::NTupleSize_t index)
	Analogous to Fill(), fills the default entry of the model.

void	LoadEntry (ROOT::NTupleSize_t index, REntry &entry)
	Fills a user provided entry after checking that the entry has been instantiated from the ntuple model.

void	PrintInfo (const ENTupleInfo what=ENTupleInfo::kSummary, std::ostream &output=std::cout) const
	Prints a detailed summary of the ntuple, 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< RNTupleReader >	Open (const RNTuple &ntuple, const ROOT::RNTupleReadOptions &options=ROOT::RNTupleReadOptions())

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

static std::unique_ptr< RNTupleReader >	Open (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< RNTupleReader >	Open (std::string_view ntupleName, std::string_view storage, const ROOT::RNTupleReadOptions &options=ROOT::RNTupleReadOptions())
	Open an RNTuple for reading.

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

static std::unique_ptr< RNTupleReader >	Open (std::unique_ptr< 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 ntuple metadata on storage.

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

void	ConnectModel (RNTupleModel &model)

RNTupleReader *	GetDisplayReader ()

void	InitPageSource (bool enableMetrics)

ROOT::DescriptorId_t	RetrieveFieldId (std::string_view fieldName) const

Private Attributes
std::optional< ROOT::RNTupleDescriptor >	fCachedDescriptor
	The ntuple descriptor in the page source is protected by a read-write lock.

std::optional< ROOT::RNTupleDescriptor::RCreateModelOptions >	fCreateModelOptions
	If not nullopt, these will used when creating the model.

std::unique_ptr< RNTupleReader >	fDisplayReader
	We use a dedicated on-demand reader for Show() and Scan().

Detail::RNTupleMetrics	fMetrics

std::unique_ptr< RNTupleModel >	fModel
	Needs to be destructed before fSource.

std::unique_ptr< Internal::RPageSource >	fSource

std::unique_ptr< Internal::RPageStorage::RTaskScheduler >	fUnzipTasks
	Set as the page source's scheduler for parallel page decompression if IMT is on Needs to be destructed after the pages source is destructed (an thus be declared before)

#include <ROOT/RNTupleReader.hxx>

Constructor & Destructor Documentation

◆ RNTupleReader() [1/2]

ROOT::Experimental::RNTupleReader::RNTupleReader	(	std::unique_ptr< 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 ntuple 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 356 of file RNTupleReader.hxx.

◆ Clone()

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

inline

Definition at line 173 of file RNTupleReader.hxx.

◆ ConnectModel()

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

private

Definition at line 27 of file RNTupleReader.cxx.

◆ CreateEntry()

std::unique_ptr< ROOT::Experimental::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 <ROOT/RNTupleReader.hxx>
using ROOT::Experimental::ENTupleInfo;
using ROOT::Experimental::RNTupleReader;
 
#include <iostream>
 
auto ntuple = RNTupleReader::Open("myNTuple", "some/file.root");
// metrics must be turned on beforehand
ntuple->EnableMetrics();
 
for (auto i : ntuple->GetEntryRange()) {
   ntuple->LoadEntry(i);
}
ntuple->PrintInfo(ENTupleInfo::kMetrics);

Definition at line 378 of file RNTupleReader.hxx.

◆ end()

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

inline

Definition at line 357 of file RNTupleReader.hxx.

◆ GetCollectionView() [1/2]

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

inline

Definition at line 351 of file RNTupleReader.hxx.

◆ GetCollectionView() [2/2]

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 341 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 >

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

inline

Definition at line 331 of file RNTupleReader.hxx.

◆ GetDirectAccessView() [2/2]

template<typename T >

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

inline

Definition at line 325 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

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

Definition at line 260 of file RNTupleReader.hxx.

◆ GetMetrics()

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

inline

Definition at line 379 of file RNTupleReader.hxx.

◆ GetModel()

const ROOT::Experimental::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 181 of file RNTupleReader.hxx.

◆ GetView() [1/6]

template<typename T >

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

inline

Definition at line 301 of file RNTupleReader.hxx.

◆ GetView() [2/6]

template<typename T >

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

inline

Definition at line 309 of file RNTupleReader.hxx.

◆ GetView() [3/6]

template<typename T >

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

inline

Definition at line 317 of file RNTupleReader.hxx.

◆ GetView() [4/6]

template<typename T >

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

inline

Provides access to an individual field that can contain either a scalar value or a collection, e.g.

GetView<double>("particles.pt") or GetView<std::vector<double>>("particle"). It can as well be the index field of a collection itself, like GetView<ROOT::NTupleSize_t>("particle").

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

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

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

Definition at line 283 of file RNTupleReader.hxx.

◆ GetView() [5/6]

template<typename T >

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

inline

Definition at line 289 of file RNTupleReader.hxx.

◆ GetView() [6/6]

template<typename T >

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

inline

Definition at line 295 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

Analogous to Fill(), fills the default entry of the model.

Returns false at the end of the ntuple. On I/O errors, raises an exception.

Definition at line 226 of file RNTupleReader.hxx.

◆ LoadEntry() [2/2]

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

inline

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

Definition at line 237 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 <ROOT/RNTupleReader.hxx>
using ROOT::Experimental::RNTupleReader;
 
#include <iostream>
 
auto ntuple = RNTupleReader::Open("myNTuple", "some/file.root");
std::cout << "myNTuple has " << ntuple->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< 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< 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 ntuple, including a list of fields.

Example: print summary information to stdout

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

Example: print detailed column storage data to stderr

#include <ROOT/RNTupleReader.hxx>
using ROOT::Experimental::ENTupleInfo;
using ROOT::Experimental::RNTupleReader;
 
#include <iostream>
 
auto ntuple = RNTupleReader::Open("myNTuple", "some/file.root");
ntuple->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 ntuple 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 89 of file RNTupleReader.hxx.

◆ fCreateModelOptions

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

private

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

Definition at line 92 of file RNTupleReader.hxx.

◆ fDisplayReader

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

private

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

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 83 of file RNTupleReader.hxx.

◆ fMetrics

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

private

Definition at line 90 of file RNTupleReader.hxx.

◆ fModel

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

private

Needs to be destructed before fSource.

Definition at line 79 of file RNTupleReader.hxx.

◆ fSource

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

private

Definition at line 77 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 IMT is on Needs to be destructed after the pages source is destructed (an thus be declared before)

Definition at line 75 of file RNTupleReader.hxx.

Libraries for ROOT::Experimental::RNTupleReader:

[legend]

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

tree/ntuple/v7/inc/ROOT/RNTupleReader.hxx
tree/ntuple/v7/src/RNTupleReader.cxx

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ RNTupleReader() [1/2]

◆ RNTupleReader() [2/2]

◆ ~RNTupleReader()

Member Function Documentation

◆ begin()

◆ Clone()

◆ ConnectModel()

◆ CreateEntry()

◆ EnableMetrics()

◆ end()

◆ GetCollectionView() [1/2]

◆ GetCollectionView() [2/2]

◆ GetDescriptor()

◆ GetDirectAccessView() [1/2]

◆ GetDirectAccessView() [2/2]

◆ GetDisplayReader()

◆ GetEntryRange()

◆ GetMetrics()

◆ GetModel()

◆ GetNEntries()

◆ GetView() [1/6]

◆ GetView() [2/6]

◆ GetView() [3/6]

◆ GetView() [4/6]

◆ GetView() [5/6]

◆ GetView() [6/6]

◆ InitPageSource()

◆ LoadEntry() [1/2]

◆ LoadEntry() [2/2]

◆ Open() [1/6]

◆ Open() [2/6]

◆ Open() [3/6]

◆ Open() [4/6]

◆ Open() [5/6]

◆ Open() [6/6]

◆ PrintInfo()

◆ RetrieveFieldId()

◆ Show()

Member Data Documentation

◆ fCachedDescriptor

◆ fCreateModelOptions

◆ fDisplayReader

◆ fMetrics

◆ fModel

◆ fSource

◆ fUnzipTasks