The RNTupleModel encapulates the schema of an ntuple.

The ntuple model comprises a collection of hierarchically organized fields. From a model, "entries" can be extracted. For convenience, the model provides a default entry unless it is created as a "bare model". Models have a unique model identifier that faciliates checking whether entries are compatible with it (i.e.: have been extracted from that model).

A model is subject to a state transition during its lifetime: it starts in a building state, in which fields can be added and modified. Once the schema is finalized, the model gets frozen. Only frozen models can create entries.

Definition at line 91 of file RNTupleModel.hxx.

Classes
struct	NameWithDescription_t
	A wrapper over a field name and an optional description; used in `AddField()` and `RUpdater::AddField()` More...

class	RProjectedFields
	Projected fields are fields whose columns are reused from existing fields. More...

class	RUpdater
	A model is usually immutable after passing it to an `RNTupleWriter`. More...

Public Types
using	FieldMappingFunc_t = std::function< std::string(const std::string &)>
	User provided function that describes the mapping of existing source fields to projected fields in terms of fully qualified field names.

Public Member Functions
	RNTupleModel (const RNTupleModel &)=delete

	~RNTupleModel ()=default

void	AddField (std::unique_ptr< RFieldBase > field)
	Adds a field whose type is not known at compile time.

RResult< void >	AddProjectedField (std::unique_ptr< RFieldBase > field, FieldMappingFunc_t mapping)
	Adds a top-level field based on existing fields.

std::unique_ptr< RNTupleModel >	Clone () const

std::unique_ptr< REntry >	CreateBareEntry () const
	In a bare entry, all values point to nullptr.

RFieldBase::RBulk	CreateBulk (std::string_view fieldName) const
	Calls the given field's CreateBulk() method. Throws an exception if no field with the given name exists.

std::unique_ptr< REntry >	CreateEntry () const

std::size_t	EstimateWriteMemoryUsage (const RNTupleWriteOptions &options=RNTupleWriteOptions()) const
	Estimate the memory usage for this model during writing.

void	Freeze ()

REntry &	GetDefaultEntry ()

const REntry &	GetDefaultEntry () const

const std::string &	GetDescription () const

const RFieldBase &	GetField (std::string_view fieldName) const

RFieldZero &	GetFieldZero ()
	Non-const access to the root field is used to commit clusters during writing, and to make adjustments to the fields between freezing and connecting to a page sink.

const RFieldZero &	GetFieldZero () const

std::uint64_t	GetModelId () const

const RProjectedFields &	GetProjectedFields () const

std::uint64_t	GetSchemaId () const

REntry::RFieldToken	GetToken (std::string_view fieldName) const
	Creates a token to be used in REntry methods to address a top-level field.

bool	IsBare () const

bool	IsFrozen () const

std::shared_ptr< RNTupleCollectionWriter >	MakeCollection (std::string_view fieldName, std::unique_ptr< RNTupleModel > collectionModel)
	Ingests a model for a sub collection and attaches it to the current model.

template<typename T , typename... ArgsT>
std::shared_ptr< T >	MakeField (const NameWithDescription_t &fieldNameDesc, ArgsT &&...args)
	Creates a new field given a `name` or `{name, description}` pair and a corresponding value that is managed by a shared pointer.

RNTupleModel &	operator= (const RNTupleModel &)=delete

void	SetDescription (std::string_view description)

void	Unfreeze ()

Static Public Member Functions
static std::unique_ptr< RNTupleModel >	Create ()

static std::unique_ptr< RNTupleModel >	Create (std::unique_ptr< RFieldZero > fieldZero)

static std::unique_ptr< RNTupleModel >	CreateBare ()
	A bare model has no default entry.

static std::unique_ptr< RNTupleModel >	CreateBare (std::unique_ptr< RFieldZero > fieldZero)

Private Member Functions
	RNTupleModel (std::unique_ptr< RFieldZero > fieldZero)

void	EnsureNotBare () const
	Throws an RException if fDefaultEntry is nullptr.

