Logo ROOT  
Reference Guide
 
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Modules Pages
Loading...
Searching...
No Matches
ROOT::RNTupleModel Class Reference

The RNTupleModel encapulates the schema of an RNTuple.

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

A model is subject to state transitions 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 an 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.

|
| (passed to a Sink (detached from
| | frozen) | | writing) | |
| Building |---------------->| Frozen |-------------->| Expired |
|___________|<----------------|__________| |___________|
#define a(i)
Definition RSha256.hxx:99
ROOT::Detail::TRangeCast< T, true > TRangeDynCast
TRangeDynCast is an adapter class that allows the typed iteration through a TCollection.

Definition at line 141 of file RNTupleModel.hxx.

Classes

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< RNTupleModelClone () const
 
std::unique_ptr< REntryCreateBareEntry () const
 Creates a "bare entry", i.e.
 
ROOT::RFieldBase::RBulk CreateBulk (std::string_view fieldName) const
 Calls the given field's CreateBulk() method. Throws an RException if no field with the given name exists.
 
std::unique_ptr< REntryCreateEntry () const
 Creates a new entry with default values for each field.
 
std::unique_ptr< Experimental::Detail::RRawPtrWriteEntryCreateRawPtrWriteEntry () const
 
std::size_t EstimateWriteMemoryUsage (const ROOT::RNTupleWriteOptions &options=ROOT::RNTupleWriteOptions()) const
 Estimate the memory usage for this model during writing.
 
void Expire ()
 Transitions an RNTupleModel from the frozen state to the expired state, invalidating all previously created entries, disabling creating new entries from it and disabling further state transitions.
 
void Freeze ()
 Transitions an RNTupleModel from the building state to the frozen state, disabling adding additional fields and enabling creating entries from it.
 
const ROOT::RFieldBaseGetConstField (std::string_view fieldName) const
 
const ROOT::RFieldZeroGetConstFieldZero () const
 Retrieves the field zero of this model, i.e. the root of the field hierarchy.
 
REntryGetDefaultEntry ()
 Retrieves the default entry of this model.
 
const REntryGetDefaultEntry () const
 
const std::string & GetDescription () const
 
const std::unordered_set< std::string > & GetFieldNames () const
 Get the names of the fields currently present in the model, including projected fields.
 
std::uint64_t GetModelId () const
 
ROOT::RFieldBaseGetMutableField (std::string_view fieldName)
 Retrieves the field with fully-qualified name fieldName.
 
ROOT::RFieldZeroGetMutableFieldZero ()
 Retrieves the field zero of this model, i.e.
 
const std::unordered_set< std::string > & GetRegisteredSubfieldNames () const
 Get the (qualified) names of subfields that have been registered (via RegisterSubfield()) to be included in entries from this model.
 
std::uint64_t GetSchemaId () const
 
ROOT::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 (std::string_view name, std::string_view description="")
 Creates a new field given a name or {name, description} pair and a corresponding, default-constructed value that is managed by a shared pointer.
 
