ROOT::Experimental::RNTupleModel Class Reference

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. From frozen, models move into a expired state. In this state, the model is only partially usable: it can be cloned and queried, but it can't be unfrozen anymore and no new entries can be created. This state is used for models that were used for writing and are no longer connected to a page sink.

Definition at line 122 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	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< ROOT::RFieldBase > field)
	Adds a field whose type is not known at compile time.
RResult< void >	AddProjectedField (std::unique_ptr< ROOT::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.
ROOT::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 ROOT::RNTupleWriteOptions &options=ROOT::RNTupleWriteOptions()) const
	Estimate the memory usage for this model during writing.
void	Expire ()
void	Freeze ()
const ROOT::RFieldBase &	GetConstField (std::string_view fieldName) const
const ROOT::RFieldZero &	GetConstFieldZero () const
REntry &	GetDefaultEntry ()
const REntry &	GetDefaultEntry () const
const std::string &	GetDescription () const
std::uint64_t	GetModelId () const
ROOT::RFieldBase &	GetMutableField (std::string_view fieldName)
ROOT::RFieldZero &	GetMutableFieldZero ()
	Mutable access to the root field is used to make adjustments to the fields.
const std::unordered_set< std::string > &	GetRegisteredSubfieldNames () const
	Get the (qualified) names of subfields that have been registered to be included in entries from this model.
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 field present in the entry.
bool	IsBare () const
bool	IsExpired () const
bool	IsFrozen () const
template<typename T >
std::shared_ptr< T >	MakeField (const NameWithDescription_t &fieldNameDesc)
	Creates a new field given a name or {name, description} pair and a corresponding, default-constructed value that is managed by a shared pointer.
RNTupleModel &	operator= (const RNTupleModel &)=delete
void	RegisterSubfield (std::string_view qualifiedFieldName)
	Register a subfield so it can be accessed directly from entries belonging to the model.
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< ROOT::RFieldZero > fieldZero)
static std::unique_ptr< RNTupleModel >	CreateBare ()
	A bare model has no default entry.
static std::unique_ptr< RNTupleModel >	CreateBare (std::unique_ptr< ROOT::RFieldZero > fieldZero)

Private Types
enum class	EState { kBuilding , kFrozen , kExpired }

Private Member Functions
	RNTupleModel (std::unique_ptr< ROOT::RFieldZero > fieldZero)
void	AddSubfield (std::string_view fieldName, REntry &entry, bool initializeValue=true) const
	Add a subfield to the provided entry.
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 RNTuple model.
ROOT::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, as well as registered subfields.
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< ROOT::RFieldZero >	fFieldZero
	Hierarchy of fields consisting of simple types and collections (sub trees)
std::uint64_t	fModelId = 0
	Every model has a unique ID to distinguish it from other models.
EState	fModelState = EState::kBuilding
	Changed by Freeze() / Unfreeze() and by the RUpdater.
std::unique_ptr< Internal::RProjectedFields >	fProjectedFields
	The set of projected top-level fields.
std::unordered_set< std::string >	fRegisteredSubfields
	Keeps track of which subfields have been registered to be included in entries belonging to this model.
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
ROOT::RFieldZero &	Internal::GetFieldZeroOfModel (RNTupleModel &)
Internal::RProjectedFields &	Internal::GetProjectedFieldsOfModel (RNTupleModel &)

#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 130 of file RNTupleModel.hxx.

Member Enumeration Documentation

EState

enum class ROOT::Experimental::RNTupleModel::EState

strongprivate

Enumerator
kBuilding
kFrozen
kExpired

Definition at line 148 of file RNTupleModel.hxx.

Constructor & Destructor Documentation

RNTupleModel() [1/2]

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

private

Definition at line 254 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< ROOT::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 335 of file RNTupleModel.cxx.

AddProjectedField()

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

Adds a top-level field based on existing fields.

The mapping function takes one argument, which is a string containing the name of the projected field. The return value of the mapping function should be the name of the (existing) field onto which the projection is made. Example

auto model = RNTupleModel::Create();
model->MakeField<float>("met");
auto metProjection = ROOT::RFieldBase::Create("missingE", "float").Unwrap();
model->AddProjectedField(std::move(metProjection), [](const std::string &) { return "met"; });

Adding projections for collection fields is also possible, as long as they follow the same schema structure. For example, a projection of a collection of structs onto a collection of scalars is possible, but a projection of a collection of a collection of scalars onto a collection of scalars is not.

In the case of projections for nested fields, the mapping function must provide a mapping for every nesting level. Example

struct P { int x, y; };
 
auto model = RNTupleModel::Create();
model->MakeField<std::vector<P>>("points");
auto pxProjection = ROOT::RFieldBase::Create("pxs", "std::vector<int>").Unwrap();
model->AddProjectedField(std::move(pxProjection), [](const std::string &fieldName) {
  if (fieldName == "pxs")
    return "points";
  else
    return "points._0.x";
});

Creating projections for fields containing std::variant or fixed-size arrays is unsupported.

Definition at line 394 of file RNTupleModel.cxx.

AddSubfield()

void ROOT::Experimental::RNTupleModel::AddSubfield ( std::string_view fieldName, REntry & entry, bool initializeValue = true ) const

private

Add a subfield to the provided entry.

If initializeValue is false, a nullptr will be bound to the entry value (used in bare models).

Definition at line 348 of file RNTupleModel.cxx.

Clone()

std::unique_ptr< ROOT::Experimental::RNTupleModel > ROOT::Experimental::RNTupleModel::Clone

(

)

const

Definition at line 285 of file RNTupleModel.cxx.

Create() [1/2]

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

static

Definition at line 272 of file RNTupleModel.cxx.

Create() [2/2]

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