void	EnsureNotFrozen () const
	Throws an RException if fFrozen is true.

void	EnsureValidFieldName (std::string_view fieldName)
	Checks that user-provided field names are valid in the context of this NTuple model.

RFieldBase *	FindField (std::string_view fieldName) const
	The field name can be a top-level field or a nested field. Returns nullptr if the field is not in the model.

Private Attributes
std::unique_ptr< REntry >	fDefaultEntry
	Contains field values corresponding to the created top-level fields.

std::string	fDescription
	Free text set by the user.

std::unordered_set< std::string >	fFieldNames
	Keeps track of which field names are taken, including projected field names.

std::unique_ptr< RFieldZero >	fFieldZero
	Hierarchy of fields consisting of simple types and collections (sub trees)

bool	fIsFrozen = false
	Changed by Freeze() / Unfreeze() and by the RUpdater.

std::uint64_t	fModelId = 0
	Every model has a unique ID to distinguish it from other models.

std::unique_ptr< RProjectedFields >	fProjectedFields
	The set of projected top-level fields.

std::uint64_t	fSchemaId = 0
	Models have a separate schema ID to remember that the clone of a frozen model still has the same schema.

Friends
std::unique_ptr< RNTupleModel >	Internal::MergeModels (const RNTupleModel &left, const RNTupleModel &right, std::string_view rightFieldPrefix)

#include <ROOT/RNTupleModel.hxx>

Member Typedef Documentation

◆ FieldMappingFunc_t

using ROOT::Experimental::RNTupleModel::FieldMappingFunc_t = std::function<std::string(const std::string &)>

User provided function that describes the mapping of existing source fields to projected fields in terms of fully qualified field names.

The mapping function is called with the qualified field names of the provided field and the subfields. It should return the qualified field names used as a mapping source.

Definition at line 99 of file RNTupleModel.hxx.

Constructor & Destructor Documentation

◆ RNTupleModel() [1/2]

ROOT::Experimental::RNTupleModel::RNTupleModel ( std::unique_ptr< RFieldZero > fieldZero )

private

Definition at line 229 of file RNTupleModel.cxx.

◆ RNTupleModel() [2/2]

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

delete

◆ ~RNTupleModel()

ROOT::Experimental::RNTupleModel::~RNTupleModel ( )

default

Member Function Documentation

◆ AddField()

void ROOT::Experimental::RNTupleModel::AddField ( std::unique_ptr< RFieldBase > field )

Adds a field whose type is not known at compile time.

Thus there is no shared pointer returned.

Throws an exception if the field is null.

Definition at line 305 of file RNTupleModel.cxx.

◆ AddProjectedField()

ROOT::Experimental::RResult< void > ROOT::Experimental::RNTupleModel::AddProjectedField	(	std::unique_ptr< RFieldBase >	field,
		FieldMappingFunc_t	mapping
	)

Adds a top-level field based on existing fields.

Definition at line 319 of file RNTupleModel.cxx.

◆ Clone()

std::unique_ptr< ROOT::Experimental::RNTupleModel > ROOT::Experimental::RNTupleModel::Clone ( ) const

Definition at line 259 of file RNTupleModel.cxx.

◆ Create() [1/2]

std::unique_ptr< ROOT::Experimental::RNTupleModel > ROOT::Experimental::RNTupleModel::Create ( )

static

Definition at line 246 of file RNTupleModel.cxx.

◆ Create() [2/2]

std::unique_ptr< ROOT::Experimental::RNTupleModel > ROOT::Experimental::RNTupleModel::Create ( std::unique_ptr< RFieldZero > fieldZero )

static

Definition at line 252 of file RNTupleModel.cxx.

◆ CreateBare() [1/2]

std::unique_ptr< ROOT::Experimental::RNTupleModel > ROOT::Experimental::RNTupleModel::CreateBare ( )

static

A bare model has no default entry.

Definition at line 233 of file RNTupleModel.cxx.