RNTupleModeloperator= (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 ()
 Transitions an RNTupleModel from the frozen state back to the building state, invalidating all previously created entries, re-enabling adding additional fields and disabling creating entries from it.
 

Static Public Member Functions

static std::unique_ptr< RNTupleModelCreate ()
 
static std::unique_ptr< RNTupleModelCreate (std::unique_ptr< ROOT::RFieldZero > fieldZero)
 
static std::unique_ptr< RNTupleModelCreateBare ()
 Creates a "bare model", i.e. an RNTupleModel with no default entry.
 
static std::unique_ptr< RNTupleModelCreateBare (std::unique_ptr< ROOT::RFieldZero > fieldZero)
 Creates a "bare model", i.e. an RNTupleModel with no default entry, with the given field zero.
 

Private Types

enum class  EState { kBuilding , kFrozen , kExpired }
 The states a model can be in. More...
 

Private Member Functions

 RNTupleModel (std::unique_ptr< ROOT::RFieldZero > fieldZero)
 
void AddSubfield (std::string_view fieldName, ROOT::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 RNTupleModel.
 
ROOT::RFieldBaseFindField (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< ROOT::REntryfDefaultEntry
 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::RFieldZerofFieldZero
 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::RProjectedFieldsfProjectedFields
 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::RFieldZeroInternal::GetFieldZeroOfModel (RNTupleModel &)
 
Internal::RProjectedFieldsInternal::GetProjectedFieldsOfModel (RNTupleModel &)
 

#include <ROOT/RNTupleModel.hxx>

Member Typedef Documentation

◆ FieldMappingFunc_t

using ROOT::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. See AddProjectedFields() for more details.

Definition at line 150 of file RNTupleModel.hxx.

Member Enumeration Documentation

◆ EState

The states a model can be in.

Possible transitions are between kBuilding and kFrozen and from kFrozen to kExpired. See RNTupleModel for the state transition graph.

Enumerator
kBuilding 
kFrozen 
kExpired 

Definition at line 158 of file RNTupleModel.hxx.

Constructor & Destructor Documentation

◆ RNTupleModel() [1/2]

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

Definition at line 265 of file RNTupleModel.cxx.

◆ RNTupleModel() [2/2]

ROOT::RNTupleModel::RNTupleModel ( const RNTupleModel & )
delete

◆ ~RNTupleModel()

ROOT::RNTupleModel::~RNTupleModel ( )
default

Member Function Documentation

◆ AddField()

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

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

No shared pointer is returned in this case: pointers should be retrieved or bound via REntry.

Throws an RException if the field is null.

Definition at line 345 of file RNTupleModel.cxx.

◆ AddProjectedField()

ROOT::RResult< void > ROOT::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"; });
static RResult< std::unique_ptr< RFieldBase > > Create(const std::string &fieldName, const std::string &typeName, const ROOT::RCreateFieldOptions &options, const ROOT::RNTupleDescriptor *desc, ROOT::DescriptorId_t fieldId)
Factory method to resurrect a field from the stored on-disk type information.
static std::unique_ptr< RNTupleModel > Create()

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";
});
Double_t y[n]
Definition legend1.C:17
Double_t x[n]
Definition legend1.C:17

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

Definition at line 404 of file RNTupleModel.cxx.

◆ AddSubfield()

void ROOT::RNTupleModel::AddSubfield ( std::string_view fieldName,
ROOT::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 358 of file RNTupleModel.cxx.

◆ Clone()

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

Definition at line 294 of file RNTupleModel.cxx.

◆ Create() [1/2]

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

Definition at line 282 of file RNTupleModel.cxx.

◆ Create() [2/2]

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

Definition at line 287 of file RNTupleModel.cxx.

◆ CreateBare() [1/2]

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

Creates a "bare model", i.e. an RNTupleModel with no default entry.

Definition at line 270 of file RNTupleModel.cxx.

◆ CreateBare() [2/2]

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

Creates a "bare model", i.e. an RNTupleModel with no default entry, with the given field zero.

Definition at line 275 of file RNTupleModel.cxx.

◆ CreateBareEntry()

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

Creates a "bare entry", i.e.

a entry with all null values. The user needs to explicitly call BindValue() or BindRawPtr() to set memory addresses before serializing / deserializing the entry.

Definition at line 491 of file RNTupleModel.cxx.

◆ CreateBulk()

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

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

Definition at line 538 of file RNTupleModel.cxx.

◆ CreateEntry()

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

Creates a new entry with default values for each field.

Definition at line 473 of file RNTupleModel.cxx.

◆ CreateRawPtrWriteEntry()

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

Definition at line 509 of file RNTupleModel.cxx.

◆ EnsureNotBare()

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

Throws an RException if fDefaultEntry is nullptr.

Definition at line 259 of file RNTupleModel.cxx.

◆ EnsureNotFrozen()

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

Throws an RException if fFrozen is true.

Definition at line 253 of file RNTupleModel.cxx.

◆ EnsureValidFieldName()

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

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

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

Definition at line 239 of file RNTupleModel.cxx.

◆ EstimateWriteMemoryUsage()

std::size_t ROOT::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 an RNTupleParallelWriter constructed with this model.

Definition at line 596 of file RNTupleModel.cxx.

◆ Expire()

void ROOT::RNTupleModel::Expire ( )

Transitions an RNTupleModel from the frozen state to the expired state, invalidating all previously created entries, disabling creating new entries from it and disabling further state transitions.

Expiring a model that is already expired is a no-op. Throws an RException if the model is in the building state. See RNTupleModel for a more detailed explanation on the state transitions.

Definition at line 552 of file RNTupleModel.cxx.

◆ FindField()

ROOT::RFieldBase * ROOT::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 324 of file RNTupleModel.cxx.

◆ Freeze()

void ROOT::RNTupleModel::Freeze ( )

Transitions an RNTupleModel from the building state to the frozen state, disabling adding additional fields and enabling creating entries from it.

Freezing an already-frozen model is a no-op. Throws an RException if the model is in the expired state. See RNTupleModel for more detailed explanation on the state transitions.

Definition at line 582 of file RNTupleModel.cxx.

◆ GetConstField()

const ROOT::RFieldBase & ROOT::RNTupleModel::GetConstField ( std::string_view fieldName) const
See also
GetMutableField()

Definition at line 450 of file RNTupleModel.cxx.

◆ GetConstFieldZero()

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

Retrieves the field zero of this model, i.e. the root of the field hierarchy.

Definition at line 364 of file RNTupleModel.hxx.

◆ GetDefaultEntry() [1/2]

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

Retrieves the default entry of this model.

Throws an RException if this is a bare model (i.e. if it was created with CreateBare()).

Definition at line 459 of file RNTupleModel.cxx.

◆ GetDefaultEntry() [2/2]

const ROOT::REntry & ROOT::RNTupleModel::GetDefaultEntry ( ) const
See also
GetDefaultEntry()

Definition at line 465 of file RNTupleModel.cxx.

◆ GetDescription()

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

Definition at line 373 of file RNTupleModel.hxx.

◆ GetFieldNames()

const std::unordered_set< std::string > & ROOT::RNTupleModel::GetFieldNames ( ) const
inline

Get the names of the fields currently present in the model, including projected fields.

Registered subfields are not included, use GetRegisteredSubfieldnames() for this.

Definition at line 378 of file RNTupleModel.hxx.

◆ GetModelId()

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

Definition at line 340 of file RNTupleModel.hxx.

◆ GetMutableField()

ROOT::RFieldBase & ROOT::RNTupleModel::GetMutableField ( std::string_view fieldName)

Retrieves the field with fully-qualified name fieldName.

Dot-separated names are used to walk down the field hierarchy: e.g. "parent.child" should be used to retrieve a field with name "child" whose parent is the top-level field with name "parent". Throws an RException if no field is found with the given name.

Definition at line 439 of file RNTupleModel.cxx.

◆ GetMutableFieldZero()

ROOT::RFieldZero & ROOT::RNTupleModel::GetMutableFieldZero ( )

Retrieves the field zero of this model, i.e.

the root of the field hierarchy. This may be used to make adjustments on the field hierarchy before the model is frozen.

Definition at line 432 of file RNTupleModel.cxx.

◆ GetRegisteredSubfieldNames()

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

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

Definition at line 381 of file RNTupleModel.hxx.

◆ GetSchemaId()

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

Definition at line 341 of file RNTupleModel.hxx.

◆ GetToken()

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

◆ IsBare()

bool ROOT::RNTupleModel::IsBare ( ) const
inline
See also
CreateBare()

Definition at line 339 of file RNTupleModel.hxx.

◆ IsExpired()

bool ROOT::RNTupleModel::IsExpired ( ) const
inline
See also
Expire()

Definition at line 335 of file RNTupleModel.hxx.

◆ IsFrozen()

bool ROOT::RNTupleModel::IsFrozen ( ) const
inline
See also
Freeze()

Definition at line 337 of file RNTupleModel.hxx.

◆ MakeField()

template<typename T >
std::shared_ptr< T > ROOT::RNTupleModel::MakeField ( std::string_view name,
std::string_view description = "" )
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 <vector>
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();
}
}
An RNTuple that gets filled with entries (data) and writes them to storage.
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())
Throws an exception if the model is null.
TPaveText * pt

