maps from source to target tables with exactly the same structure More...

#include <TableMapper.qm.dox.h>

Inheritance diagram for TableMapper::InboundIdentityTableMapper:

Public Member Methods
	constructor (SqlUtil::AbstractTable target, hash< auto > mapv={}, *hash< auto > opts)
	builds the object based on an optional hash providing field mappings, data constraints, and optionally custom mapping logic More...

	constructor (SqlUtil::Table target, hash< auto > mapv={}, *hash< auto > opts)
	builds the object based on an optional hash providing field mappings, data constraints, and optionally custom mapping logic More...

Public Member Methods inherited from TableMapper::InboundTableMapper
nothing	commit ()
	flushes any queued data and commits the transaction

	constructor (SqlUtil::AbstractTable target, hash< auto > mapv, *hash< auto > opts)
	builds the object based on a hash providing field mappings, data constraints, and optionally custom mapping logic More...

	constructor (SqlUtil::Table target, hash< auto > mapv, *hash< auto > opts)
	builds the object based on a hash providing field mappings, data constraints, and optionally custom mapping logic More...

	destructor ()
	throws an exception if there is data pending in the block cache More...

	discard ()
	discards any buffered batched data; this method should be called after using the batch APIs (queueData()) and an error occurs More...

*hash< auto >	flush ()
	flushes any remaining batched data to the database; this method should always be called before committing the transaction or destroying the object More...

Qore::SQL::AbstractDatasource	getDatasource ()
	returns the AbstractDatasource object associated with this object

*list< hash< auto > >	getReturning ()
	returns a list argument for the SqlUtil "returning" option, if applicable

SqlUtil::AbstractTable	getTable ()
	returns the underlying SqlUtil::AbstractTable object

string	getTableName ()
	returns the table name

hash< string, hash< MapperOptionInfo > >	getUserOptions ()
	returns mapper options useful for users

hash< auto >	insertRow (hash< auto > rec)
	inserts or upserts a row into the target table based on a mapped input record; does not commit the transaction More...

deprecated hash< auto >	insertRowNoCommit (hash< auto > rec)
	Plain alias to insertRow(). Obsolete. Do not use.

TableMapper::InboundTableMapperIterator	iterator (Qore::AbstractIterator i)
	returns an iterator for the current object More...

	logOutput (hash< auto > h)
	ignore logging from Mapper since we may have to log sequence values; output logged manually in insertRow()

hash< auto >	optionKeys ()
	returns a list of valid constructor options for this class (can be overridden in subclasses) More...

*hash< auto >	queueData (hash< auto > rec, *hash< auto > crec)
	inserts/upserts a row (or a set of rows, in case a hash of lists is passed) into the block buffer based on a mapped input record; the block buffer is flushed to the DB if the buffer size reaches the limit defined by the `"insert_block"` option; does not commit the transaction More...

*hash< auto >	queueData (list< auto > l, *hash< auto > crec)
	inserts/upserts a set of rows (list of hashes representing input records) into the block buffer based on a mapped input record; the block buffer is flushed to the DB if the buffer size reaches the limit defined by the `"insert_block"` option; does not commit the transaction More...

*hash< auto >	queueData (Qore::AbstractIterator iter, *hash< auto > crec)
	inserts/upserts a set of rows (from an iterator that returns hashes as values where each hash value represents an input record) into the block buffer based on a mapped input record; the block buffer is flushed to the DB if the buffer size reaches the limit defined by the `"insert_block"` option; does not commit the transaction More...

nothing	rollback ()
	discards any queued data and rolls back the transaction

	setRowCode (*code rowc)
	sets a closure or call reference that will be called when data has been sent to the database and all output data is available; must accept a hash argument that represents the data written to the database including any output arguments. This code will be reset, once the transaction is commited. More...

hash< string, bool >	validKeys ()
	returns a list of valid field keys for this class (can be overridden in subclasses) More...

Private Member Methods
hash< string, AbstractDataField >	getInputRecord (SqlUtil::AbstractTable table, *hash< auto > opts)
	returns a description of the input record based on the AbstractTable source

	init (hash< auto > mapv, *hash< auto > opts)
	common constructor initialization

Private Member Methods inherited from TableMapper::InboundTableMapper
	checkMapField (string k, reference< auto > fh)
	perform per-field pre-processing on the passed map in the constructor More...

	error (string fmt)
	prepends the datasource description to the error string and calls Mapper::error()

	error2 (string ex, string fmt)
	prepends the datasource description to the error description and calls Mapper::error2()

*hash< auto >	flushIntern (bool force_flush)

	init (hash< auto > mapv, *hash< auto > opts)
	common constructor initialization

bool	isMapperConstant ()

auto	mapFieldType (string key, hash< auto > mapping, AbstractDataProviderType type, auto value, hash< auto > rec)
	performs type handling

*hash< auto >	queueDataIntern (hash< auto > rec)
	inserts a row into the block buffer based on a mapped input record; does not commit the transaction More...

hash	record2Batch (hash h)

Additional Inherited Members
Static Public Member Methods inherited from TableMapper::InboundTableMapper
static deprecated nothing	addBatchToBatch (reference< hash > hb, reference x1, hash batch, *reference x2)
	adds a batch (hash of lists) to another batch (in-place) More...