◆ CreateBare() [2/2]

std::unique_ptr< ROOT::Experimental::RNTupleModel > ROOT::Experimental::RNTupleModel::CreateBare ( std::unique_ptr< RFieldZero > fieldZero )

static

Definition at line 239 of file RNTupleModel.cxx.

◆ CreateBareEntry()

std::unique_ptr< ROOT::Experimental::REntry > ROOT::Experimental::RNTupleModel::CreateBareEntry ( ) const

In a bare entry, all values point to nullptr.

The resulting entry shall use BindValue() in order set memory addresses to be serialized / deserialized

Definition at line 412 of file RNTupleModel.cxx.

◆ CreateBulk()

ROOT::Experimental::RFieldBase::RBulk ROOT::Experimental::RNTupleModel::CreateBulk ( std::string_view fieldName ) const

Calls the given field's CreateBulk() method. Throws an exception if no field with the given name exists.

Definition at line 436 of file RNTupleModel.cxx.

◆ CreateEntry()

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

Definition at line 400 of file RNTupleModel.cxx.

◆ EnsureNotBare()

void ROOT::Experimental::RNTupleModel::EnsureNotBare ( ) const

private

Throws an RException if fDefaultEntry is nullptr.

Definition at line 223 of file RNTupleModel.cxx.

◆ EnsureNotFrozen()

void ROOT::Experimental::RNTupleModel::EnsureNotFrozen ( ) const

private

Throws an RException if fFrozen is true.

Definition at line 217 of file RNTupleModel.cxx.

◆ EnsureValidFieldName()

void ROOT::Experimental::RNTupleModel::EnsureValidFieldName ( std::string_view fieldName )

private

Checks that user-provided field names are valid in the context of this NTuple model.

Throws an RException for invalid names.

Definition at line 206 of file RNTupleModel.cxx.

◆ EstimateWriteMemoryUsage()

std::size_t ROOT::Experimental::RNTupleModel::EstimateWriteMemoryUsage ( const RNTupleWriteOptions & options = RNTupleWriteOptions() ) const

Estimate the memory usage for this model during writing.

This will return an estimate in bytes for the internal page and compression buffers. The value should be understood per sequential RNTupleWriter or per RNTupleFillContext created for a RNTupleParallelWriter constructed with this model.

Definition at line 472 of file RNTupleModel.cxx.

◆ FindField()

ROOT::Experimental::RFieldBase * ROOT::Experimental::RNTupleModel::FindField ( std::string_view fieldName ) const

private

The field name can be a top-level field or a nested field. Returns nullptr if the field is not in the model.

Definition at line 284 of file RNTupleModel.cxx.

◆ Freeze()

void ROOT::Experimental::RNTupleModel::Freeze ( )

Definition at line 461 of file RNTupleModel.cxx.

◆ GetDefaultEntry() [1/2]

ROOT::Experimental::REntry & ROOT::Experimental::RNTupleModel::GetDefaultEntry ( )

Definition at line 386 of file RNTupleModel.cxx.

◆ GetDefaultEntry() [2/2]

const ROOT::Experimental::REntry & ROOT::Experimental::RNTupleModel::GetDefaultEntry ( ) const

Definition at line 392 of file RNTupleModel.cxx.

◆ GetDescription()

const std::string & ROOT::Experimental::RNTupleModel::GetDescription ( ) const

inline

Definition at line 343 of file RNTupleModel.hxx.

◆ GetField()

const ROOT::Experimental::RFieldBase & ROOT::Experimental::RNTupleModel::GetField ( std::string_view fieldName ) const

Definition at line 377 of file RNTupleModel.cxx.

◆ GetFieldZero() [1/2]

ROOT::Experimental::RFieldZero & ROOT::Experimental::RNTupleModel::GetFieldZero ( )

Non-const access to the root field is used to commit clusters during writing, and to make adjustments to the fields between freezing and connecting to a page sink.

Definition at line 370 of file RNTupleModel.cxx.