static

Definition at line 278 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 259 of file RNTupleModel.cxx.

CreateBare() [2/2]

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

static

Definition at line 265 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 481 of file RNTupleModel.cxx.

CreateBulk()

ROOT::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 511 of file RNTupleModel.cxx.

CreateEntry()

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

(

)

const

Definition at line 463 of file RNTupleModel.cxx.

EnsureNotBare()

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

private

Throws an RException if fDefaultEntry is nullptr.

Definition at line 248 of file RNTupleModel.cxx.

EnsureNotFrozen()

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

private

Throws an RException if fFrozen is true.

Definition at line 242 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 RNTuple model.

Throws an RException for invalid names, empty names (which is reserved for the zero field) and duplicate field names.

Definition at line 228 of file RNTupleModel.cxx.

EstimateWriteMemoryUsage()

std::size_t ROOT::Experimental::RNTupleModel::EstimateWriteMemoryUsage

(

const ROOT::RNTupleWriteOptions &

options = ROOT::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 569 of file RNTupleModel.cxx.

Expire()

void ROOT::Experimental::RNTupleModel::Expire

(

)

Definition at line 525 of file RNTupleModel.cxx.

FindField()

ROOT::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 314 of file RNTupleModel.cxx.

Freeze()

void ROOT::Experimental::RNTupleModel::Freeze

(

)

Definition at line 555 of file RNTupleModel.cxx.

GetConstField()

const ROOT::RFieldBase & ROOT::Experimental::RNTupleModel::GetConstField

(

std::string_view

fieldName

)

const

Definition at line 440 of file RNTupleModel.cxx.

GetConstFieldZero()

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

inline

Definition at line 333 of file RNTupleModel.hxx.

GetDefaultEntry() [1/2]

ROOT::Experimental::REntry & ROOT::Experimental::RNTupleModel::GetDefaultEntry

(

)

Definition at line 449 of file RNTupleModel.cxx.

GetDefaultEntry() [2/2]

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

(

)

const

Definition at line 455 of file RNTupleModel.cxx.

GetDescription()

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

inline

Definition at line 337 of file RNTupleModel.hxx.

GetModelId()

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

inline

Definition at line 316 of file RNTupleModel.hxx.

GetMutableField()

ROOT::RFieldBase & ROOT::Experimental::RNTupleModel::GetMutableField

(

std::string_view

fieldName

)

Definition at line 429 of file RNTupleModel.cxx.

GetMutableFieldZero()

ROOT::RFieldZero & ROOT::Experimental::RNTupleModel::GetMutableFieldZero

(

)

Mutable access to the root field is used to make adjustments to the fields.

Definition at line 422 of file RNTupleModel.cxx.

GetRegisteredSubfieldNames()

const std::unordered_set< std::string > & ROOT::Experimental::RNTupleModel::GetRegisteredSubfieldNames ( ) const

inline

Get the (qualified) names of subfields that have been registered to be included in entries from this model.

Definition at line 341 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 field present in the entry.

Definition at line 499 of file RNTupleModel.cxx.

IsBare()

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

inline

Definition at line 315 of file RNTupleModel.hxx.

IsExpired()

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

inline

Definition at line 313 of file RNTupleModel.hxx.

IsFrozen()

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

inline

Definition at line 314 of file RNTupleModel.hxx.

MakeField()

template<typename T >

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

inline

Creates a new field given a name or {name, description} pair and a corresponding, default-constructed 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 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 244 of file RNTupleModel.hxx.

operator=()

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

delete

RegisterSubfield()

void ROOT::Experimental::RNTupleModel::RegisterSubfield

(

std::string_view

qualifiedFieldName

)

Register a subfield so it can be accessed directly from entries belonging to the model.

Because registering a subfield does not fundamentally change the model, previously created entries will not be invalidated, nor modified in any way; a registered subfield is merely an accessor added to the default entry (if present) and any entries created afterwards.

Using models with registered subfields for writing is not allowed. Attempting to do so will result in an exception.

Throws an exception if the provided subfield could not be found in the model.

Definition at line 358 of file RNTupleModel.cxx.

SetDescription()

void ROOT::Experimental::RNTupleModel::SetDescription

(

std::string_view

description

)

Definition at line 563 of file RNTupleModel.cxx.

Unfreeze()

void ROOT::Experimental::RNTupleModel::Unfreeze

(

)

Definition at line 538 of file RNTupleModel.cxx.

Friends And Related Symbol Documentation

Internal::GetFieldZeroOfModel

ROOT::RFieldZero & Internal::GetFieldZeroOfModel ( RNTupleModel & )

friend

Internal::GetProjectedFieldsOfModel

Internal::RProjectedFields & Internal::GetProjectedFieldsOfModel ( RNTupleModel & )

friend

Member Data Documentation

fDefaultEntry

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

private

Contains field values corresponding to the created top-level fields, as well as registered subfields.

Definition at line 157 of file RNTupleModel.hxx.

fDescription

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

private

Free text set by the user.

Definition at line 161 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 159 of file RNTupleModel.hxx.

fFieldZero

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

private

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

Definition at line 155 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. Expired models are cloned into frozen models.

Definition at line 168 of file RNTupleModel.hxx.

fModelState

EState ROOT::Experimental::RNTupleModel::fModelState = EState::kBuilding

private

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

Definition at line 172 of file RNTupleModel.hxx.

fProjectedFields

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

private

The set of projected top-level fields.

Definition at line 163 of file RNTupleModel.hxx.

fRegisteredSubfields

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

private

Keeps track of which subfields have been registered to be included in entries belonging to this model.

Definition at line 165 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 170 of file RNTupleModel.hxx.

Libraries for ROOT::Experimental::RNTupleModel:

---

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

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