An RNTuple that gets filled with entries (data) and writes them to storage.

RNTupleWriter is an interface for writing RNTuples to storage. It can be instantiated using the static functions Append() and Recreate(), providing an RNTupleModel that defines the schema of the data to be written.

An RNTuple can be thought of as a table, whose columns are defined by its schema (i.e. by its associated RNTupleModel, whose Fields map to 0 or more columns). Writing into an RNTuple happens by filling entries into the RNTupleWriter, which make up the rows of the table. The simplest way to do so is by:

retrieving a (shared) pointer to each Field's value;
writing a value into each pointer;
calling writer->Fill() to commit the entry with all the current pointer values.

#include <ROOT/RNTupleWriter.hxx>
 
/// 1. Create the model.
auto model = ROOT::RNTupleModel::Create();
// Define the schema by adding Fields to the model.
// MakeField returns a shared_ptr to the value to be written (in this case, a shared_ptr<int>)
auto pFoo = model->MakeField<int>("foo");
 
/// 2. Create writer from the model.
auto writer = ROOT::RNTupleReader::Recreate(std::move(model), "myNTuple", "some/file.root");
 
/// 3. Write into it.
for (int i = 0; i < 10; ++i) {
   // Assign the value you want to each RNTuple Field (in this case there is only one Field "foo").
   *pFoo = i;
 
   // Fill() writes the entire entry to the RNTuple.
   // After calling Fill() you can safely write another value into `pFoo` knowing that the previous one was
   // already saved.
   writer->Fill();
}
 
// On destruction, the writer will flush the written data to disk.

The caller has to make sure that the data that gets filled into an RNTuple is not modified for the time of the Fill() call. The Fill call serializes the C++ object into the column format and writes data into the corresponding column page buffers.

The actual writing of the buffers to storage is deferred and can be triggered by FlushCluster() or by destructing the writer.

On I/O errors, a ROOT::RException is thrown.

Definition at line 101 of file RNTupleWriter.hxx.

Public Member Functions
	RNTupleWriter (const RNTupleWriter &)=delete

	~RNTupleWriter ()

void	CommitCluster (bool commitClusterGroup=false)
	Ensure that the data from the so far seen Fill calls has been written to storage.

void	CommitDataset ()
	Closes the underlying file (page sink) and expires the model.

std::unique_ptr< ROOT::REntry >	CreateEntry () const

std::unique_ptr< ROOT::RNTupleModel::RUpdater >	CreateModelUpdater ()
	Get a RNTupleModel::RUpdater that provides limited support for incremental updates to the underlying model, e.g.

std::unique_ptr< Experimental::Detail::RRawPtrWriteEntry >	CreateRawPtrWriteEntry () const

void	EnableMetrics ()

std::size_t	Fill ()
	The simplest user interface if the default entry that comes with the ntuple model is used.

std::size_t	Fill (Experimental::Detail::RRawPtrWriteEntry &entry)
	Fill an RRawPtrWriteEntry into this ntuple.

std::size_t	Fill (ROOT::REntry &entry)
	Multiple entries can have been instantiated from the ntuple model.

void	FillNoFlush (Experimental::Detail::RRawPtrWriteEntry &entry, RNTupleFillStatus &status)
	Fill an RRawPtrWriteEntry into this ntuple, but don't commit the cluster.

void	FillNoFlush (ROOT::REntry &entry, RNTupleFillStatus &status)
	Fill an entry into this ntuple, but don't commit the cluster.

void	FlushCluster ()
	Flush so far filled entries to storage.

void	FlushColumns ()
	Flush column data, preparing for CommitCluster or to reduce memory usage.

ROOT::NTupleSize_t	GetLastCommitted () const
	Return the entry number that was last committed in a cluster.

ROOT::NTupleSize_t	GetLastCommittedClusterGroup () const
	Return the entry number that was last committed in a cluster group.

ROOT::NTupleSize_t	GetLastFlushed () const
	Return the entry number that was last flushed in a cluster.

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

const ROOT::RNTupleModel &	GetModel () const

ROOT::NTupleSize_t	GetNEntries () const
	Return the number of entries filled so far.

RNTupleWriter &	operator= (const RNTupleWriter &)=delete

Static Public Member Functions
static std::unique_ptr< RNTupleWriter >	Append (std::unique_ptr< ROOT::RNTupleModel > model, std::string_view ntupleName, TDirectory &fileOrDirectory, const ROOT::RNTupleWriteOptions &options=ROOT::RNTupleWriteOptions())
	Creates an RNTupleWriter that writes into an existing TFile or TDirectory, without overwriting its content.