Example: create a field with a description

auto hadronFlavour = model->MakeField<float>(
"hadronFlavour", "flavour from hadron ghost clustering"
);

Definition at line 253 of file RNTupleModel.hxx.

◆ operator=()

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

◆ RegisterSubfield()

void ROOT::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. Note that previously created entries won't have this subfield added to them.

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

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

Definition at line 368 of file RNTupleModel.cxx.

◆ SetDescription()

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

Definition at line 590 of file RNTupleModel.cxx.

◆ Unfreeze()

void ROOT::RNTupleModel::Unfreeze ( )

Transitions an RNTupleModel from the frozen state back to the building state, invalidating all previously created entries, re-enabling adding additional fields and disabling creating entries from it.

Unfreezing a model that is already in the building state is a no-op. Throws an RException if the model is in the expired state. See RNTupleModel for a more detailed explanation on the state transitions.

Definition at line 565 of file RNTupleModel.cxx.

Friends And Related Symbol Documentation

◆ Internal::GetFieldZeroOfModel

◆ Internal::GetProjectedFieldsOfModel

Member Data Documentation

◆ fDefaultEntry

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

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

Definition at line 167 of file RNTupleModel.hxx.

◆ fDescription

std::string ROOT::RNTupleModel::fDescription
private

Free text set by the user.

Definition at line 171 of file RNTupleModel.hxx.

◆ fFieldNames

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

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

Definition at line 169 of file RNTupleModel.hxx.

◆ fFieldZero

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

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

Definition at line 165 of file RNTupleModel.hxx.

◆ fModelId

std::uint64_t ROOT::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 178 of file RNTupleModel.hxx.

◆ fModelState

EState ROOT::RNTupleModel::fModelState = EState::kBuilding
private

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

Definition at line 182 of file RNTupleModel.hxx.

◆ fProjectedFields

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

The set of projected top-level fields.

Definition at line 173 of file RNTupleModel.hxx.

◆ fRegisteredSubfields

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

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

Definition at line 175 of file RNTupleModel.hxx.

◆ fSchemaId

std::uint64_t ROOT::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 180 of file RNTupleModel.hxx.

Libraries for ROOT::RNTupleModel:

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