Qore TableMapper Module Reference 1.3
Loading...
Searching...
No Matches
TableMapper.qm.dox.h
1// -*- mode: c++; indent-tabs-mode: nil -*-
3
4/* TableMapper.qm Copyright 2014 - 2024 Qore Technologies, s.r.o.
5
6 Permission is hereby granted, free of charge, to any person obtaining a
7 copy of this software and associated documentation files (the "Software"),
8 to deal in the Software without restriction, including without limitation
9 the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 and/or sell copies of the Software, and to permit persons to whom the
11 Software is furnished to do so, subject to the following conditions:
12
13 The above copyright notice and this permission notice shall be included in
14 all copies or substantial portions of the Software.
15
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22 DEALINGS IN THE SOFTWARE.
23*/
24
25// minimum Qore version
26
27// require type definitions everywhere
28
29// enable all warnings
30
31// don't use "$" signs for variables and class members, assume local variable scope
32
33// requires the Mapper module
34// requires the SqlUtil module
35
36
271namespace TableMapper {
274
275public:
277 const OptionKeys = ...;
278
279
281 const UserOptions = ...;
282
283
285 const OptionDefaults = ...;
286
287
288protected:
291
294
297
299 list ret_args = ();
300
302 list out_args = ();
303
305 bool unstable_input = False;
306
309
312
314 hash hbuf;
316 /* FIXME would be nice to have hbuf with hbuf_size in a class, but there are performance considerations.
317 */
319
321 *code rowcode;
322
324 bool upsert = False;
325
328
331
332public:
333
335
368 constructor(SqlUtil::Table target, hash<auto> mapv, *hash<auto> opts);
369
370
372
405 constructor(SqlUtil::AbstractTable target, hash<auto> mapv, *hash<auto> opts);
406
407
409
412
413
415 static *hash<string, AbstractDataField> getOutputRecord(string mapper_name, AbstractTable table, *hash<auto> opts, *hash<SqlUtilDataTypeOptionInfo> field_opts, *hash<auto> mapv);
416
418protected:
419 init(hash<auto> mapv, *hash<auto> opts);
420public:
421
422
424protected:
425 auto mapFieldType(string key, hash<auto> mapping, AbstractDataProviderType type, auto value, hash<auto> rec);
426public:
427
428
430
433protected:
434 checkMapField(string k, reference<auto> fh);
435public:
436
437
439
441 hash<string, bool> validKeys();
442
443
445
447 hash<auto> optionKeys();
448
449
451 hash<string, hash<MapperOptionInfo>> getUserOptions();
452
453
455
465 hash<auto> insertRow(hash<auto> rec);
466
467
469
481 setRowCode(*code rowc);
482
483
485
567 *hash<auto> queueData(hash<auto> rec, *hash<auto> crec);
568
569
571
607 *hash<auto> queueData(Qore::AbstractIterator iter, *hash<auto> crec);
608
609
611
646 *hash<auto> queueData(list<auto> l, *hash<auto> crec);
647
648
650
665protected:
666 *hash<auto> queueDataIntern(hash<auto> rec);
667public:
668
669
674protected:
675 hash record2Batch(hash h);
676public:
677
678
682protected:
684public:
685
686
692 static nothing addBatchToBatch(reference<hash<auto>> hb, hash<auto> batch);
693
695
697 deprecated static nothing addBatchToBatch(reference<hash> hb, reference x1, hash batch, *reference x2);
698
700
723 *hash<auto> flush();
724
725
727
749
750
760 // return nothing if nothing needs to be flushed
761protected:
762 *hash<auto> flushIntern(bool force_flush);
763public:
764
765
767 *list<hash<auto>> getReturning();
768
769
771 logOutput(hash<auto> h);
772
773
775
781
782
784 deprecated hash<auto> insertRowNoCommit(hash<auto> rec);
785
787 nothing commit();
788
789
791 nothing rollback();
792
793
795 string getTableName();
796
797
800
801
804
805
807protected:
808 error(string fmt, ...);
809public:
810
811
813protected:
814 error2(string ex, string fmt, ...);
815public:
816
817 };
818
821
822public:
824
843 constructor(SqlUtil::Table target, hash<auto> mapv = {}, *hash<auto> opts) ;
844
845
847
867 constructor(SqlUtil::AbstractTable target, hash<auto> mapv = {}, *hash<auto> opts) ;
868
869
871protected:
872 init(hash<auto> mapv, *hash<auto> opts);
873public:
874
875
877protected:
878 hash<string, AbstractDataField> getInputRecord(SqlUtil::AbstractTable table, *hash<auto> opts);
879public:
880
881 };
882
885
886public:
887
888protected:
891
894
896 int cnt = 0;
897
899 hash<auto> val;
900
901public:
902
904
911
912
914
942 constructor(Qore::AbstractIterator i, SqlUtil::Table target, hash<auto> mapv, *hash<auto> opts, int commit_limit = 0) ;
943
944
946
974 constructor(Qore::AbstractIterator i, SqlUtil::AbstractTable target, hash<auto> mapv, *hash<auto> opts, int commit_limit = 0) ;
975
976
978
1002
1003
1005 hash<auto> getValue();
1006
1007
1009
1013 bool next();
1014
1015
1018
1019
1021 nothing commit();
1022
1023
1025 nothing rollback();
1026
1027
1030
1031
1033
1036
1037
1039
1042
1043
1046
1047
1049
1060 setRuntime(string key, auto value);
1061
1062
1064
1074 setRuntime(hash<auto> runtime);
1075
1076
1078
1088 replaceRuntime(*hash<auto> runtime);
1089
1090
1092
1103 auto getRuntime(string key);
1104
1105 };
1106
1108
1113
1114public:
1115
1116protected:
1119
1120public:
1121
1123
1126
1127
1129
1136 constructor(SqlUtil::AbstractTable table, hash<auto> sh, hash<auto> mapv, *hash<auto> opts) ;
1137
1138
1140
1147 constructor(SqlUtil::Table table, hash<auto> sh, hash<auto> mapv, *hash<auto> opts) ;
1148
1149
1151
1155 constructor(Qore::SQL::AbstractSQLStatement stmt, hash<auto> mapv, *hash<auto> opts) ;
1156
1157
1158protected:
1159 setup(hash<auto> mapv, *hash<auto> opts);
1160public:
1161
1162
1164 hash<auto> getValue();
1165
1166
1168
1171
1172
1174
1177
1178
1180 bool hasBulk();
1181
1182
1184
1188 list<auto> mapBulk(int size);
1189
1190
1192
1203 setRuntime(string key, auto value);
1204
1205
1207
1217 setRuntime(hash<auto> runtime);
1218
1219
1221
1231 replaceRuntime(*hash<auto> runtime);
1232
1233
1235
1246 auto getRuntime(string key);
1247
1248 }; // class SqlStatementMapperIterator
1249
1252
1253public:
1255 const OptionKeys = ...;
1256
1257
1259 const OptionDefaults = ...;
1260
1261
1262protected:
1263 // internal SQLStatement
1264 AbstractSQLStatement m_stmt;
1265 // a select_block size. Taken from options
1266 int select_block;
1267 // original option hash
1268 *hash<auto> m_orig_opts;
1269
1270public:
1271
1273
1283 constructor(hash<auto> mapv, *hash<auto> opts);
1284
1285
1287
1289 hash<auto> optionKeys();
1290
1291
1293 hash<string, hash<MapperOptionInfo>> getUserOptions();
1294
1295
1298
1299
1302
1303
1306
1308protected:
1309 abstract initOptions(reference<hash> opts);
1310public:
1311
1313protected:
1314 abstract initStatement();
1315public:
1316
1318
1324
1325
1327
1330
1331
1333
1339
1340
1342
1351 *hash<string, auto> getData();
1352
1353
1355
1363 *list<auto> getDataRows();
1364
1365
1367protected:
1368 static *hash<string, AbstractDataField> getInputRecordFromStmt(AbstractSQLStatement stmt, *hash<auto> input);
1369public:
1370
1371 }; // AbstractSqlStatementOutboundMapper
1372
1375
1376public:
1377protected:
1378 // the target table object
1379 SqlUtil::AbstractTable m_table;
1380 // SqlUtil select hash
1381 *hash m_sh;
1382
1384 const OptionKeys = ...;
1385
1386
1388 const UserOptions = ...;
1389
1390
1391public:
1392
1394
1404 constructor(SqlUtil::Table source, *hash<auto> sh, hash<auto> mapv, *hash<auto> opts) ;
1405
1406
1408
1418 constructor(SqlUtil::AbstractTable source, *hash<auto> sh, hash<auto> mapv, *hash<auto> opts) ;
1419
1420
1422
1425
1426
1428
1431
1432
1435
1436
1439
1440
1442
1444 hash<auto> optionKeys();
1445
1446
1448 hash<string, hash<MapperOptionInfo>> getUserOptions();
1449
1450
1452protected:
1453 initOptions(reference<hash<auto>> opts);
1454public:
1455
1456
1458 static *hash<string, AbstractDataField> getStaticInputRecord(AbstractTable table, *hash<auto> select_hash, *reference<string> sql, *hash<auto> input);
1459 }; // SqlStatementOutboundMapper
1460
1463
1464public:
1465protected:
1466 AbstractDatasource m_ds;
1467 string m_sql;
1468 *list m_sqlargs;
1469
1471 const OptionKeys = ...;
1472
1473
1475 const UserOptions = ...;
1476
1477
1478public:
1479
1481
1511 constructor(Qore::SQL::AbstractDatasource ds, string sql, *softlist<auto> sqlargs, hash<auto> mapv, *hash<auto> opts) ;
1512
1513
1516
1517
1519
1521 hash<auto> optionKeys();
1522
1523
1525 hash<string, hash<MapperOptionInfo>> getUserOptions();
1526
1527
1529protected:
1531public:
1532
1533
1535protected:
1536 initOptions(reference<hash<auto>> opts);
1537public:
1538
1539
1541 static *hash<string, AbstractDataField> getStaticInputRecord(Qore::SQL::AbstractDatasource ds, string sql, *softlist<auto> args, *hash<auto> input);
1542 }; // RawSqlStatementOutboundMapper
1543};
Qore::AbstractIterator i
*hash< string, AbstractDataField > input
provides an abstract base for all SQL based outbound mappers
Definition TableMapper.qm.dox.h:1251
abstract Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
Qore::SQL::SQLStatement getRowIterator()
returns a row iterator for the underlying SQL statement for this object
Qore::SQL::AbstractSQLStatement getStatement()
returns a row iterator for the underlying SQL statement for this object
abstract initOptions(reference< hash > opts)
re-implement to initialize options
static *hash< string, AbstractDataField > getInputRecordFromStmt(AbstractSQLStatement stmt, *hash< auto > input)
returns an input record description from an SQLStatement
SqlStatementMapperIterator iterator()
Returns an SqlStatementMapperIterator based on the current object.
commit()
commits the transaction and frees the Qore::SQL::AbstractDatasource transaction thread resource
rollback()
rolls the transaction back and frees the Qore::SQL::AbstractDatasource transaction thread resource
hash< string, hash< MapperOptionInfo > > getUserOptions()
returns mapper options useful for users
*hash< string, auto > getData()
Retrieve mapped data as a hash of lists.
const OptionDefaults
default option values
Definition TableMapper.qm.dox.h:1259
hash< auto > optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses)
constructor(hash< auto > mapv, *hash< auto > opts)
builds the object based on an optional hash providing field mappings, data constraints,...
*list< auto > getDataRows()
Retrieve mapped data as a list of hashes.
abstract initStatement()
re-implement to initialize Qore::SQL::AbstractSQLStatement on demand
const OptionKeys
option keys for this class
Definition TableMapper.qm.dox.h:1255
maps from source to target tables with exactly the same structure
Definition TableMapper.qm.dox.h:820
constructor(SqlUtil::AbstractTable target, hash< auto > mapv={}, *hash< auto > opts)
builds the object based on an optional hash providing field mappings, data constraints,...
constructor(SqlUtil::Table target, hash< auto > mapv={}, *hash< auto > opts)
builds the object based on an optional hash providing field mappings, data constraints,...
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
provides an inbound data mapper to a Table target
Definition TableMapper.qm.dox.h:273
destructor()
throws an exception if there is data pending in the block cache
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
error(string fmt,...)
prepends the datasource description to the error string and calls Mapper::error()
init(hash< auto > mapv, *hash< auto > opts)
common constructor initialization
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 m...
*hash< auto > flush()
flushes any remaining batched data to the database; this method should always be called before commit...
list out_args
extra arguments for sequence output binds
Definition TableMapper.qm.dox.h:302
*hash< auto > flushIntern(bool force_flush)
const OptionKeys
option keys for this object
Definition TableMapper.qm.dox.h:277
bool unstable_input
"unstable input" option for non-optimized inserts/upserts (~33% performance reduction in insert/upser...
Definition TableMapper.qm.dox.h:305
static nothing addBatchToBatch(reference< hash< auto > > hb, hash< auto > batch)
SqlUtil::AbstractDatabase db
the target Database object in case sequence value need to be acquired
Definition TableMapper.qm.dox.h:293
SqlUtil::AbstractTable table
the target table object
Definition TableMapper.qm.dox.h:290
string getTableName()
returns the table name
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
Qore::SQL::AbstractSQLStatement stmt
statement for inserts/upserts
Definition TableMapper.qm.dox.h:308
bool has_returning
if the AbstractTable object supports the "returning" clause
Definition TableMapper.qm.dox.h:296
SqlUtil::AbstractTable getTable()
returns the underlying SqlUtil::AbstractTable object
deprecated hash< auto > insertRowNoCommit(hash< auto > rec)
Plain alias to insertRow(). Obsolete. Do not use.
*code rowcode
per-row Closures or Call References for batch inserts/upserts
Definition TableMapper.qm.dox.h:321
int insert_block
bulk DML block size (also valid for upserts despite the name)
Definition TableMapper.qm.dox.h:311
*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 bas...
*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 r...
setRowCode(*code rowc)
sets a closure or call reference that will be called when data has been sent to the database and all ...
list ret_args
"returning" arguments for sequences
Definition TableMapper.qm.dox.h:299
nothing commit()
flushes any queued data and commits the transaction
*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...
auto mapFieldType(string key, hash< auto > mapping, AbstractDataProviderType type, auto value, hash< auto > rec)
performs type handling
const UserOptions
User options.
Definition TableMapper.qm.dox.h:281
hash< string, hash< MapperOptionInfo > > getUserOptions()
returns mapper options useful for users
TableMapper::InboundTableMapperIterator iterator(Qore::AbstractIterator i)
returns an iterator for the current object
*list< hash< auto > > getReturning()
returns a list argument for the SqlUtil "returning" option, if applicable
error2(string ex, string fmt,...)
prepends the datasource description to the error description and calls Mapper::error2()
logOutput(hash< auto > h)
ignore logging from Mapper since we may have to log sequence values; output logged manually in insert...
discard()
discards any buffered batched data; this method should be called after using the batch APIs (queueDat...
*code upsert_code
closure used for upserting
Definition TableMapper.qm.dox.h:330
const OptionDefaults
default option values
Definition TableMapper.qm.dox.h:285
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 tr...
static deprecated nothing addBatchToBatch(reference< hash > hb, reference x1, hash batch, *reference x2)
adds a batch (hash of lists) to another batch (in-place)
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 m...
*hash< auto > queueDataIntern(hash< auto > rec)
inserts a row into the block buffer based on a mapped input record; does not commit the transaction
hash< auto > optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses)
hash hbuf
buffer for bulk DML
Definition TableMapper.qm.dox.h:314
hash< string, bool > validKeys()
returns a list of valid field keys for this class (can be overridden in subclasses)
*int upsert_strategy
upsert strategy option
Definition TableMapper.qm.dox.h:327
checkMapField(string k, reference< auto > fh)
perform per-field pre-processing on the passed map in the constructor
bool upsert
upsert flag
Definition TableMapper.qm.dox.h:324
nothing rollback()
discards any queued data and rolls back the transaction
*int hbuf_size
size of the batch in hbuf as if returned from getRecListSize()
Definition TableMapper.qm.dox.h:318
provides a hash iterator based on a InboundTableMapper object and an iterator input source; for each ...
Definition TableMapper.qm.dox.h:884
setRuntime(hash< auto > runtime)
adds runtime options to the current runtime option hash
hash< auto > getValue()
returns the current row transformed with the mapper
constructor(Qore::AbstractIterator i, SqlUtil::Table target, hash< auto > mapv, *hash< auto > opts, int commit_limit=0)
creates the iterator from the arguments passed
int commit_limit
row commit limit (<= 0 for no commits)
Definition TableMapper.qm.dox.h:893
TableMapper::InboundTableMapper mapc
data mapper
Definition TableMapper.qm.dox.h:890
string getTableName()
returns the table name
bool next()
Moves the current position of the input iterator to the next element; returns False if there are no m...
constructor(Qore::AbstractIterator i, TableMapper::InboundTableMapper mapv, int commit_limit)
creates the iterator from the arguments passed
resetCount()
resets the internal record count
replaceRuntime(*hash< auto > runtime)
replaces runtime options
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
setRuntime(string key, auto value)
set the runtime option with "key" to value "value"
nothing commit()
commits the transaction
int commitLimit()
returns the commit_limit value set in the constructor()
nothing rollback()
rolls back the transaction
constructor(Qore::AbstractIterator i, SqlUtil::AbstractTable target, hash< auto > mapv, *hash< auto > opts, int commit_limit=0)
creates the iterator from the arguments passed
auto getRuntime(string key)
get current runtime option value for a key
hash< auto > val
a copy of the last hash value mapped
Definition TableMapper.qm.dox.h:899
int getCount()
returns the internal record count
constructor(Qore::AbstractIterator i, InboundTableMapper mapper)
creates the iterator from the mapper passed
int cnt
row count for commit
Definition TableMapper.qm.dox.h:896
provides an outbound data mapper to a raw SQL statement
Definition TableMapper.qm.dox.h:1462
hash< auto > optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses)
constructor(Qore::SQL::AbstractDatasource ds, string sql, *softlist< auto > sqlargs, hash< auto > mapv, *hash< auto > opts)
builds the obejct based on real SQL statement
const UserOptions
user options for this class
Definition TableMapper.qm.dox.h:1475
hash< string, hash< MapperOptionInfo > > getUserOptions()
returns mapper options useful for users
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
initStatement()
initializes the internal statement object
initOptions(reference< hash< auto > > opts)
initializes options
const OptionKeys
option keys for this class
Definition TableMapper.qm.dox.h:1471
static *hash< string, AbstractDataField > getStaticInputRecord(Qore::SQL::AbstractDatasource ds, string sql, *softlist< auto > args, *hash< auto > input)
returns a description of the input record based on Qore::SQL::AbstractSQLStatement::describe()
provides a hash iterator based on a mapper object and an SQLStatement or SqlUtil select hash
Definition TableMapper.qm.dox.h:1112
setRuntime(string key, auto value)
set the runtime option with "key" to value "value"
replaceRuntime(*hash< auto > runtime)
replaces runtime options
bool hasBulk()
returns True because this class supports bulk mode
resetCount()
resets the internal record count
constructor(TableMapper::AbstractSqlStatementOutboundMapper mapper)
creates the iterator from the Mapper passed
auto getRuntime(string key)
get current runtime option value for a key
setRuntime(hash< auto > runtime)
adds runtime options to the current runtime option hash
int getCount()
returns the internal record count
hash< auto > getValue()
returns the current row transformed with the mapper
list< auto > mapBulk(int size)
performs bulk mapping by selecting the requested number of rows in a single select
constructor(Qore::SQL::AbstractSQLStatement stmt, hash< auto > mapv, *hash< auto > opts)
creates the iterator from the arguments passed
Mapper::Mapper m_mapper
data mapper
Definition TableMapper.qm.dox.h:1118
constructor(SqlUtil::AbstractTable table, hash< auto > sh, hash< auto > mapv, *hash< auto > opts)
creates the iterator from the arguments passed
constructor(SqlUtil::Table table, hash< auto > sh, hash< auto > mapv, *hash< auto > opts)
creates the iterator from the arguments passed
provides an outbound data mapper to a Table with SqlUtil select hash as a asource
Definition TableMapper.qm.dox.h:1374
constructor(SqlUtil::Table source, *hash< auto > sh, hash< auto > mapv, *hash< auto > opts)
builds the object based on an optional hash providing field mappings, data constraints,...
hash< string, hash< MapperOptionInfo > > getUserOptions()
returns mapper options useful for users
hash< auto > optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses)
string getTableName()
returns the table name
initStatement()
initializes the internal statement object
const UserOptions
user options for this class
Definition TableMapper.qm.dox.h:1388
initOptions(reference< hash< auto > > opts)
initializes options
constructor(SqlUtil::AbstractTable source, *hash< auto > sh, hash< auto > mapv, *hash< auto > opts)
builds the object based on an optional hash providing field mappings, data constraints,...
const OptionKeys
option keys for this class
Definition TableMapper.qm.dox.h:1384
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
static *hash< string, AbstractDataField > getStaticInputRecord(AbstractTable table, *hash< auto > select_hash, *reference< string > sql, *hash< auto > input)
returns a description of the input record based on Qore::SQL::AbstractSQLStatement::describe()
SqlUtil::AbstractTable getTable()
returns the underlying SqlUtil::AbstractTable object
the TableMapper namespace contains all the definitions in the TableMapper module
Definition TableMapper.qm.dox.h:271