static std::unique_ptr< RNTupleWriter >	Recreate (std::initializer_list< std::pair< std::string_view, std::string_view > > fields, std::string_view ntupleName, std::string_view storage, const ROOT::RNTupleWriteOptions &options=ROOT::RNTupleWriteOptions())
	Convenience function allowing to call Recreate() with an inline-defined model.

static std::unique_ptr< RNTupleWriter >	Recreate (std::unique_ptr< ROOT::RNTupleModel > model, std::string_view ntupleName, std::string_view storage, const ROOT::RNTupleWriteOptions &options=ROOT::RNTupleWriteOptions())
	Creates an RNTupleWriter backed by `storage`, overwriting it if one with the same URI exists.

Private Member Functions
	RNTupleWriter (std::unique_ptr< ROOT::RNTupleModel > model, std::unique_ptr< Internal::RPageSink > sink)

void	CommitClusterGroup ()

Internal::RPageSink &	GetSink ()

ROOT::RNTupleModel &	GetUpdatableModel ()

Static Private Member Functions
static std::unique_ptr< RNTupleWriter >	Create (std::unique_ptr< ROOT::RNTupleModel > model, std::unique_ptr< Internal::RPageSink > sink, const ROOT::RNTupleWriteOptions &options)
	Create a writer, potentially wrapping the sink in a RPageSinkBuf.

Private Attributes
Experimental::RNTupleFillContext	fFillContext

ROOT::NTupleSize_t	fLastCommittedClusterGroup = 0

Experimental::Detail::RNTupleMetrics	fMetrics

Friends
std::unique_ptr< RNTupleWriter >	Internal::CreateRNTupleWriter (std::unique_ptr< ROOT::RNTupleModel >, std::unique_ptr< Internal::RPageSink >)

#include <ROOT/RNTupleWriter.hxx>

Constructor & Destructor Documentation

◆ RNTupleWriter() [1/2]

ROOT::RNTupleWriter::RNTupleWriter	(	std::unique_ptr< ROOT::RNTupleModel >	model,
		std::unique_ptr< Internal::RPageSink >	sink )

private

Definition at line 32 of file RNTupleWriter.cxx.

◆ RNTupleWriter() [2/2]

ROOT::RNTupleWriter::RNTupleWriter ( const RNTupleWriter & )

delete

◆ ~RNTupleWriter()

ROOT::RNTupleWriter::~RNTupleWriter ( )

Definition at line 47 of file RNTupleWriter.cxx.

Member Function Documentation

◆ Append()

std::unique_ptr< ROOT::RNTupleWriter > ROOT::RNTupleWriter::Append	(	std::unique_ptr< ROOT::RNTupleModel >	model,
		std::string_view	ntupleName,
		TDirectory &	fileOrDirectory,
		const ROOT::RNTupleWriteOptions &	options = ROOT::RNTupleWriteOptions() )

static

Creates an RNTupleWriter that writes into an existing TFile or TDirectory, without overwriting its content.

fileOrDirectory may be an empty TFile.

See also: Recreate()

Definition at line 99 of file RNTupleWriter.cxx.

◆ CommitCluster()

void ROOT::RNTupleWriter::CommitCluster ( bool commitClusterGroup = false )

inline

Ensure that the data from the so far seen Fill calls has been written to storage.

Definition at line 186 of file RNTupleWriter.hxx.

◆ CommitClusterGroup()

void ROOT::RNTupleWriter::CommitClusterGroup ( )

private

Definition at line 116 of file RNTupleWriter.cxx.

◆ CommitDataset()

void ROOT::RNTupleWriter::CommitDataset ( )

Closes the underlying file (page sink) and expires the model.

Automatically called on destruct. Once the dataset is committed, calls to Fill(), [Commit|Flush]Cluster(), FlushColumns(), CreateEntry(), and model updating fail.

Definition at line 132 of file RNTupleWriter.cxx.

◆ Create()

std::unique_ptr< ROOT::RNTupleWriter > ROOT::RNTupleWriter::Create	(	std::unique_ptr< ROOT::RNTupleModel >	model,
		std::unique_ptr< Internal::RPageSink >	sink,
		const ROOT::RNTupleWriteOptions &	options )

staticprivate

Create a writer, potentially wrapping the sink in a RPageSinkBuf.

Definition at line 56 of file RNTupleWriter.cxx.

◆ CreateEntry()

std::unique_ptr< ROOT::REntry > ROOT::RNTupleWriter::CreateEntry ( ) const

inline

Definition at line 197 of file RNTupleWriter.hxx.

◆ CreateModelUpdater()

std::unique_ptr< ROOT::RNTupleModel::RUpdater > ROOT::RNTupleWriter::CreateModelUpdater ( )

inline

Get a RNTupleModel::RUpdater that provides limited support for incremental updates to the underlying model, e.g.

