Loading...
Searching...
No Matches
DataProvider Module

# Introduction to the DataProvider Module

The DataProvider module provides APIs for hierarchical data structures from arbitrary sources to be described, queried, introspected, and updated. It supports data providers supporting record-based APIs as well as request-reply semantics such as REST schemas or with SOAP messaging, as well as event-based data providers.

The data provider module supports high-performance reading (native or simulated searching, also with advanced search expression support) and writing as well as record creation, upserting, and transaction management for record-based data providers if supported by the underlying data provider implementation as well.

The Qore command-line program `qdp` provides a user-friendly interface to data provider functionality.

This module provides the following primary classes:

- AbstractDataField
- AbstractDataProcessor
- AbstractDataProvider
- AbstractDataProviderBulkOperation
- AbstractDataProviderBulkRecordInterface
- AbstractDataProviderFactory
- AbstractDataProviderRecordIterator
- DataProvider
- DataProviderBulkRecordIterator
- DataProviderPipeline
- DefaultBulkInserter
- DefaultBulkUpserter
- DefaultBulkRecordIterface
- DefaultRecordIterator
- QoreDataField

The following supporting type classes are also provided:

- AbstractDataProviderType
- DataProviderTypeCache
- HashDataType
- HashDeclDataType
- ListDataType
- NullDataProvider
- NullDataProviderFactory
- QoreBase64BinaryDataType
- QoreBase64BinaryOrNothingDataType
- QoreBinaryDataType
- QoreBinaryDataTypeBase
- QoreBinaryOrNothingDataType
- QoreBoolDataType
- QoreBoolDataTypeBase
- QoreBoolOrNothingDataType
- QoreDataType
- QoreDateDataType
- QoreDateDataTypeBase
- QoreDateOrNothingDataType
- QoreFloatDataType
- QoreFloatDataTypeBase
- QoreFloatOrNothingDataType
- QoreHashDataType
- QoreHexBinaryDataType
- QoreHexBinaryOrNothingDataType
- QoreIntDataType
- QoreIntDataTypeBase
- QoreIntOrNothingDataType
- QoreListDataType
- QoreNumberDataType
- QoreNumberDataTypeBase
- QoreNumberOrNothingDataType
- QoreSoftBinaryDataType
- QoreSoftBinaryNoNullDataType
- QoreSoftBinaryOrNothingDataType
- QoreSoftBoolDataType
- QoreSoftBoolNoNullDataType
- QoreSoftBoolOrNothingDataType
- QoreSoftDateDataType
- QoreSoftDateNoNullDataType
- QoreSoftDateOrNothingDataType
- QoreSoftFloatDataType
- QoreSoftFloatNoNullDataType
- QoreSoftFloatOrNothingDataType
- QoreSoftIntDataType
- QoreSoftIntNoNullDataType
- QoreSoftIntOrNothingDataType
- QoreSoftNumberDataType
- QoreSoftNumberNoNullDataType
- QoreSoftNumberOrNothingDataType
- QoreSoftStringDataType
- QoreSoftStringOrNothingDataType
- QoreStringDataType
- QoreStringDataTypeBase
- QoreStringOrNothingDataType

## Data Provider Modules

This module uses the `"QORE_DATA_PROVIDERS"` environment variable to register data provider modules. Each data provider registration module must provide one of the following two public functions.

### Data Provider Dynamic Discovery

Implement a public function with the following signature to support dynamic discovery of data providers:

# returns a hash of connection provider factory names to module names
public hash<string, string> sub get_data_provider_map() { ... }

### Data Provider Type Dynamic Discovery

Implement a public function with the following signature to support dynamic discovery of data provider types:

# returns a hash of type prefix paths (ex: \c "qore/sftp") to module names
public hash<string, string> sub get_type_provider_map() { ... }

Data provider registration modules declared in the `"QORE_DATA_PROVIDERS"` environment variable must be separated by the platform-specific PathSep character as in the following examples:

Unix Example

      export QORE_DATA_PROVIDERS=MyConnectionProvider:OtherConnectionProvider

Windows CMD.EXE Example

      set QORE_DATA_PROVIDERS=MyConnectionProvider;OtherConnectionProvider

Windows PowerShell Example

      $env:QORE_DATA_PROVIDERS="MyConnectionProvider;OtherConnectionProvider"

# Data Provider Pipelines

Data provider pipelines allow for efficient processing of record or other data in multiple streams and, if desired, in multiple threads.

Pipeline data can be any data type except a list, as list values are interpreted as multiple output values in pipeline procesor objects.

# Data Provider Pipeline Bulk Processing

Bulk processing is processing of record data that is in "hash of lists" form, so a single hash, where each key value is a list of values for that key. Records can be formed as by taking each hash key and then using each list value in order for the values of each record. In case a key is assigned a single value instead of a list, it's interpreted as constant value for all records. Note that the first key value for bulk data must be a list of values in order for the bulk data to be properly detected.

Each pipeline processor element must declare if it is compatible with bulk processing by implementing the AbstractDataProcessor::supportsBulkApiImpl() method.

