The Query builder

The Query builder allows you to filter data from Data Service entities, while respecting a predefined syntax.

Using the Query builder

The Query builder uses the Fetch() function to evaluate and sort your Data Service entities.

As a prerequisite, you must reference existing Data Service entities into your app. To use the Query builder, proceed with the following steps:

1. For the desired control, select a VB enabled property. You can identify these types of properties by the VB Data source field in the General tab.
   
2. Select Query builder. This opens the Query builder window.
3. Select the entity for which you want to build the query for.
4. On the Conditions tab, click:

   Option	Description
   Add condition	to add a single condition
   Add group	to group several conditions

   When you add two or more conditions, the query evaluates and returns data based on AND or OR operators:

   • AND - returns data where all conditions are met

   • OR - returns data where any condition is met

5. Select the entity field which you want to query data from.
6. Select the evaluation operator.
7. Enter the value for your condition. The value must be of the same type as the field type. For example, use strings for Text fields, use integers for Number fields.
8. On the Additional settings tab, you can configure sorting rules for the queried data:

   Option	Description
   Sort by field	Sorts the queried data by the selected field
   Sort ascending	If true, sorts the queried data in an ascending order.

9. Click Save to save your query.

The Fetch function

The query builder uses the Fetch() function to retrieve and manipulate entity data.

The Fetch() function has the following parameters:

FilterGroup	A group of filters in Data Service
PaginationProps	Specify page size and number of records to skip.
SortOption [] sortOptions	Specify the column to sort and the order for sorting.
string[] selectedFields	Specify the entity fields that should be returned.
ExpansionFieldOption[] expansionFieldOptions	Specify which column of a relationship entity should be expanded and returned. Apps allows level one expansions, meaning that if you have a relationship field, the expressions expects one level of properties to be accessible. The query builder automatically adds these properties, and they are mandatory for the non-system entities.

The FetchOne() function

While Fetch() returns a ListSource<T>, which is the same type as for list controls, FetchOne() returns a single record of type T.

For the following scenarios you need to manually modify the Fetch() function, to get more customized results:

Simple Fetch

Gets the number of records for an entity, for example SystemUsers.

Fetch(of SystemUsers)()

Fetch with filter condition

Fetch(of SystemUsers)(createFilterGroup(new QueryFilter(){addFilter("Name", "=", "You")}), new PaginationProps(0, 10))

Fetch with filter condition and sort order (ascending)

Fetch(of SystemUsers)(createFilterGroup(new QueryFilter(){addFilter("Name", "=", "You")}), new PaginationProps(0, 10), new SortOption(){addSortOption("Date")})

Fetch with filter condition and sort order (descending)

Fetch(of SystemUsers)(createFilterGroup(new QueryFilter(){addFilter("Name", "=", "You")}), new PaginationProps(0, 10), new SortOption(){addSortOption("Date", true)})

Fetch with static PaginationProps

Fetch(of SystemUsers)(Nothing, new PaginationProps(0, 100))

Fetch with control bound PaginationProps

For example, for the Edit Grid control:

Fetch(of SystemUsers)(Nothing, new PaginationProps(MainPage.EditableGrid.PageStart, MainPage.EditableGrid.PageLimit))

Fetch with projection

Fetch(of SystemUsers)(createFilterGroup(new QueryFilter(){addFilter("Name", "=", "You")}), new PaginationProps(0, 10), Nothing, new string(){"Name"})