History objects are results of successful transactions. Before adding to database, entire transaction is checked to be consistent. If so, history object is created as a successful commit of transaction.
Transactions are most critical part when saving data into model. There are several settings available to tune transactions. By default, platform tries to ensure that data flowing into database are consistent.
To do so, we utilize a lot of techniques. When somethig goes wrong, transaction is canceled and data are removed from model. There are lot of settings for transactions, see below.
Entire database is transactional. Each operation or group of operations is added into history object. The platform maintains history of every object. Deleted objects are just marked as deleted and remains in DB by default. Each history object contains all information about objects modified/created/updated. So it is easy to find information like
See history command
History objects contains references to objects. User can find information that object was modified, created or deleted but cannot see actual state of object at specified time. To see actual object state at specific time, more epochs is needed.
Epoch history objects are held within epoch data and will be deleted together with epoch. It contains all modifications within epoch.
Global history objects are held within global storage and will remain in database even if epoch is deleted. Mainly used as audit log (who, when and how created/updated epochs, tags and other global objects)
By default, database consistency is prefered rather than speed of processing. But this can be tuned for some cases.
You need to balance between speed and consistency. Use --transaction.level which fits your needs. Higher level means lower speed because everything needs to be doublechecked before saving. By default, level is set to medium which is fair enough for most environments. During transaction, entire database is locked to ensure that there is only one process updating data. Database locks are saved within state storage so it is global.
Even if more users/processes will try to update database, transaction will check and lock database automatically.
--transaction.level={none,low,medium,high}
This phase does not look into actual DB, just checks transaction consistency.
This part actively checks within DB, if transaction can be saved. For example, if we are creating objects, ensure that objects does not exists. If we should create object which already exists, throw an exception. Similary, to check if objects to be modified exists in DB. This part does an extensive load to DB because every object in transaction must be checked against DB. No data is changed within DB during this phase. Some error behaviour can be changed by options (ignore errors). See below options.
To disable predbcheck, use
--transaction.predbcheck=0
When everything was checked, actual saving of data phase is started. According to configuratiom, this can be one or two phase process.
If --transaction.tag=1, there are two phases:
If --transaction.tag=0, there is only one phase:
This is next optional phase to be absolutely sure. If this phase is enabled, all objects are reread from DB and checked again if they ae consistent.
This phase is disabled by default, but can be enabled if you want another layer of consistency.
When transaction is successfully finished, it is saved to database as a history object.
usage: fcpc module/transaction [-h] [--transaction.tag {0,1}] [--transaction.max_objects TRANSACTION.MAX_OBJECTS] [--transaction.precheck TRANSACTION.PRECHECK]
[--transaction.predbcheck TRANSACTION.PREDBCHECK] [--transaction.postdbcheck TRANSACTION.POSTDBCHECK]
[--transaction.tag_name TRANSACTION.TAG_NAME] [--transaction.level {none,low,medium,high}]
[--transaction.add.ifexists {ignore,error,update}] [--transaction.link.ifnotexists {ignore,error}]
[--transaction.delete.action {tag,delete}] [--transaction.delete.ifnotexists {ignore,error}]
[--transaction.modify.ifnotexists {ignore,error}] [--transaction.dry {0,1}] [--transaction.report_on_error {0,1}]
transaction
optional arguments:
-h, --help show this help message and exit
--transaction.tag {0,1}
Tag objects in transaction[Defined:fcplib.db.transaction] (default: 1)
Choices:
0
1
--transaction.max_objects TRANSACTION.MAX_OBJECTS
Maximum count of objects per one history object.[Defined:fcplib.db.transaction] (default: 6000)
--transaction.precheck TRANSACTION.PRECHECK
Essential checking of objects before commit. If you are really sure, set to 0 to disable[Defined:fcplib.db.transaction] (default: 1)
--transaction.predbcheck TRANSACTION.PREDBCHECK
Check consistency of objects before each transaction. Use 0 if you are sure that you do not run multiple imports at same
time.[Defined:fcplib.db.transaction] (default: 1)
--transaction.postdbcheck TRANSACTION.POSTDBCHECK
Check consistency of objects after each transaction. Use 0 if you are sure that you do not run multiple imports at same
time.[Defined:fcplib.db.transaction] (default: 0)
--transaction.tag_name TRANSACTION.TAG_NAME
Name of tag to use for tagging transactions. Use empty string to skip tagging[Defined:fcplib.db.transaction] (default: sys:in-transaction)
--transaction.level {none,low,medium,high}
Transaction consistency level. Low means bigger speed but less checks.[Defined:fcplib.db.transaction] (default: None)
Choices:
none
low
medium
high
--transaction.add.ifexists {ignore,error,update}
What to do if added object is already in db. Ignore: Ignore object and do not touch in db, Error: throw error, Update: update object in
db[Defined:fcplib.db.transaction] (default: error)
Choices:
ignore
error
update
--transaction.link.ifnotexists {ignore,error}
What to do if added link references to non-existing object. Error: throw error, ignore: ignore link[Defined:fcplib.db.transaction] (default:
error)
Choices:
ignore
error
--transaction.delete.action {tag,delete}
What we should do with deleted objects. Either to delete or just tag as deleted (default)[Defined:fcplib.db.transaction] (default: tag)
Choices:
tag
delete
--transaction.delete.ifnotexists {ignore,error}
What we should do if we should delete object which does not exists. Either ignore or error (default)[Defined:fcplib.db.transaction] (default:
error)
Choices:
ignore
error
--transaction.modify.ifnotexists {ignore,error}
What we should do if we should modify object which does not exists. Either ignore or error (default)[Defined:fcplib.db.transaction] (default:
error)
Choices:
ignore
error
--transaction.dry {0,1}
Do not commit transaction, just test[Defined:fcplib.db.transaction] (default: 0)
Choices:
0
1
--transaction.report_on_error {0,1}
When there is some error within transaction, save to the file transaction-id.json[Defined:fcplib.db.transaction] (default: 0)
Choices:
0
1