If a processor does not support the bulk API, but bulk data is submitted, then the bulk data will be separately iterated, and each record will be passed separately to the processor with a significant performance penalty when processing large volumes of data.

# Release Notes

## DataProvider v2.7.4

- added `allowed_values` to field data info (issue 4762)

## DataProvider v2.7.3

- added missing `base64binary` and `hexbinary` type support (issue 4732)

## DataProvider v2.7.2

- fixed bugs handling null hash assignments with fields with default values in HashDataType (issue 4715)

## DataProvider v2.7.1

- added DataProvider::getFactoryObjectWithTemplate() and AbstractDataProviderFactory::createWithTemplate() to allow data providers to be created from factories with template arguments (issue 4624)
- `AbstractDataProvider::search*`() fails with record-based data providers that do not provide a record definition (issue 4624)
- `AbstractDataProvider::search*`() methods fail with an empty `where` hash argument (issue 4622)

## DataProvider v2.7

- fixed a bug accepting the element type in SoftListDataType (issue 4603)
- added child capability support to data provider summary info (issue 4576)

## DataProvider v2.6

- added child capability support to data provider info (issue 4572)

## DataProvider v2.5

- implemented support for the observer pattern / event API (issue 4557)

## DataProvider v2.4

- allow data providers to be introspected with additional information about children (issue 4543)

## DataProvider v2.3

- updated to use new generic expression support for searches (issue 4538)
- addded support for data provider options to support default values (issue 4532)
- addded `search_operators` to the data provider response to report supported search operators (issue 4528)
- fixed a type error in `DataProvider::search*`() calls with an empty `where` hash argument (issue 4511)

## DataProvider v2.2.1

- made it possible to determine the default field type in HashDataType (issue 4491)

## DataProvider v2.2

- added an attribute to factories to indicate if any children can support the request-response pattern (issue 4486)
- added the DTT_ClientOnly type tag constant (issue 4477)

## DataProvider v2.1.2

- fixed a bug where DataProvider types based on string that accept multiple input types with conversions but are not soft types threw spurious errors at runtime with non-string types (issue 4471)
- added the `desc` key supporting a markdown description to data provider info (issue 4465)
- fixed a bug where hash types incorrectly claimed compatibility with incompatible hashes (issue 4463)

## DataProvider v2.1.1

- fixed a type error iterating data in DefaultBulkRecordIterface (issue 4457)

## DataProvider v2.1

- added support for tags on data provider types (i.e. AbstractDataProviderType) (issue 4442)
- fixed data provider factory info to provide info about the actual data provider factory instead of only provider info (issue 4438)
- added "from example" APIs to data provider factories:
  - AbstractDataProviderFactory::getProviderFromExample()
  - AbstractDataProviderFactory::getExampleProviderRecordOutput() (issue 4430)
- added generic search capabilities to data providers with no native search capabilities (issue 4430)

## DataProvider v2.0

- added a logger to the AbstractDataProvider class to enable logging (issue 4409)
- added support for creating, reading, updating, and modifying data providers (issue 4395)

## DataProvider v1.3

- added DataProviderTypeCache::listParentTypes() to allow a list of parent types to be returned (issue 4385)

## DataProvider v1.2.2

- added support for starting a transaction with DataProviders that support transaction management (issue 4346)

## DataProvider v1.2.1

- return the `base_type` key in input type info in getInputInfo (issue 4311)

## DataProvider v1.2

- greatly improved dataprovider and type acquisition speed from clients requiring initialization from the environment (issue 4305)

## DataProvider v1.1

- the DataProvider::DefaultRecordIterator class supports the `limit` search option

## DataProvider v1.0.6

- fixed a bug where the data type was not supported correctly as a data provider type (issue 4232)

## DataProvider v1.0.5

- fixed an issue where it was not possible for pipeline to flush any pending data or to perform reset or purge operations when pipeline processing is complete; for this the AbstractDataProcessor::flush() and AbstractDataProcessor::flushImpl() methods were implemented (issue 4107)

## DataProvider v1.0.4

- fixed type-handling bugs handling data provider options (issue 4062)

## DataProvider v1.0.3

- fixed bugs in the default return value for AbstractDataProcessor::getExpectedType() and AbstractDataProcessor::getReturnType() (issue 4043)

## DataProvider v1.0.2

- fixed a bug where HashDataType would not enforce fields or field types when checking for type and value compatibility (issue 4037)
- added new Qore base types to the data type hierarchy
- implemented the following classes:
  - AbstractDataProcessor
  - DataProviderBulkRecordIterator
  - DataProviderPipeline
    (issue 3876)
- added `DUPLICATE-RECORD` exception documentation for AbstractDataProvider::createRecord()
- updated to allow data provider type attributes to appear as children in the type hierarchy (issue 4015)

## DataProvider v1.0.1

- implemented callbacks to allow for dynamic elements of request-response data providers (such as URI paths) to be resolved at runtime (issue 3838)
- AbstractDataProviderType and AbstractDataField classes made serializable (issue 3809)
- implemented the DataProviderTypeCache class to encapsulate reusable type caching logic (issue 3810)

## DataProvider v1.0

- initial release of the module