Developer Guide and Reference

  • 2021.1
  • 12/04/2020
  • Public Content
Contents

Tables

This section describes the types related to the dm table concept.
Type
Description
A common implementation of the table concept. Base class for other table types.
An implementation of dm table metadata concept.
An enumeration of data layouts used to store contiguous data blocks inside the table.
An enumeration of feature types used in oneDAL to define set of available operations onto the data.

Requirements on table types

Each implementation of dm table concept:
  1. Follows the definition of the dm table concept and its restrictions (e.g., immutability).
  2. Is derived from the
    oneapi::dal::table
    class. The behavior of this class can be extended, but cannot be weaken.
  3. Every new
    oneapi::dal::table
    sub-type defines a unique id number - the “kind” that represents objects of that type in runtime.
The following listing provides an example of table API to illustrate table kinds and copy-assignment operation:
using namespace onedal; // Creating homogen_table sub-type. dal::homogen_table table1 = homogen_table::wrap(queue, data_ptr, row_count, column_count); // table1 and table2 share the same data (no data copy is performed) dal::table table2 = table1; // Creating an empty table dal::table table3; std::cout << table1.get_kind() == table2.get_kind() << std::endl; // true std::cout << homogen_table::kind() == table2.get_kind() << std::endl; // true std::cout << table2.get_kind() == table3.get_kind() << std::endl; // false // Referring table3 to the table2. table3 = table2; std::cout << table2.get_kind() == table3.get_kind() << std::endl; // true

Table types

oneDAL defines a set of classes that implement the dm table concept for a specific data format:
Table type
Description
A dense table that contains contiguoushomogeneous data.

Programming interface

All types and functions in this section are declared in the
oneapi::dal
namespace and be available via inclusion of the
oneapi/dal/table/common.hpp
header file.
Table
A base implementation of the dm table concept. The
table
type and all of its subtypes are reference-counted:
  1. The instance stores a pointer to table implementation that holds all property values and data
  2. The reference count indicating how many table objects refer to the same implementation.
  3. The table increments the reference count for it to be equal to the number of table objects sharing the same implementation.
  4. The table decrements the reference count when the table goes out of the scope. If the reference count is zero, the table frees its implementation.
class
table
Constructors
table
()
An empty table constructor: creates the table instance with zero number of rows and columns. Implementation is set to the special “empty” object that returns all the property values set to default (see Properties section).
table
(
const
table&) = default
Creates a new table instance that shares the implementation with another one.
table
(table&&)
Creates a new table instance and moves implementation from another one into it.
template<typename
Impl
, typename
ImplType
= std::decay_t<Impl>, typename
None
= std::enable_if_t<detail::is_table_impl_v<ImplType> && !std::is_base_of_v<table, ImplType>>>
table
(Impl &&
impl
)
Public Methods
table &
operator=
(
const
table&) = default
Replaces the implementation by another one.
table &
operator=
(table&&)
Swaps the implementation of this object and another one.
bool
has_data
()
const
noexcept
Indicates whether a table contains non-zero number of rows and columns.
Properties
std::int64_t
column_count
= 0
The number of columns in the table.
Getter & Setter


std::int64_t get_column_count() const

std::int64_t
row_count
= 0
The number of rows in the table.
Getter & Setter


std::int64_t get_row_count() const

const
table_metadata &
metadata
= table_metadata()
The metadata object that holds additional information about the data within the table.
Getter & Setter


const table_metadata & get_metadata() const

std::int64_t
kind
= empty_table_kind
The runtime id of the table type. Each table sub-type has its unique
kind
. An empty table (see the default constructor) has a unique
kind
value as well.
Getter & Setter


std::int64_t get_kind() const

data_layout
data_layout
= data_layout::unknown
The layout of the data within the table.
Getter & Setter


data_layout get_data_layout() const

Table metadata
An implementation of the dm table metadata concept. Holds additional information about data within the table. The objects of
table_metadata
are reference-counted.
class
table_metadata
Constructors
table_metadata
()
Creates the metadata instance without information about the features. The
feature_count
sshould be set to zero. The
data_type
and
feature_type
properties should not be initialized.
table_metadata
(
const
array<data_type> &
dtypes
,
const
array<feature_type> &
ftypes
)
Creates the metadata instance from external information about the data types and the feature types.
Parameters
  • dtypes
    – The data types of the features. Assigned into the
    data_type
    property.
  • ftypes
    – The feature types. Assigned into the
    feature_type
    property.
Preconditions


dtypes.get_count() == ftypes.get_count()

Properties
std::int64_t
feature_count
The number of features that metadata contains information about.
Getter & Setter


std::int64_t get_feature_count() const

const
feature_type &
feature_type
Feature types in the metadata object. Should be within the range
[0, feature_count)
.
Getter & Setter


const feature_type & get_feature_type(std::int64_t feature_index) const

const
data_type &
data_type
Data types of the features in the metadata object. Should be within the range
[0, feature_count)
.
Getter & Setter


const data_type & get_data_type(std::int64_t feature_index) const

Data layout
An implementation of the data layout concept.
enum class data_layout { unknown, row_major, column_major };
data_layout::unknown Represents the :capterm:`data layout` that is undefined or unknown at this moment. data_layout::row_major The data block elements are stored in raw-major layout. data_layout::column_major The data block elements are stored in column_major layout.
Feature type
An implementation of the logical data types.
enum class feature_type { nominal, ordinal, interval, ratio };
feature_type::nominal Represents the type of :capterm:`Nominal feature`. feature_type::ordinal Represents the type of :capterm:`Ordinal feature`. feature_type::interval Represents the type of :capterm:`Interval feature`. feature_type::ratio Represents the type of :capterm:`Ratio feature`.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.