addition of new fields.

Note that a Model may not be extended with Streamer fields.

Example: add a new field after the model has been used to construct a RNTupleWriter object

#include <ROOT/RNTuple.hxx>
 
auto model = ROOT::RNTupleModel::Create();
auto fldFloat = model->MakeField<float>("fldFloat");
auto writer = ROOT::RNTupleWriter::Recreate(std::move(model), "myNTuple", "some/file.root");
auto updater = writer->CreateModelUpdater();
updater->BeginUpdate();
updater->AddField(std::make_unique<RField<float>>("pt"));
updater->CommitUpdate();
 
// ...

Definition at line 236 of file RNTupleWriter.hxx.

◆ CreateRawPtrWriteEntry()

std::unique_ptr< Experimental::Detail::RRawPtrWriteEntry > ROOT::RNTupleWriter::CreateRawPtrWriteEntry ( ) const

inline

Definition at line 198 of file RNTupleWriter.hxx.

◆ EnableMetrics()

void ROOT::RNTupleWriter::EnableMetrics ( )

inline

Definition at line 212 of file RNTupleWriter.hxx.

◆ Fill() [1/3]

std::size_t ROOT::RNTupleWriter::Fill ( )

inline

The simplest user interface if the default entry that comes with the ntuple model is used.

Returns: The number of uncompressed bytes written.

Definition at line 160 of file RNTupleWriter.hxx.

◆ Fill() [2/3]

std::size_t ROOT::RNTupleWriter::Fill ( Experimental::Detail::RRawPtrWriteEntry & entry )

inline

Fill an RRawPtrWriteEntry into this ntuple.

This method will check the entry's model ID to ensure it comes from the writer's own model or throw an exception otherwise.

Returns: The number of uncompressed bytes written.

Definition at line 172 of file RNTupleWriter.hxx.

◆ Fill() [3/3]

std::size_t ROOT::RNTupleWriter::Fill ( ROOT::REntry & entry )

inline

Multiple entries can have been instantiated from the ntuple model.

This method will check the entry's model ID to ensure it comes from the writer's own model or throw an exception otherwise.

Returns: The number of uncompressed bytes written.

Definition at line 164 of file RNTupleWriter.hxx.

◆ FillNoFlush() [1/2]

void ROOT::RNTupleWriter::FillNoFlush	(	Experimental::Detail::RRawPtrWriteEntry &	entry,
		RNTupleFillStatus &	status )

inline

Fill an RRawPtrWriteEntry into this ntuple, but don't commit the cluster.

The calling code must pass an RNTupleFillStatus and check RNTupleFillStatus::ShouldFlushCluster.

Definition at line 175 of file RNTupleWriter.hxx.

◆ FillNoFlush() [2/2]

void ROOT::RNTupleWriter::FillNoFlush	(	ROOT::REntry &	entry,
		RNTupleFillStatus &	status )

inline

Fill an entry into this ntuple, but don't commit the cluster.

The calling code must pass an RNTupleFillStatus and check RNTupleFillStatus::ShouldFlushCluster.

Definition at line 167 of file RNTupleWriter.hxx.

◆ FlushCluster()

void ROOT::RNTupleWriter::FlushCluster ( )

inline

Flush so far filled entries to storage.

Definition at line 184 of file RNTupleWriter.hxx.

◆ FlushColumns()

void ROOT::RNTupleWriter::FlushColumns ( )

inline

Flush column data, preparing for CommitCluster or to reduce memory usage.

This will trigger compression of pages, but not actually write to storage (unless buffered writing is turned off).

Definition at line 182 of file RNTupleWriter.hxx.

◆ GetLastCommitted()

ROOT::NTupleSize_t ROOT::RNTupleWriter::GetLastCommitted ( ) const

inline

Return the entry number that was last committed in a cluster.

Definition at line 206 of file RNTupleWriter.hxx.

◆ GetLastCommittedClusterGroup()

ROOT::NTupleSize_t ROOT::RNTupleWriter::GetLastCommittedClusterGroup ( ) const

inline

Return the entry number that was last committed in a cluster group.

Definition at line 208 of file RNTupleWriter.hxx.

◆ GetLastFlushed()

ROOT::NTupleSize_t ROOT::RNTupleWriter::GetLastFlushed ( ) const

inline

Return the entry number that was last flushed in a cluster.

Definition at line 204 of file RNTupleWriter.hxx.

◆ GetMetrics()

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

inline

Definition at line 213 of file RNTupleWriter.hxx.

◆ GetModel()

const ROOT::RNTupleModel & ROOT::RNTupleWriter::GetModel ( ) const

inline

Definition at line 215 of file RNTupleWriter.hxx.

◆ GetNEntries()

