Data Sources#

This section describes the types related to the data source concept.

Read#

Read operation is a function that transforms a data source and other arguments represented via an args object to a result object. The operation is responsible for:

  • Executing all of the data retrieval and transformation routines of the data source.

  • Passing a SYCL* queue to the data retrieval and transformation routines.

Read operation definition#

The following code sample shows the declaration for a read operation.

namespace oneapi::dal {

template <typename Object, typename DataSource>
using read_args_t = /* implementation defined */;

template <typename Object, typename DataSource>
using read_result_t = Object;

template <typename Object, typename DataSource>
read_result_t<Object, DataSource> read(
   sycl::queue& queue,
   const DataSource& data_source,
   const read_args_t<Object, DataSource>& args);

} // namespace oneapi::dal

Each operation shall satisfy the following requirements:

  • An operation shall accept three parameters in the following order:

    • The SYCL* queue object.

    • The data source.

    • The args object.

  • An operation shall return the result object.

  • The read_args_t and read_result_t alias templates shall be used for inference of the args and return types.

Read operation shortcuts#

In order to make the code on user side less verbose, oneDAL defines the following overloaded functions called shortcuts for a read operation in addition to the general one described in section Read operation definition.

  • A shortcut for execution on host. Performs the same operation as the general function on host, but does not require passing the queue explicitly.

    template <typename Object, typename DataSource>
read_result_t<Object, DataSource> read(
   const DataSource& data_source,
   const read_args_t<Object, DataSource>& args);

  • A shortcut that allows omitting explicit args creation.

    template <typename Object, typename DataSource, typename... Args>
read_result_t<Object, DataSource> read(
   sycl::queue& queue,
   const DataSource& data_source,
   Args&&... args);

  • A shortcut that allows omitting explicit queue and args creation. This is a combination of two previous shortcuts.

    template <typename Object, typename DataSource, typename... Args>
read_result_t<Object, DataSource> read(
   const DataSource& data_source,
   Args&&... args);

Args#

  • The string %DATA_SOURCE% should be substituted with the name of the data source, for example, csv.

  • %PROPERTY_NAME% and %PROPERTY_TYPE% should be substituted with the name and the type of one of the data source args properties.

namespace oneapi::dal::%DATA_SOURCE% {

template <typename Object, typename DataSource>
class read_args {
public:
   read_args(
      const %PROPERTY_TYPE_1%& property_name_1,
      const %PROPERTY_TYPE_2%& property_name_2,
      /* more properties */
   )
   /* Getter & Setter for the property called `%PROPERTY_NAME_1%` */
   descriptor& set_%PROPERTY_NAME_1%(%PROPERTY_TYPE_1% value);
   %PROPERTY_TYPE_1% get_%PROPERTY_NAME_1%() const;
   /* Getter & Setter for the property called `%PROPERTY_NAME_2%` */
   descriptor& set_%PROPERTY_NAME_2%(%PROPERTY_TYPE_2% value);
   %PROPERTY_TYPE_2% get_%PROPERTY_NAME_2%() const;
   /* more properties */
};
} // namespace oneapi::dal::%DATA_SOURCE%

Result#

The result of a read operation is an instance of an in-memory object with Object type.

Data Source Types#

oneDAL defines a set of classes.

Data source type

Description

CSV data source

Data source that allows reading data from a text file into a table.