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
                }
            ]
        }
    }
}