Qore TableMapper Module Reference  1.2.1
TableMapper.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
3 
4 /* TableMapper.qm Copyright 2014 - 2017 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 // this module requires Qore 0.8.13 or better
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 
259 namespace TableMapper {
263 
264 public:
265  public :
267  const OptionKeys = Mapper::OptionKeys + (
268  "unstable_input": sprintf("if this is set to True then a slower insert/upsert method will be used that verifies each input row; if False an optimized insert/upsert method is used (additionally bulk inserts/upserts are possible) but all input hashes must have the same keys in the same order; default: %y", OptionDefaults.unstable_input),
269  "insert_block": sprintf("the row block size used when bulk DML / batch inserts/upserts are used; default: %y", OptionDefaults.insert_block),
270  "rowcode": "a closure or call reference taking a single hash argument representing the row values inserted/upserted plus any output values generated in inserts (such as sequence values, for example)",
271  "upsert": "if True then data will be upserted instead of inserted",
272  "upsert_strategy": "the upsert strategy code to use; implies 'upsert'",
273  );
274 
276  const OptionDefaults = (
277  "unstable_input": False,
278  "insert_block": 1000,
279  );
280 
281 public:
282 
283  private :
286 
289 
292 
295 
298 
301 
304 
307 
310  *int hbuf_size; // size of the batch in hbuf (like if returned from
311  // getRecListSize())
312  // FIXME would be nice to have hbuf with hbuf_size
313  // in a class, but there are performance considerations.
314  // --PQ 23-Mar-2017
315 
317  *code rowcode;
318 
320  bool upsert = False;
321 
324 
326  *code upsert_code;
327 
328 public:
329 
331 
364  constructor(SqlUtil::Table target, hash mapv, *hash opts);
365 
366 
368 
401  constructor(SqlUtil::AbstractTable target, hash mapv, *hash opts);
402 
403 
405 
407  destructor();
408 
409 
411  static hash getOutputRecord(*string mname, AbstractTable table, *hash output);
412 
414 
415 private:
416  init(hash mapv, *hash opts);
417 public:
418 
419 
421 
422 private:
423  mapFieldType(string key, hash m, reference<auto> v, hash rec);
424 public:
425 
426 
428 
432 private:
433  checkMapField(string k, reference<auto> fh);
434 public:
435 
436 
438 
440  hash validTypes();
441 
442 
444 
446  hash validKeys();
447 
448 
450 
452  hash optionKeys();
453 
454 
456 
466  hash insertRow(hash rec);
467 
468 
470 
482  setRowCode(*code rowc);
483 
484 
486 
550  *hash queueData(hash rec, *hash crec);
551 
552 
554 
591 
592 
594 
629  *hash queueData(list l, *hash crec);
630 
631 
633 
646 private:
647  *hash queueDataIntern(hash rec);
648 public:
649 
650 
659 private:
660  *int getRecListSize(hash rec);
661 public:
662 
663 
669 private:
671 public:
672 
673 
678 private:
679  bool isMapperConstant();
680 public:
681 
682 
688  static nothing addBatchToBatch(reference<hash> hb, hash batch);
689 
691 
693  deprecated static nothing addBatchToBatch(reference<hash> hb, reference x1, hash batch, *reference x2);
694 
696 
719  *hash flush();
720 
721 
723 
744  discard();
745 
746 
756  // return nothing if nothing needs to be flushed
757 
758 private:
759  *hash flushIntern(bool force_flush);
760 public:
761 
762 
764  *list getReturning();
765 
766 
768  logOutput(hash h);
769 
770 
772 
778 
779 
781  deprecated hash insertRowNoCommit(hash rec);
782 
784  nothing commit();
785 
786 
788  nothing rollback();
789 
790 
792  string getTableName();
793 
794 
797 
798 
801 
802 
804 
805 private:
806  error(string fmt);
807 public:
808 
809 
811 
812 private:
813  error2(string ex, string fmt);
814 public:
815 
816  };
817 
820 
821 public:
823 
842  constructor(SqlUtil::Table target, hash mapv = {}, *hash opts) ;
843 
844 
846 
866  constructor(SqlUtil::AbstractTable target, hash mapv = {}, *hash opts) ;
867 
868 
870 
871 private:
872  init(hash mapv, *hash opts);
873 public:
874 
875 
877  static hash getStaticInputRecord(SqlUtil::AbstractTable table, *hash input);
878  };
879 
882 
883 public:
884  public :
885 
886 public:
887 
888  private :
891 
894 
896  int cnt = 0;
897 
900 
901 public:
902 
904 
911 
912 
914 
942  constructor(Qore::AbstractIterator i, SqlUtil::Table target, hash mapv, *hash opts, int commit_limit = 0) ;
943 
944 
946 
974  constructor(Qore::AbstractIterator i, SqlUtil::AbstractTable target, hash mapv, *hash opts, int commit_limit = 0) ;
975 
976 
978 
1002 
1003 
1005  hash getValue();
1006 
1007 
1009 
1013  bool next();
1014 
1015 
1017  int commitLimit();
1018 
1019 
1021  nothing commit();
1022 
1023 
1025  nothing rollback();
1026 
1027 
1029  string getTableName();
1030 
1031 
1033 
1035  int getCount();
1036 
1037 
1039 
1041  resetCount();
1042 
1043 
1046 
1047 
1049 
1060  setRuntime(string key, auto value);
1061 
1062 
1064 
1074  setRuntime(hash runtime);
1075 
1076 
1078 
1088  replaceRuntime(*hash runtime);
1089 
1090 
1092 
1103  auto getRuntime(string key);
1104 
1105  };
1106 
1108 
1113 
1114 public:
1115  public :
1116 
1117 public:
1118 
1119  private :
1122 
1123 public:
1124 
1126 
1129  ;
1130 
1131 
1133 
1141  ;
1142 
1143 
1145 
1152  constructor(SqlUtil::Table table, hash sh, hash mapv, *hash opts)
1153  ;
1154 
1155 
1157 
1162  ;
1163 
1164 
1165 
1166 private:
1167  setup(hash mapv, *hash opts);
1168 public:
1169 
1170 
1172  hash getValue();
1173 
1174 
1176 
1178  int getCount();
1179 
1180 
1182 
1184  resetCount();
1185 
1186 
1188  bool hasBulk();
1189 
1190 
1192 
1196  list mapBulk(int size);
1197 
1198 
1200 
1211  setRuntime(string key, auto value);
1212 
1213 
1215 
1225  setRuntime(hash runtime);
1226 
1227 
1229 
1239  replaceRuntime(*hash runtime);
1240 
1241 
1243 
1254  auto getRuntime(string key);
1255 
1256  }; // class SqlStatementMapperIterator
1257 
1260 
1261 public:
1262  public :
1264  const OptionKeys = Mapper::OptionKeys + (
1265  "table": "(required) the AbstractTable object for the source of the data",
1266  "sh": "(optional) an SqlUtil select hash",
1267  "select_block" : sprintf("the row block size used when bulk DML / batch inserts are used; default: %y", OptionDefaults.select_block),
1268  );
1269 
1271  const OptionDefaults = (
1272  "select_block": 1000,
1273  );
1274 
1275 public:
1276 
1277  private :
1278  // internal SQLStatement
1279  SQLStatement m_stmt;
1280  // a select_block size. Taken from options
1281  int select_block;
1282  // original option hash
1283  *hash m_orig_opts;
1284 
1285 public:
1286 
1288 
1298  constructor(hash mapv, *hash opts);
1299 
1300 
1302 
1304  hash optionKeys();
1305 
1306 
1308  commit();
1309 
1310 
1312  rollback();
1313 
1314 
1317 
1319 
1320 private:
1321  abstract initOptions(reference<hash> opts);
1322 public:
1323 
1325 
1326 private:
1327  abstract initStatement();
1328 public:
1329 
1331 
1333  Qore::SQL::SQLStatement getRowIterator();
1334 
1335 
1337 
1343 
1344 
1346 
1355  *hash getData();
1356 
1357 
1359 
1367  *list getDataRows();
1368 
1369 
1370  }; // AbstractSqlStatementOutboundMapper
1371 
1374 
1375 public:
1376  private :
1377  // the target table object
1378  SqlUtil::AbstractTable m_table;
1379  // SqlUtil select hash
1380  *hash m_sh;
1381 
1382 public:
1383 
1385 
1395  constructor(SqlUtil::Table source, *hash sh, hash mapv, *hash opts)
1396  ;
1397 
1398 
1400 
1410  constructor(SqlUtil::AbstractTable source, *hash sh, hash mapv, *hash opts)
1411  ;
1412 
1413 
1415 
1417  string getTableName();
1418 
1419 
1421 
1424 
1425 
1428 
1429 
1431  static *hash getStaticInputRecord(AbstractTable table, *hash select_hash, *reference<string> sql, *hash input);
1432 
1434  initStatement();
1435 
1436 
1438 
1439 private:
1440  initOptions(reference<hash> opts);
1441 public:
1442 
1443  }; // SqlStatementOutboundMapper
1444 
1447 
1448 public:
1449  private :
1450  AbstractDatasource m_ds;
1451  string m_sql;
1452  *list m_sqlargs;
1453 
1454 public:
1455 
1457 
1487  constructor(Qore::SQL::AbstractDatasource ds, string sql, *softlist sqlargs, hash mapv, *hash opts)
1488  ;
1489 
1490 
1493 
1494 
1496  static *hash getStaticInputRecord(Qore::SQL::AbstractDatasource ds, string sql, *softlist args, *hash input);
1497 
1499 
1500 private:
1501  initStatement();
1502 public:
1503 
1504 
1506 
1507 private:
1508  initOptions(reference<hash> opts);
1509 public:
1510 
1511  }; // RawSqlStatementOutboundMapper
1512 };
auto getRuntime(string key)
string sprintf(string fmt,...)
string getTableName()
returns the table name
*hash getOutputRecord()
*hash queueData(hash rec, *hash crec)
inserts/upserts a row (or a set of rows, in case a hash of lists is passed) into the block buffer bas...
provides a hash iterator based on a InboundTableMapper object and an iterator input source; for each ...
Definition: TableMapper.qm.dox.h:881
Qore::SQL::SQLStatement stmt
statement for inserts/upserts
Definition: TableMapper.qm.dox.h:303
int commit_limit
row commit limit (<= 0 for no commits)
Definition: TableMapper.qm.dox.h:893
*list getReturning()
returns a list argument for the SqlUtil "returning" option, if applicable
Mapper::Mapper m_mapper
data mapper
Definition: TableMapper.qm.dox.h:1121
*int upsert_strategy
upsert strategy option
Definition: TableMapper.qm.dox.h:323
provides an outbound data mapper to a Table with SqlUtil select hash as a asource ...
Definition: TableMapper.qm.dox.h:1373
destructor()
throws an exception if there is data pending in the block cache
hash hbuf
buffer for bulk DML
Definition: TableMapper.qm.dox.h:309
hash validKeys()
returns a list of valid field keys for this class (can be overridden in subclasses) ...
hash optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses) ...
static nothing addBatchToBatch(reference< hash > hb, hash batch)
provides an outbound data mapper to a raw SQL statement
Definition: TableMapper.qm.dox.h:1446
nothing rollback()
discards any queued data and rolls back the transaction
checkMapField(string k, reference< auto > fh)
perform per-field pre-processing on the passed map in the constructor
hash validTypes()
returns a list of valid field types for this class (can be overridden in subclasses) ...
hash val
a copy of the last hash value mapped
Definition: TableMapper.qm.dox.h:899
*hash flush()
flushes any remaining batched data to the database; this method should always be called before commit...
const OptionDefaults
default option values
Definition: TableMapper.qm.dox.h:276
*hash flushIntern(bool force_flush)
const False
list list(...)
bool has_returning
if the AbstractTable object supports the "returning" clause
Definition: TableMapper.qm.dox.h:291
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
const OptionKeys
option keys for this object
Definition: TableMapper.qm.dox.h:267
deprecated hash insertRowNoCommit(hash rec)
Plain alias to insertRow(). Obsolete. Do not use.
setup(hash mapv, *hash opts)
SqlUtil::AbstractTable getTable()
returns the underlying SqlUtil::AbstractTable object
*hash queueDataIntern(hash rec)
inserts a row into the block buffer based on a mapped input record; does not commit the transaction ...
bool upsert
upsert flag
Definition: TableMapper.qm.dox.h:320
init(hash mapv, *hash opts)
common constructor initialization
*code upsert_code
closure used for upserting
Definition: TableMapper.qm.dox.h:326
nothing commit()
flushes any queued data and commits the transaction
mapFieldType(string key, hash m, reference< auto > v, hash rec)
performs type handling
SqlUtil::AbstractDatabase db
the target Database object in case sequence value need to be acquired
Definition: TableMapper.qm.dox.h:288
bool unstable_input
"unstable input" option for non-optimized inserts/upserts (~33% performance reduction in insert/upser...
Definition: TableMapper.qm.dox.h:300
maps from source to target tables with exactly the same structure
Definition: TableMapper.qm.dox.h:819
setRuntime(string key, auto value)
error(string fmt)
prepends the datasource description to the error string and calls Mapper::error() ...
the TableMapper namespace contains all the definitions in the TableMapper module
Definition: TableMapper.qm.dox.h:260
provides an abstract base for all SQL based outbound mappers
Definition: TableMapper.qm.dox.h:1259
error2(string ex, string fmt)
prepends the datasource description to the error description and calls Mapper::error2() ...
list ret_args
"returning" arguments for sequences
Definition: TableMapper.qm.dox.h:294
provides a hash iterator based on a mapper object and an SQLStatement or SqlUtil select hash ...
Definition: TableMapper.qm.dox.h:1112
provides an inbound data mapper to a Table target
Definition: TableMapper.qm.dox.h:262
discard()
discards any buffered batched data; this method should be called after using the batch APIs (queueDat...
replaceRuntime(*hash runtime)
hash insertRow(hash rec)
inserts or upserts a row into the target table based on a mapped input record; does not commit the tr...
TableMapper::InboundTableMapper mapc
data mapper
Definition: TableMapper.qm.dox.h:890
hash hash(object obj)
list out_args
extra arguments for sequence output binds
Definition: TableMapper.qm.dox.h:297
int insert_block
bulk DML block size (also valid for upserts despite the name)
Definition: TableMapper.qm.dox.h:306
SqlUtil::AbstractTable table
the target table object
Definition: TableMapper.qm.dox.h:285
TableMapper::InboundTableMapperIterator iterator(Qore::AbstractIterator i)
returns an iterator for the current object
logOutput(hash h)
ignore logging from Mapper since we may have to log sequence values; output logged manually in insert...
*code rowcode
per-row Closures or Call References for batch inserts/upserts
Definition: TableMapper.qm.dox.h:317
setRowCode(*code rowc)
sets a closure or call reference that will be called when data has been sent to the database and all ...