Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
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.

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 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, std::function< std::string(const std::string &)> mapping)
 Adds a top-level field based on existing fields.
 
std::unique_ptr< RNTupleModelClone () const
 
std::unique_ptr< REntryCreateBareEntry () 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< REntryCreateEntry () const
 
std::size_t EstimateWriteMemoryUsage (const RNTupleWriteOptions &options=RNTupleWriteOptions()) const
 Estimate the memory usage for this model during writing.
 
void Freeze ()
 
REntryGetDefaultEntry ()
 
const REntryGetDefaultEntry () const
 
std::string GetDescription () const
 
const RFieldBaseGetField (std::string_view fieldName) const
 
RFieldZeroGetFieldZero ()
 Non-const access to the root field is used to commit clusters during writing and to set the on-disk field IDs when connecting a model to a page source or sink.
 
const RFieldZeroGetFieldZero () const
 
std::uint64_t GetModelId () const
 
const RProjectedFieldsGetProjectedFields () 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 IsFrozen () const
 
std::shared_ptr< RNTupleCollectionWriterMakeCollection (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.
 
RNTupleModeloperator= (const RNTupleModel &)=delete
 
void SetDescription (std::string_view description)
 
void Unfreeze ()
 

Static Public Member Functions

static std::unique_ptr< RNTupleModelCreate ()
 
static std::unique_ptr< RNTupleModelCreate (std::unique_ptr< RFieldZero > fieldZero)
 
static std::unique_ptr< RNTupleModelCreateBare ()
 A bare model has no default entry.
 
static std::unique_ptr< RNTupleModelCreateBare (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.
 
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< REntryfDefaultEntry
 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< RFieldZerofFieldZero
 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< RProjectedFieldsfProjectedFields
 The set of projected top-level fields.
 

Friends

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

#include <ROOT/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 298 of file RNTupleModel.cxx.

◆ AddProjectedField()

ROOT::Experimental::RResult< void > ROOT::Experimental::RNTupleModel::AddProjectedField ( std::unique_ptr< RFieldBase field,
std::function< std::string(const std::string &)>  mapping 
)

Adds a top-level field based on existing fields.

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. Projected fields can only be used for models used to write data.

Definition at line 312 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 406 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 433 of file RNTupleModel.cxx.

◆ CreateEntry()

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

Definition at line 394 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 466 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 277 of file RNTupleModel.cxx.

◆ Freeze()

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

Definition at line 455 of file RNTupleModel.cxx.

◆ GetDefaultEntry() [1/2]

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

Definition at line 380 of file RNTupleModel.cxx.

◆ GetDefaultEntry() [2/2]

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

Definition at line 386 of file RNTupleModel.cxx.

◆ GetDescription()

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

Definition at line 338 of file RNTupleModel.hxx.

◆ GetField()

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

Definition at line 371 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 set the on-disk field IDs when connecting a model to a page source or sink.

Definition at line 364 of file RNTupleModel.cxx.

◆ GetFieldZero() [2/2]

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

Definition at line 335 of file RNTupleModel.hxx.

◆ GetModelId()

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

Definition at line 312 of file RNTupleModel.hxx.

◆ GetProjectedFields()

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

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

◆ IsFrozen()

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

Definition at line 311 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 342 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 <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();
}
}
The RNTupleModel encapulates the schema of an ntuple.
static std::unique_ptr< RNTupleModel > Create()
An RNTuple that gets filled with entries (data) and writes them to storage.
static std::unique_ptr< RNTupleWriter > Recreate(std::unique_ptr< RNTupleModel > model, std::string_view ntupleName, std::string_view storage, const RNTupleWriteOptions &options=RNTupleWriteOptions())
Throws an exception if the model is null.
TPaveText * pt

Example: create a field with an initial value

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

auto model = RNTupleModel::Create();
auto hadronFlavour = model->MakeField<float>({
"hadronFlavour", "flavour from hadron ghost clustering"
});

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

◆ Unfreeze()

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

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

◆ fDescription

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

Free text set by the user.

Definition at line 200 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 198 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 194 of file RNTupleModel.hxx.

◆ fIsFrozen

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

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

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

◆ fProjectedFields

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

The set of projected top-level fields.

Definition at line 202 of file RNTupleModel.hxx.

Libraries for ROOT::Experimental::RNTupleModel:

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