DatabaseTable¶
Description¶
The DatabaseTable object represents a database table in a database. The Object.objectId property or alternatively the QML ID attribute is used as name of the table in the database. If DataObjectWriter.objects contains an object which value is NaN
or Inf
it will be saved as 0
due to database limitations.
› Inherits: | DataObjectWriter |
---|---|
› Inherited by: | DatabaseEventTable |
Properties¶
database¶
This property holds a Database object to which database the table belongs. If left blank the parent is used.
› Type: | Database |
---|---|
› Signal: | databaseChanged() |
› Attributes: | Writable, Optional |
defaultFieldOptions¶
This property holds default options to apply to all DataObjectWriter.objects which do not have a property of type DatabaseFieldOptions. This can be used to e.g. allow NULL
values for every column without having to set DatabaseFieldOptions.notNull to false
for every object.
This property was introduced in InCore 1.1.
› Type: | DatabaseFieldOptions |
---|---|
› Signal: | defaultFieldOptionsChanged() |
› Attributes: | Writable, Optional |
error¶
This property holds the most recently occurred error or DatabaseTable.NoError if no error occurred. If the same error occurs multiple times this property does not change. Use the errorOccurred() signal to detect multiple occurrences of the same error.
› Type: | Error |
---|---|
› Signal: | errorChanged() |
› Attributes: | Readonly |
errorString¶
This property holds the current human readable error string corresponding to the current value in the error property. It may include additional information such as failure reasons or locations.
› Type: | String |
---|---|
› Signal: | errorStringChanged() |
› Attributes: | Readonly |
operationsEnabled¶
This property holds whether the database table is ready for operations. The DataObjectWriter.objects property must be populated completely before operations may be enabled. Otherwise columns could be missing when creating a database table the first time. For statically initialized objects this property can be left at its default value. However special care needs to be taken in cases where the object list is populated dynamically, e.g. when using property modifiers such as Repeater or populating the list in a function manually. Whenever this applies operations must be enabled only after the list has been initialized. The list must not be changed after this property is changed from false
to true
.
› Type: | Boolean |
---|---|
› Default: | true |
› Signal: | operationsEnabledChanged() |
› Attributes: | Writable, Optional |
pseudoRingBufferOrderBy¶
This property holds an optional sort criterion specifying which data should be removed first whenever the dataset count exceeds pseudoRingBufferSize. This string must be set to an id or Object.objectId of an object in DataObjectWriter.objects to work. For example if there is a DateTime object with id date
and the oldest dateset is to be removed first, pseudoRingBufferOrderBy has to be set to date
(ascending order - oldest will be found and removed first). To use a descending order prepend pseudoRingBufferOrderBy with ‘-‘.
Note
The column id
will be inserted as an auto-incrementing primary key in every DatabaseTable and can be used to determine the least recently inserted datasets.
› Type: | String |
---|---|
› Default: | id |
› Signal: | pseudoRingBufferOrderByChanged() |
› Attributes: | Writable |
pseudoRingBufferSize¶
This property holds an optional dataset limit. When set to a value greater 0 the number of datasets in this table will be limited automatically. If a new dataset is inserted and DataObjectWriter.datasetCount exceeds the configured value the oldest or least recent dataset will be removed. Setting this property makes the table behave like a ring buffer. You can specify a different sort criterion through the pseudoRingBufferOrderBy property.
› Type: | SignedInteger |
---|---|
› Default: | 0 |
› Signal: | pseudoRingBufferSizeChanged() |
› Attributes: | Writable |
queries¶
This property holds a list of DatabaseQuery objects which should be performed on this table.
› Type: | List<DatabaseQuery> |
---|---|
› Signal: | queriesChanged() |
› Attributes: | Readonly |
ready¶
This property holds whether the database table has been opened and initialized successfully and is ready to execute queries.
This property was introduced in InCore 2.5.
› Type: | Boolean |
---|---|
› Default: | false |
› Signal: | readyChanged() |
› Attributes: | Readonly |
structure¶
This property holds an alternate list of DataObject objects describing the desired database table structure upon initialization and creation. Usually this list can be left blank so DataObjectWriter.objects are used. In some cases however only a subset of DataObject objects might be configured to be enabled after the table has been created. In such cases all possible objects can be assigned to structure so that the table does not have to be dropped and recreated on every configuration change.
This property was introduced in InCore 1.1.
› Type: | List<DataObject> |
---|---|
› Signal: | structureChanged() |
› Attributes: | Readonly, Optional |
Methods¶
drop()¶
This method removes the table from the database. If you want to remove the datasets only and keep the table structure, call DataObjectWriter.truncate() instead.
› Returns: | Boolean |
---|
Signals¶
errorOccurred()¶
This signal is emitted whenever an error has occurred, regardless of whether the error property has changed or not. In contrast to the change notification signal of the error property this signal is also emitted several times if a certain error occurs several times in succession.
queriesDataChanged(SignedInteger index)¶
This signal is emitted whenever the List.dataChanged() signal is emitted, i.e. the item at index
in the queries list itself emitted the dataChanged() signal.
structureDataChanged(SignedInteger index)¶
This signal is emitted whenever the List.dataChanged() signal is emitted, i.e. the item at index
in the structure list itself emitted the dataChanged() signal.
Enumerations¶
Error¶
This enumeration describes all errors which can occur in DatabaseTable objects. The most recently occurred error is stored in the error property.
Name | Value | Description |
---|---|---|
DatabaseTable.NoError |
0 |
No error occurred or was detected. |
DatabaseTable.InvalidDatabase |
1 |
Empty or invalid database property or parent. |
DatabaseTable.InvalidTableIdError |
2 |
Empty or invalid object id. |
DatabaseTable.DatabaseContextError |
3 |
Could not switch database context. |
DatabaseTable.MissingObjectsIds |
4 |
Some data objects do not have an object ID. |
DatabaseTable.MissingDefaultData |
5 |
Some data objects do not have valid default data. |
DatabaseTable.ObjectsChangedWhileOpen |
6 |
Data objects have changed after table has been created and opened. |
DatabaseTable.StructureChangedWhileOpen |
7 |
Structure has changed after table has been created and opened. |
DatabaseTable.OperationsNotEnabled |
8 |
Operation requested before operationsEnabled is set to true. |
DatabaseTable.SubmitError |
9 |
Failed to submit a new data row, probably due to a broken database connection or mismatching table structure. |
Example¶
import InCore.Foundation 2.5
import InCore.Database 2.5
Application {
LocalDatabase {
id: exampleDatabase
DatabaseTable {
id: exampleTable
submitInterval: 1000
submitMode: DatabaseTable.SubmitPeriodically
// save only 1000 datasets in the database
pseudoRingBufferSize: 1000
// order by date - delete oldest dataset first
pseudoRingBufferOrderBy: "date"
// objects to store
DateTime { id: date }
Measurement { id: sensor1; data: 1 }
Measurement { id: sensor2; data: 2 }
Measurement { id: sensor3; data: 123 }
queries: [
DatabaseQuery {
// objects to query
objects: [sensor1, sensor2, sensor3]
orderBy: [sensor3]
// only get 15 values from start on
limitPos: 0
limitLength: 15
onResultsChanged: {
// use a local variable
// this will only trigger execute once and store the result in r
var r = results
// read the data
for(var i = 0; i < r.length; i++)
console.log("S1, S2, S3:", r[i].sensor1, r[i].sensor2, r[i].sensor3)
}
Polling on results { interval: 10000 }
},
DatabaseQuery {
// query only sensor3 data
objects: [sensor3]
// sort by sensor3 descending, then sensor2 ascending
orderByNames: ["-sensor3", "sensor2"]
// only get 10 values descending
limitPos: 0
limitLength: 10
}
]
}
}
}