static nothing	addBatchToBatch (reference< hash< auto > > hb, hash< auto > batch)

static *hash< string, AbstractDataField >	getOutputRecord (string mapper_name, AbstractTable table, hash< auto > opts, hash< SqlUtilDataTypeOptionInfo > field_opts, *hash< auto > mapv)
	returns a description of the output record based on the AbstractTable target

Public Attributes inherited from TableMapper::InboundTableMapper
const	OptionDefaults
	default option values

const	OptionKeys = ...
	option keys for this object

const	UserOptions
	User options.

Private Attributes inherited from TableMapper::InboundTableMapper
SqlUtil::AbstractDatabase	db
	the target Database object in case sequence value need to be acquired

bool	has_returning
	if the AbstractTable object supports the "returning" clause

hash	hbuf
	buffer for bulk DML

*int	hbuf_size
	size of the batch in hbuf as if returned from getRecListSize()

int	insert_block
	bulk DML block size (also valid for upserts despite the name)

list	out_args = ()
	extra arguments for sequence output binds

list	ret_args = ()
	"returning" arguments for sequences

*code	rowcode
	per-row Closures or Call References for batch inserts/upserts

Qore::SQL::AbstractSQLStatement	stmt
	statement for inserts/upserts

SqlUtil::AbstractTable	table
	the target table object

bool	unstable_input = False
	"unstable input" option for non-optimized inserts/upserts (~33% performance reduction in insert/upsert speed)

bool	upsert = False
	upsert flag

*code	upsert_code
	closure used for upserting

*int	upsert_strategy
	upsert strategy option

Detailed Description

maps from source to target tables with exactly the same structure

Member Function Documentation

◆ constructor() [1/2]

TableMapper::InboundIdentityTableMapper::constructor	(	SqlUtil::AbstractTable	target,
		hash< auto >	mapv = `{}`,
		*hash< auto >	opts
	)

builds the object based on an optional hash providing field mappings, data constraints, and optionally custom mapping logic

The target table is also scanned using SqlUtil and column definitions are used to update the target record specification, also if there are any columns with NOT NULL constraints and no default value, mapping, or constant value, then a MAP-ERROR exception is thrown

Example:: const DbMapper = (

"id": ("sequence": "seq_inventory_example"),

);

InboundIdentityTableMapper mapper(table, DbMapper);

Parameters

target	the target table object
mapv	a hash providing field mappings; each hash key is the name of the output field; each value is either True (meaning no translations are done; the data is copied 1:1) or a hash describing the mapping; see Mapper Specification Format for detailed documentation for this option
opts	an optional hash of options for the mapper; see Mapper Options for a description of valid mapper options plus the following options specific to this object: `"unstable_input"`: set this option to True (default False) if the input passed to the mapper is unstable, meaning that different hash keys or a different hash key order can be passed as input data in each call to insertRow(); if this option is set, then insert speed will be reduced by about 33%; when this option is not set, an optimized insert approach is used which allows for better performance `"insert_block"`: for DB drivers supporting bulk DML (for use with the queueData(), flush(), and discard() methods), the number of rows inserted at once (default: 1000, only used when `"unstable_input"` is False) and bulk inserts are supported in the table object; see InboundTableMapper Bulk Insert API for more information

Exceptions

MAP-ERROR	the map hash has a logical error (ex: `"trunc"` key given without `"maxlen"`, invalid map key)
TABLE-ERROR	the table includes a column using an unknown native data type

◆ constructor() [2/2]

TableMapper::InboundIdentityTableMapper::constructor	(	SqlUtil::Table	target,
		hash< auto >	mapv = `{}`,
		*hash< auto >	opts
	)

builds the object based on an optional hash providing field mappings, data constraints, and optionally custom mapping logic

The target table is also scanned using SqlUtil and column definitions are used to update the target record specification, also if there are any columns with NOT NULL constraints and no default value, mapping, or constant value, then a MAP-ERROR exception is thrown

Example:: const DbMapper = (

"id": ("sequence": "seq_inventory_example"),

);

InboundIdentityTableMapper mapper(table, DbMapper);

Parameters

target	the target table object
mapv	a optional hash providing overrides for the default 1:1 input to output field mappings; each hash key is the name in lower case of the output column in the target table; each value is either True (meaning no translations are done; the data is copied 1:1) or a hash describing the mapping; see Mapper Specification Format for detailed documentation for this option
opts	an optional hash of options for the mapper; see Mapper Options for a description of valid mapper options plus the following options specific to this object: `"unstable_input"`: set this option to True (default False) if the input passed to the mapper is unstable, meaning that different hash keys or a different hash key order can be passed as input data in each call to insertRow(); if this option is set, then insert speed will be reduced by about 33%; when this option is not set, an optimized insert approach is used which allows for better performance `"insert_block"`: for DB drivers supporting bulk DML (for use with the queueData(), flush(), and discard() methods), the number of rows inserted at once (default: 1000, only used when `"unstable_input"` is False) and bulk inserts are supported in the table object; see InboundTableMapper Bulk Insert API for more information

Exceptions

MAP-ERROR the map hash has a logical error (ex: "trunc" key given without "maxlen", invalid map key)

Public Member Methods

Private Member Methods

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ constructor() [1/2]

◆ constructor() [2/2]