◆ GetFieldZero() [2/2]

const RFieldZero & ROOT::Experimental::RNTupleModel::GetFieldZero ( ) const

inline

Definition at line 340 of file RNTupleModel.hxx.

◆ GetModelId()

std::uint64_t ROOT::Experimental::RNTupleModel::GetModelId ( ) const

inline

Definition at line 316 of file RNTupleModel.hxx.

◆ GetProjectedFields()

const RProjectedFields & ROOT::Experimental::RNTupleModel::GetProjectedFields ( ) const

inline

Definition at line 310 of file RNTupleModel.hxx.

◆ GetSchemaId()

std::uint64_t ROOT::Experimental::RNTupleModel::GetSchemaId ( ) const

inline

Definition at line 317 of file RNTupleModel.hxx.

◆ GetToken()

ROOT::Experimental::REntry::RFieldToken ROOT::Experimental::RNTupleModel::GetToken ( std::string_view fieldName ) const

Creates a token to be used in REntry methods to address a top-level field.

Definition at line 424 of file RNTupleModel.cxx.

◆ IsBare()

bool ROOT::Experimental::RNTupleModel::IsBare ( ) const

inline

Definition at line 315 of file RNTupleModel.hxx.

◆ IsFrozen()

bool ROOT::Experimental::RNTupleModel::IsFrozen ( ) const

inline

Definition at line 314 of file RNTupleModel.hxx.

◆ MakeCollection()

std::shared_ptr< ROOT::Experimental::RNTupleCollectionWriter > ROOT::Experimental::RNTupleModel::MakeCollection	(	std::string_view	fieldName,
		std::unique_ptr< RNTupleModel >	collectionModel
	)

Ingests a model for a sub collection and attaches it to the current model.

Throws an exception if collectionModel is null.

Definition at line 348 of file RNTupleModel.cxx.

◆ MakeField()

template<typename T , typename... ArgsT>

std::shared_ptr< T > ROOT::Experimental::RNTupleModel::MakeField	(	const NameWithDescription_t &	fieldNameDesc,
		ArgsT &&...	args
	)

inline

Creates a new field given a name or {name, description} pair and a corresponding value that is managed by a shared pointer.

Example: create some fields and fill an RNTuple

#include <ROOT/RNTupleModel.hxx>
#include <ROOT/RNTupleWriter.hxx>
using ROOT::Experimental::RNTupleModel;
using ROOT::Experimental::RNTupleWriter;
 
#include <vector>
 
auto model = RNTupleModel::Create();
auto pt = model->MakeField<float>("pt");
auto vec = model->MakeField<std::vector<int>>("vec");
 
// The RNTuple is written to disk when the RNTupleWriter goes out of scope
{
   auto writer = RNTupleWriter::Recreate(std::move(model), "myNTuple", "myFile.root");
   for (int i = 0; i < 100; i++) {
      *pt = static_cast<float>(i);
      *vec = {i, i+1, i+2};
      writer->Fill();
   }
}

Example: create a field with an initial value

#include <ROOT/RNTupleModel.hxx>
using ROOT::Experimental::RNTupleModel;
 
auto model = RNTupleModel::Create();
// pt's initial value is 42.0
auto pt = model->MakeField<float>("pt", 42.0);

Example: create a field with a description

#include <ROOT/RNTupleModel.hxx>
using ROOT::Experimental::RNTupleModel;
 
auto model = RNTupleModel::Create();
auto hadronFlavour = model->MakeField<float>({
   "hadronFlavour", "flavour from hadron ghost clustering"
});

Definition at line 289 of file RNTupleModel.hxx.

◆ operator=()

RNTupleModel & ROOT::Experimental::RNTupleModel::operator= ( const RNTupleModel & )

delete

◆ SetDescription()

void ROOT::Experimental::RNTupleModel::SetDescription ( std::string_view description )

Definition at line 466 of file RNTupleModel.cxx.

◆ Unfreeze()