ROOT::NTupleSize_t ROOT::RNTupleWriter::GetNEntries ( ) const

inline

Return the number of entries filled so far.

Definition at line 210 of file RNTupleWriter.hxx.

◆ GetSink()

Internal::RPageSink & ROOT::RNTupleWriter::GetSink ( )

inlineprivate

Definition at line 115 of file RNTupleWriter.hxx.

◆ GetUpdatableModel()

ROOT::RNTupleModel & ROOT::RNTupleWriter::GetUpdatableModel ( )

private

Definition at line 124 of file RNTupleWriter.cxx.

◆ operator=()

RNTupleWriter & ROOT::RNTupleWriter::operator= ( const RNTupleWriter & )

delete

◆ Recreate() [1/2]

std::unique_ptr< ROOT::RNTupleWriter > ROOT::RNTupleWriter::Recreate	(	std::initializer_list< std::pair< std::string_view, std::string_view > >	fields,
		std::string_view	ntupleName,
		std::string_view	storage,
		const ROOT::RNTupleWriteOptions &	options = ROOT::RNTupleWriteOptions() )

static

Convenience function allowing to call Recreate() with an inline-defined model.

Definition at line 83 of file RNTupleWriter.cxx.

◆ Recreate() [2/2]

std::unique_ptr< ROOT::RNTupleWriter > ROOT::RNTupleWriter::Recreate	(	std::unique_ptr< ROOT::RNTupleModel >	model,
		std::string_view	ntupleName,
		std::string_view	storage,
		const ROOT::RNTupleWriteOptions &	options = ROOT::RNTupleWriteOptions() )

static

Creates an RNTupleWriter backed by storage, overwriting it if one with the same URI exists.

The format of the backing storage is determined by storage: in the simplest case it will be a local file, but a different backend may be selected via the URI prefix.

The RNTupleWriter will create an RNTuple with the schema determined by model (which must not be null) and with name ntupleName. This same name can later be used to read back the RNTuple via RNTupleReader.

Parameters

model	The RNTupleModel describing the schema of the RNTuple written by this writer
ntupleName	The name of the RNTuple to be written
storage	The URI where the RNTuple will be stored (usually just a file name or path)
options	May be passed to customize the behavior of the RNTupleWriter (see also RNTupleWriteOptions).

Throws a ROOT::RException if the model is null.

Definition at line 75 of file RNTupleWriter.cxx.

Friends And Related Symbol Documentation

◆ Internal::CreateRNTupleWriter

std::unique_ptr< RNTupleWriter > Internal::CreateRNTupleWriter	(	std::unique_ptr< ROOT::RNTupleModel >	,
		std::unique_ptr< Internal::RPageSink >	)

friend

Member Data Documentation

◆ fFillContext

Experimental::RNTupleFillContext ROOT::RNTupleWriter::fFillContext

private

Definition at line 107 of file RNTupleWriter.hxx.

◆ fLastCommittedClusterGroup

ROOT::NTupleSize_t ROOT::RNTupleWriter::fLastCommittedClusterGroup = 0

private

Definition at line 110 of file RNTupleWriter.hxx.

◆ fMetrics

Experimental::Detail::RNTupleMetrics ROOT::RNTupleWriter::fMetrics

private

Definition at line 108 of file RNTupleWriter.hxx.

Libraries for ROOT::RNTupleWriter:

[legend]

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

tree/ntuple/inc/ROOT/RNTupleWriter.hxx
tree/ntuple/src/RNTupleWriter.cxx

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Friends

Constructor & Destructor Documentation

◆ RNTupleWriter() [1/2]

◆ RNTupleWriter() [2/2]

◆ ~RNTupleWriter()

Member Function Documentation

◆ Append()

◆ CommitCluster()

◆ CommitClusterGroup()

◆ CommitDataset()

◆ Create()

◆ CreateEntry()

◆ CreateModelUpdater()

◆ CreateRawPtrWriteEntry()

◆ EnableMetrics()

◆ Fill() [1/3]

◆ Fill() [2/3]

◆ Fill() [3/3]

◆ FillNoFlush() [1/2]

◆ FillNoFlush() [2/2]

◆ FlushCluster()

◆ FlushColumns()

◆ GetLastCommitted()

◆ GetLastCommittedClusterGroup()

◆ GetLastFlushed()

◆ GetMetrics()

◆ GetModel()

◆ GetNEntries()

◆ GetSink()

◆ GetUpdatableModel()

◆ operator=()

◆ Recreate() [1/2]

◆ Recreate() [2/2]

Friends And Related Symbol Documentation

◆ Internal::CreateRNTupleWriter

Member Data Documentation

◆ fFillContext

◆ fLastCommittedClusterGroup

◆ fMetrics