Qore TableMapper Module Reference  1.2.2
 All Classes Namespaces Functions Variables Groups Pages
TableMapper.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
3 
4 /* TableMapper.qm Copyright 2014 - 2018 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 
266 namespace TableMapper {
270 
271 public:
272  public :
274  const OptionKeys = Mapper::OptionKeys + (
275  "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),
276  "insert_block": sprintf("the row block size used when bulk DML / batch inserts/upserts are used; default: %y", OptionDefaults.insert_block),
277  "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)",
278  "upsert": "if True then data will be upserted instead of inserted",
279  "upsert_strategy": "the upsert strategy code to use; implies 'upsert'",
280  );
281 
283  const OptionDefaults = (
284  "unstable_input": False,
285  "insert_block": 1000,
286  );
287 
288 public:
289 
290  private :
293 
296 
299 
302 
305 
308 
311 
314 
317  *int hbuf_size; // size of the batch in hbuf (like if returned from
318  // getRecListSize())
319  // FIXME would be nice to have hbuf with hbuf_size
320  // in a class, but there are performance considerations.
321  // --PQ 23-Mar-2017
322 
324  *code rowcode;
325 
327  bool upsert = False;
328 
331 
333  *code upsert_code;
334 
335 public:
336 
338 
371  constructor(SqlUtil::Table target, hash mapv, *hash opts);
372 
373 
375 
408  constructor(SqlUtil::AbstractTable target, hash mapv, *hash opts);
409 
410 
412 
414  destructor();
415 
416 
418  static hash getOutputRecord(*string mname, AbstractTable table, *hash output);
419 
421 
422 private:
423  init(hash mapv, *hash opts);
424 public:
425 
426 
428 
429 private:
430  mapFieldType(string key, hash m, reference<auto> v, hash rec);
431 public:
432 
433 
435 
439 private:
440  checkMapField(string k, reference<auto> fh);
441 public:
442 
443 
445 
447  hash validTypes();
448 
449 
451 
453  hash validKeys();
454 
455 
457 
459  hash optionKeys();
460 
461 
463 
473  hash insertRow(hash rec);
474 
475 
477 
489  setRowCode(*code rowc);
490 
491 
493 
557  *hash queueData(hash<auto> rec, *hash<auto> crec);
558 
559 
561 
598 
599 
601 
636  *hash queueData(list l, *hash crec);
637 
638 
640 
653 private:
654  *hash queueDataIntern(hash rec);
655 public:
656 
657 
666 private:
667  *int getRecListSize(hash rec);
668 public:
669 
670 
676 private:
678 public:
679 
680 
685 private:
686  bool isMapperConstant();
687 public:
688 
689 
695  static nothing addBatchToBatch(reference<hash> hb, hash batch);
696 
698 
700  deprecated static nothing addBatchToBatch(reference<hash> hb, reference x1, hash batch, *reference x2);
701 
703 
726  *hash flush();
727 
728 
730 
751  discard();
752 
753 
763  // return nothing if nothing needs to be flushed
764 
765 private:
766  *hash flushIntern(bool force_flush);
767 public:
768 
769 
771  *list getReturning();
772 
773 
775  logOutput(hash h);
776 
777 
779 
785 
786 
788  deprecated hash insertRowNoCommit(hash rec);
789 
791  nothing commit();
792 
793 
795  nothing rollback();
796 
797 
799  string getTableName();
800 
801 
804 
805 
808 
809 
811 
812 private:
813  error(string fmt);
814 public:
815 
816 
818 
819 private:
820  error2(string ex, string fmt);
821 public:
822 
823  };
824 
827 
828 public:
830 
849  constructor(SqlUtil::Table target, hash mapv = {}, *hash opts) ;
850 
851 
853 
873  constructor(SqlUtil::AbstractTable target, hash mapv = {}, *hash opts) ;
874 
875 
877 
878 private:
879  init(hash mapv, *hash opts);
880 public:
881 
882 
885  };
886 
889 
890 public:
891  public :
892 
893 public:
894 
895  private :
898 
901 
903  int cnt = 0;
904 
907 
908 public:
909 
911 
918 
919 
921 
949  constructor(Qore::AbstractIterator i, SqlUtil::Table target, hash mapv, *hash opts, int commit_limit = 0) ;
950 
951 
953 
982 
983 
985 
1009 
1010 
1012  hash getValue();
1013 
1014 
1016 
1020  bool next();
1021 
1022 
1024  int commitLimit();
1025 
1026 
1028  nothing commit();
1029 
1030 
1032  nothing rollback();
1033 
1034 
1036  string getTableName();
1037 
1038 
1040 
1042  int getCount();
1043 
1044 
1046 
1048  resetCount();
1049 
1050 
1053 
1054 
1056 
1067  setRuntime(string key, auto value);
1068 
1069 
1071 
1081  setRuntime(hash runtime);
1082 
1083 
1085 
1095  replaceRuntime(*hash runtime);
1096 
1097 
1099 
1110  auto getRuntime(string key);
1111 
1112  };
1113 
1115 
1120 
1121 public:
1122  public :
1123 
1124 public:
1125 
1126  private :
1129 
1130 public:
1131 
1133 
1136  ;
1137 
1138 
1140 
1147  constructor(SqlUtil::AbstractTable table, hash sh, hash mapv, *hash opts)
1148  ;
1149 
1150 
1152 
1159  constructor(SqlUtil::Table table, hash sh, hash mapv, *hash opts)
1160  ;
1161 
1162 
1164 
1168  constructor(Qore::SQL::SQLStatement stmt, hash mapv, *hash opts)
1169  ;
1170 
1171 
1172 
1173 private:
1174  setup(hash mapv, *hash opts);
1175 public:
1176 
1177 
1179  hash getValue();
1180 
1181 
1183 
1185  int getCount();
1186 
1187 
1189 
1191  resetCount();
1192 
1193 
1195  bool hasBulk();
1196 
1197 
1199 
1203  list mapBulk(int size);
1204 
1205 
1207 
1218  setRuntime(string key, auto value);
1219 
1220 
1222 
1232  setRuntime(hash runtime);
1233 
1234 
1236 
1246  replaceRuntime(*hash runtime);
1247 
1248 
1250 
1261  auto getRuntime(string key);
1262 
1263  }; // class SqlStatementMapperIterator
1264 
1267 
1268 public:
1269  public :
1271  const OptionKeys = Mapper::OptionKeys + {
1272  "select_block" : sprintf("the row block size used when bulk DML / batch inserts are used; default: %y", OptionDefaults.select_block),
1273  };
1274 
1276  const OptionDefaults = {
1277  "select_block": 1000,
1278  };
1279 
1280 public:
1281 
1282  private :
1283  // internal SQLStatement
1284  SQLStatement m_stmt;
1285  // a select_block size. Taken from options
1286  int select_block;
1287  // original option hash
1288  *hash m_orig_opts;
1289 
1290 public:
1291 
1293 
1303  constructor(hash mapv, *hash opts);
1304 
1305 
1307 
1309  hash<auto> optionKeys();
1310 
1311 
1313  commit();
1314 
1315 
1317  rollback();
1318 
1319 
1322 
1324 
1325 private:
1326  abstract initOptions(reference<hash> opts);
1327 public:
1328 
1330 
1331 private:
1332  abstract initStatement();
1333 public:
1334 
1336 
1339 
1340 
1342 
1348 
1349 
1351 
1360  *hash getData();
1361 
1362 
1364 
1372  *list getDataRows();
1373 
1374 
1375  }; // AbstractSqlStatementOutboundMapper
1376 
1379 
1380 public:
1381  private :
1382  // the target table object
1383  SqlUtil::AbstractTable m_table;
1384  // SqlUtil select hash
1385  *hash m_sh;
1386 
1389  "table": "(required) the AbstractTable object for the source of the data",
1390  "sh": "(optional) an SqlUtil select hash",
1391  };
1392 
1393 public:
1394 
1396 
1406  constructor(SqlUtil::Table source, *hash sh, hash mapv, *hash opts)
1407  ;
1408 
1409 
1411 
1421  constructor(SqlUtil::AbstractTable source, *hash sh, hash mapv, *hash opts)
1422  ;
1423 
1424 
1426 
1428  string getTableName();
1429 
1430 
1432 
1435 
1436 
1439 
1440 
1442  static *hash getStaticInputRecord(AbstractTable table, *hash select_hash, *reference<string> sql, *hash input);
1443 
1445  initStatement();
1446 
1447 
1449 
1451  hash<auto> optionKeys();
1452 
1453 
1455 
1456 private:
1457  initOptions(reference<hash> opts);
1458 public:
1459 
1460  }; // SqlStatementOutboundMapper
1461 
1464 
1465 public:
1466  private :
1467  AbstractDatasource m_ds;
1468  string m_sql;
1469  *list m_sqlargs;
1470 
1471  const OptionKeys = AbstractSqlStatementOutboundMapper::OptionKeys + {
1472  "datasource": "(internal) the datasource containing the target table",
1473  "select": "(internal) the SQL statement used",
1474  "bind": "(internal) a runtime bind-variable (soft)list",
1475  };
1476 
1477 public:
1478 
1480 
1510  constructor(Qore::SQL::AbstractDatasource ds, string sql, *softlist sqlargs, hash mapv, *hash opts)
1511  ;
1512 
1513 
1516 
1517 
1519 
1521  hash<auto> optionKeys();
1522 
1523 
1525  static *hash getStaticInputRecord(Qore::SQL::AbstractDatasource ds, string sql, *softlist args, *hash input);
1526 
1528 
1529 private:
1530  initStatement();
1531 public:
1532 
1533 
1535 
1536 private:
1537  initOptions(reference<hash> opts);
1538 public:
1539 
1540  }; // RawSqlStatementOutboundMapper
1541 };
abstract Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
string getTableName()
returns the table name
commit()
commits the transaction and frees the Qore::SQL::AbstractDatasource transaction thread resource ...
Qore::AbstractIterator i
int commitLimit()
returns the commit_limit value set in the constructor()
nothing commit()
commits the transaction
string sprintf(string fmt,...)
string getTableName()
returns the table name
hash getValue()
returns the current row transformed with the mapper
*hash getOutputRecord()
provides a hash iterator based on a InboundTableMapper object and an iterator input source; for each ...
Definition: TableMapper.qm.dox.h:888
Qore::SQL::SQLStatement stmt
statement for inserts/upserts
Definition: TableMapper.qm.dox.h:310
int commit_limit
row commit limit (&lt;= 0 for no commits)
Definition: TableMapper.qm.dox.h:900
hash< auto > optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses) ...
*list getReturning()
returns a list argument for the SqlUtil &quot;returning&quot; option, if applicable
initOptions(reference< hash > opts)
initializes options
Mapper::Mapper m_mapper
data mapper
Definition: TableMapper.qm.dox.h:1128
Qore::SQL::AbstractDatasource getDatasource()
builds the obejct based on real SQL statement
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
*int upsert_strategy
upsert strategy option
Definition: TableMapper.qm.dox.h:330
provides an outbound data mapper to a Table with SqlUtil select hash as a asource ...
Definition: TableMapper.qm.dox.h:1378
setRuntime(string key, auto value)
set the runtime option with &quot;key&quot; to value &quot;value&quot;
destructor()
throws an exception if there is data pending in the block cache
hash hbuf
buffer for bulk DML
Definition: TableMapper.qm.dox.h:316
SqlUtil::AbstractTable getTable()
returns the underlying SqlUtil::AbstractTable object
hash validKeys()
returns a list of valid field keys for this class (can be overridden in subclasses) ...
replaceRuntime(*hash runtime)
replaces runtime options
bool next()
Moves the current position of the input iterator to the next element; returns False if there are no m...
hash optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses) ...
static hash getStaticInputRecord(SqlUtil::AbstractTable table, *hash input)
returns a description of the input record based on the AbstractTable source
initStatement()
initializes the internal statement object
static nothing addBatchToBatch(reference< hash > hb, hash batch)
abstract initOptions(reference< hash > opts)
re-implement to initialize options
provides an outbound data mapper to a raw SQL statement
Definition: TableMapper.qm.dox.h:1463
hash< auto > optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses) ...
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
resetCount()
resets the internal record count
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
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:906
const OptionDefaults
default option values
Definition: TableMapper.qm.dox.h:1276
*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:283
*hash flushIntern(bool force_flush)
const False
*hash 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...
bool hasBulk()
returns True because this class supports bulk mode
replaceRuntime(*hash runtime)
replaces runtime options
list list(...)
bool has_returning
if the AbstractTable object supports the &quot;returning&quot; clause
Definition: TableMapper.qm.dox.h:298
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
const OptionKeys
option keys for this object
Definition: TableMapper.qm.dox.h:274
static *hash getStaticInputRecord(Qore::SQL::AbstractDatasource ds, string sql, *softlist args, *hash input)
returns a description of the input record based on Qore::SQL::SQLStatement::describe() ...
setRuntime(string key, auto value)
set the runtime option with &quot;key&quot; to value &quot;value&quot;
resetCount()
resets the internal record count
initStatement()
initializes the internal statement object
deprecated hash insertRowNoCommit(hash rec)
Plain alias to insertRow(). Obsolete. Do not use.
SqlUtil::AbstractTable getTable()
returns the underlying SqlUtil::AbstractTable object
nothing rollback()
rolls back the transaction
*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:327
init(hash mapv, *hash opts)
common constructor initialization
int getCount()
returns the internal record count
*code upsert_code
closure used for upserting
Definition: TableMapper.qm.dox.h:333
initOptions(reference< hash > opts)
initializes options
abstract initStatement()
re-implement to initialize Qore::SQL::SQLStatement on demand
int getCount()
returns the internal record count
nothing commit()
flushes any queued data and commits the transaction
init(hash mapv, *hash opts)
common constructor initialization
int cnt
row count for commit
Definition: TableMapper.qm.dox.h:903
const OptionKeys
option keys for this object
Definition: TableMapper.qm.dox.h:1271
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:295
bool unstable_input
&quot;unstable input&quot; option for non-optimized inserts/upserts (~33% performance reduction in insert/upser...
Definition: TableMapper.qm.dox.h:307
constructor(Qore::AbstractIterator i, InboundTableMapper mapper)
creates the iterator from the mapper passed
maps from source to target tables with exactly the same structure
Definition: TableMapper.qm.dox.h:826
constructor(Qore::AbstractIterator iter)
hash getValue()
returns the current row transformed with the mapper
error(string fmt)
prepends the datasource description to the error string and calls Mapper::error() ...
auto getRuntime(string key)
get current runtime option value for a key
provides an abstract base for all SQL based outbound mappers
Definition: TableMapper.qm.dox.h:1266
list mapBulk(int size)
performs bulk mapping by selecting the requested number of rows in a single select ...
*list getDataRows()
Retrieve mapped data as a list of hashes.
*hash getData()
Retrieve mapped data as a hash of lists.
error2(string ex, string fmt)
prepends the datasource description to the error description and calls Mapper::error2() ...
setup(hash mapv, *hash opts)
creates the iterator from the Mapper passed
list ret_args
&quot;returning&quot; arguments for sequences
Definition: TableMapper.qm.dox.h:301
rollback()
rolls the transaction back and frees the Qore::SQL::AbstractDatasource transaction thread resource ...
provides a hash iterator based on a mapper object and an SQLStatement or SqlUtil select hash ...
Definition: TableMapper.qm.dox.h:1119
provides an inbound data mapper to a Table target
Definition: TableMapper.qm.dox.h:269
Qore::SQL::SQLStatement getRowIterator()
returns a row iterator for the underlying SQL statement for this object
SqlStatementMapperIterator iterator()
Returns an SqlStatementMapperIterator based on the current object.
discard()
discards any buffered batched data; this method should be called after using the batch APIs (queueDat...
hash insertRow(hash rec)
inserts or upserts a row into the target table based on a mapped input record; does not commit the tr...
string getTableName()
builds the object based on an optional hash providing field mappings, data constraints, and optionally custom mapping logic
TableMapper::InboundTableMapper mapc
data mapper
Definition: TableMapper.qm.dox.h:897
hash hash(object obj)
list out_args
extra arguments for sequence output binds
Definition: TableMapper.qm.dox.h:304
hash< auto > optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses) ...
int insert_block
bulk DML block size (also valid for upserts despite the name)
Definition: TableMapper.qm.dox.h:313
static *hash getStaticInputRecord(AbstractTable table, *hash select_hash, *reference< string > sql, *hash input)
returns a description of the input record based on Qore::SQL::SQLStatement::describe() ...
const OptionKeys
option keys for this object
Definition: TableMapper.qm.dox.h:1388
SqlUtil::AbstractTable table
the target table object
Definition: TableMapper.qm.dox.h:292
auto getRuntime(string key)
get current runtime option value for a key
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:324
setRowCode(*code rowc)
sets a closure or call reference that will be called when data has been sent to the database and all ...