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 satisfies the following requirements:

  • An operation accepts three parameters in the following order:

    • The SYCL* queue object.

    • The data source.

    • The args object.

  • An operation returns the result object.

  • The read_args_t and read_result_t alias templates is 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 Types

Data source type

Description

CSV data source

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