$.udb(ds).getDataSet()

note

This article is about the getDataSet() function of the DataSourceContainer object.

$.udb(ds).getDataSet()

Fetches records of a data source. These records can then be set in a data set of this data source, or used independently, for example as a list of possible values in an autocompletion input box.

Returns a UdbPromise object with the UdbDsc object as parameter, unless the get-rows option is true, in which case the fetched rows (or the result of process-function, if specified) are passed as parameter instead.

Syntax

$.udb( *ds* ).getDataSet( [options] )
.then( (*dsc*) => {
    //...
})
.catch(() => {
     // failure
})
.finally(() => {
     // executed after success / failure is handled
});

*options*  ::=  {
      [colRef]:             *columns* | null,
      [doCount]:            *do-count*,
      [beginRec]:           *begin-record-index*,
      [count]:              *count*,
      [withQueryCondition]: *with-query-condition*,
      [condition]:          *condition-object*,
      [getRows]:            *get-rows*,
      [replace]:            *replace*,
      [process]:            *process-function*
      [noProcess]:          *skip-process-combined*
}

*do-count*               ::= { [true] | false   }
*with-query-condition*   ::= { [true] | false   }
*get-rows*               ::= { true   | [false] }
*replace*                ::= { [true] | false   }
*skip-process-combined*  ::= { true   | [false] }

The required ds parameter is a data source selector.

Options is a struct that can have the following items, all of which are optional.

Columns is a comma-separated list of references to one or more columns of the data source. To refer to a column you can use its name or alias.

Do-count determines whether a count query must be performed in addition to the query action.

Begin-record-index is the record index number of the first record to be fetched. Its default is 1, which identifies the first record.

Count is the maximum number of records to be queried. Normally, this is limited by the 'Maximum Number of Records' property of the data source, but this parameter allows you to override that limit. Specifying the 0 value will fetch all matching records.

With-query-condition determines whether the current search values must be included in the query action. The default is true, but if a query is performed for an autocompletion field for a search condition, with-query-condition should be set to false.

Condition-object is a search condition object that identifies the subset of rows that you want to be fetched. This object is a JSON object that matches column names with search conditions for these objects.

Get-rows specifies whether you want the rows delivered directly as the return value of the .getDataSet() function or whether you want the rows placed in the data source's row set instead. If true, then the .then() clause will get an object with these rows, otherwise it will get the dsc object instead.

Replace determines whether rows in the data source's rowset need to be completely replaced by the records that were queried. This setting is ignored when get-rows is true.

Process-function is an optional function used to transform the records returned by the server. If this function is specified, its results are passed to the .then() clause of the resulting UdbPromise.

Example 1

var cond = {};
cond[col.alias()] = ''; //all values of the column
dsc.getDataSet({
    colRef: col.alias(),
    getRows: true,
    condition: cond,
    replace: false
}).then((result) => {
    //...
});

Example 2

var condition = {};
condition[col] = v + '%';

$.udb(d).getDataSet({
    count: $.udb(d).dataSetSize(),
    getRows: true,
    replace: false,
    condition: condition,
    process: function(rows) {
        var values = [];
        // ...
        for (var i = 0; i < rows.length; i++) {
            if (rows[i] && !check[rows[i][pkName]]) {
                if (!max || values.length < max)
                    values.push({
                        text: rows[i][colName],
                        value: rows[i][pkName],
                        rowData: rows[i],
                        dsId: d,
                        colName: colName,
                        pkName: pkName});
                check[rows[i][pkName]] = true;
            }
        }
        return values;
    }
}).then((result) => {
    //publish result
    ...
});

Related events

Event	Applies to	Occurs when
beforeexecutequery	Data source objects	Before the data source is queried
showdata	Data source objects	New data is available for display. Only fires when get-rows is false and skip-process-combined is false (the defaults).