void ROOT::Experimental::RNTupleModel::Unfreeze ( )

Definition at line 447 of file RNTupleModel.cxx.

Friends And Related Symbol Documentation

◆ Internal::MergeModels

std::unique_ptr< RNTupleModel > Internal::MergeModels	(	const RNTupleModel &	left,
		const RNTupleModel &	right,
		std::string_view	rightFieldPrefix
	)

friend

Member Data Documentation

◆ fDefaultEntry

std::unique_ptr<REntry> ROOT::Experimental::RNTupleModel::fDefaultEntry

private

Contains field values corresponding to the created top-level fields.

Definition at line 200 of file RNTupleModel.hxx.

◆ fDescription

std::string ROOT::Experimental::RNTupleModel::fDescription

private

Free text set by the user.

Definition at line 204 of file RNTupleModel.hxx.

◆ fFieldNames

std::unordered_set<std::string> ROOT::Experimental::RNTupleModel::fFieldNames

private

Keeps track of which field names are taken, including projected field names.

Definition at line 202 of file RNTupleModel.hxx.

◆ fFieldZero

std::unique_ptr<RFieldZero> ROOT::Experimental::RNTupleModel::fFieldZero

private

Hierarchy of fields consisting of simple types and collections (sub trees)

Definition at line 198 of file RNTupleModel.hxx.

◆ fIsFrozen

bool ROOT::Experimental::RNTupleModel::fIsFrozen = false

private

Changed by Freeze() / Unfreeze() and by the RUpdater.

Definition at line 213 of file RNTupleModel.hxx.

◆ fModelId

std::uint64_t ROOT::Experimental::RNTupleModel::fModelId = 0

private

Every model has a unique ID to distinguish it from other models.

Entries are linked to models via the ID. Cloned models get a new model ID.

Definition at line 209 of file RNTupleModel.hxx.

◆ fProjectedFields

std::unique_ptr<RProjectedFields> ROOT::Experimental::RNTupleModel::fProjectedFields

private

The set of projected top-level fields.

Definition at line 206 of file RNTupleModel.hxx.

◆ fSchemaId

std::uint64_t ROOT::Experimental::RNTupleModel::fSchemaId = 0

private

Models have a separate schema ID to remember that the clone of a frozen model still has the same schema.

Definition at line 211 of file RNTupleModel.hxx.

Libraries for ROOT::Experimental::RNTupleModel:

[legend]

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

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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Member Typedef Documentation

◆ FieldMappingFunc_t

Constructor & Destructor Documentation

◆ RNTupleModel() [1/2]

◆ RNTupleModel() [2/2]

◆ ~RNTupleModel()

Member Function Documentation

◆ AddField()

◆ AddProjectedField()

◆ Clone()

◆ Create() [1/2]

◆ Create() [2/2]

◆ CreateBare() [1/2]

◆ CreateBare() [2/2]

◆ CreateBareEntry()

◆ CreateBulk()

◆ CreateEntry()

◆ EnsureNotBare()

◆ EnsureNotFrozen()

◆ EnsureValidFieldName()

◆ EstimateWriteMemoryUsage()

◆ FindField()

◆ Freeze()

◆ GetDefaultEntry() [1/2]

◆ GetDefaultEntry() [2/2]

◆ GetDescription()

◆ GetField()

◆ GetFieldZero() [1/2]

◆ GetFieldZero() [2/2]

◆ GetModelId()

◆ GetProjectedFields()

◆ GetSchemaId()

◆ GetToken()

◆ IsBare()

◆ IsFrozen()

◆ MakeCollection()

◆ MakeField()

◆ operator=()

◆ SetDescription()

◆ Unfreeze()

Friends And Related Symbol Documentation

◆ Internal::MergeModels

Member Data Documentation

◆ fDefaultEntry

◆ fDescription

◆ fFieldNames

◆ fFieldZero

◆ fIsFrozen

◆ fModelId

◆ fProjectedFields

◆ fSchemaId