DatabaseQuery

Description

The DatabaseQuery object is used to query objects from a database. It can be used to select a subset of the original dataset. The result can be sorted through the orderBy property and limited through the limitLength property.

Note

Pay attention to the usage of results each call will execute the query. See the example at bottom.

› Inherits:Object
› Inherited by:DatabaseUpdate

Properties

error

This property holds the most recently occurred error or DatabaseQuery.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

filters

This property holds a list of filters which restrict the result. Internally this list is transformed to a SQL-WHERE clause.

› Type:List<DatabaseQueryFilter>
› Signal:filtersChanged()
› Attributes:Readonly

limitLength

This property holds the lenght of the limit to restrict the number of rows returned. This is the maximum number of rows returned.

› Type:SignedInteger
› Default:-1
› Signal:limitLengthChanged()
› Attributes:Writable

limitPos

This property holds the start of a limit to restrict the number of rows returned. This can be seen as a offset.

› Type:SignedInteger
› Default:0
› Signal:limitPosChanged()
› Attributes:Writable

objects

This property holds the list of objects which column should be queried. The order is kept.

› Type:List<DataObject>
› Signal:objectsChanged()
› Attributes:Readonly

orderBy

This property holds a list of columns to use for ordering (sorting) the rows. Only ascending ordering is done. See also orderByNames.

› Type:List<DataObject>
› Signal:orderByChanged()
› Attributes:Readonly

orderByNames

This property holds a string list of column ids to use for ordering (sorting) the rows. This will have no effect if orderBy is set. The negative sign in front of an id indicates descending order. See also the example at the bottom.

This property was introduced in InCore 2.4.

› Type:StringList
› Signal:orderByNamesChanged()
› Attributes:Writable

results

This property holds the results of the query. This will include all objects as columns. For example the column id of the second row can be read with results[1].id. Pay attention to the usage of results and try to use local variables because each reference will execute the query.

› Type:List
› Signal:resultsChanged()
› Attributes:Readonly, Requires Polling

table

This property holds the database table which should be queried. Can be left blank if the parent is a DatabaseTable.

› Type:DatabaseTable
› Signal:tableChanged()
› Attributes:Writable, Optional

Methods

execute()

This method executes the query and updates results. On success, true is returned, otherwise false.

› Returns:Boolean

pollResults()

This method polls the results property. It is called automatically when using a Polling property modifier on this property and usually does not have to be called manually.

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.

filtersDataChanged(SignedInteger index)

This signal is emitted whenever the List.dataChanged() signal is emitted, i.e. the item at index in the filters list itself emitted the dataChanged() signal.

objectsDataChanged(SignedInteger index)

This signal is emitted whenever the List.dataChanged() signal is emitted, i.e. the item at index in the objects list itself emitted the dataChanged() signal.

orderByDataChanged(SignedInteger index)

This signal is emitted whenever the List.dataChanged() signal is emitted, i.e. the item at index in the orderBy list itself emitted the dataChanged() signal.

Enumerations

Error

This enumeration describes all errors which can occur in DatabaseQuery objects. The most recently occurred error is stored in the error property.

Name Value Description
DatabaseQuery.NoError 0 No error occurred or was detected.
DatabaseQuery.InvalidQueryNameError 1 Empty or invalid table name.
DatabaseQuery.InvalidTableError 2 Table property not set or parent is not a table.
DatabaseQuery.TableOpenError 3 Table property not set or parent is not a table.

Example

See DatabaseTable example on how to use DatabaseQuery.