A Seeker is a special ViewModel that lets you search persistent database objects from MDriven Designer, and is for developers who need to find a limited result set without loading every object into memory.

What a Seeker does

A Seeker evaluates search criteria as OCLps (persistent-storage OCL). MDriven translates the criteria to SQL and executes them in the database. This lets you search large data sets while loading only the matching objects needed for the result.

For example, a customer seeker can accept a name fragment and a selected department, then return customers that match both values. The user does not need to load all customers into the ViewModel before searching.

A seeker has three main parts:

Part	Purpose	Example
Search-input variables	Hold values supplied by the user.	vSeekParam holds a name or number; a department reference variable holds the selected department.
Search expressions	Define the OCLps criteria that MDriven evaluates in the database.	Find customers whose name matches the entered text.
vSeekerResult	A collection variable that receives the search result and can be shown in a grid or used by actions.	A result table displays the matching customers.

Create a basic seeker

1. Create a ViewModel for the search.
2. Add variables for the values that users will enter or select. Use a string variable for free-text search, such as vSeekParam. Add typed variables when users need structured limits, such as a reference to a department.
3. Add ViewModel columns for the input variables so that the user interface exposes the search fields. For a reference variable, you can use a PickList.
4. In the ViewModel editor, right-click the input ViewModel column and choose Add nested and then Add search expr.
5. Define the search expression and its active expression, where required.
6. Confirm that the ViewModel contains a collection variable named vSeekerResult. The Designer adds default seeker implementation details when you add the first search expression; the required part is the collection variable with this name.
7. Add a nested ViewModel for the result rows beneath vSeekerResult, and add the attributes or actions that users need in the result.
8. Add a search action in the user interface and test the seeker with both empty and populated search values.

Define criteria and when they apply

Each search expression is a criterion. When multiple active criteria are evaluated in the same search batch, their results are intersected on the server. A returned object must satisfy every active criterion.

This makes an active expression important for optional user input. If a user has not selected a department, the department criterion must not restrict the search. An active expression is optional; when you leave it empty, the criterion is always active.

For example, a customer seeker can have these criteria:

User input	Criterion intent	When active
vSeekParam, a string	Match a customer name or customer number.	When the user has entered search text.
A department reference	Limit results to customers in the selected department.	When the user has selected a department.

If both criteria are active, a customer must match the text and belong to the selected department. If only the text criterion is active, the search is not limited by department.

Use multiple search batches

A seeker can contain multiple batches of search expressions. This supports a progressive search strategy without presenting several separate search buttons.

1. On the first search, MDriven evaluates the first batch.
2. If that batch returns results, those results are shown.
3. If it returns no results, MDriven proceeds to the next batch.
4. If the user runs the search again without changing the search variables, MDriven advances to the next batch.
5. If a search variable changes, MDriven resets the round-robin sequence and starts again with the first batch.

For example, the first batch can search for an exact identifier. A later batch can use broader matching criteria. A user who searches for an exact value receives the precise result first; a repeated search with unchanged input can try the broader alternative.

Show and act on results

Use vSeekerResult as the source for the result area in the ViewModel. The result does not have to be a grid. You can show result rows in a table, show a count, or use an action to select or navigate from a returned object.

For a search box with a dropdown result list in Turnkey, bind the search input to vSeekParam and the result table to vSeekerResult. MDriven Stylesheet describes the tk-searchbox structure, result visibility expression, and an optional action that selects a result and clears vSeekParam.

Search large result sets deliberately

A database search finds a subset of records. Do not treat it as a way to load an entire large class into a client-side table.

For example, a search for “Adam” can match more than 1,000 people while the interface displays only 100. If the user changes the sort order from first name to last name, rerun the search in the database. Sorting only the 100 loaded rows does not produce the correct first page of the full result set ordered by last name.

Keep these concerns separate:

Concern	Meaning	Guidance
Search	The user enters a word or value to find records.	Use seeker criteria evaluated as OCLps in the database.
Filter	The user or current context selects a limiting parameter.	Use an optional criterion with an appropriate active expression.
Ordering	The order in which found rows are presented.	Rerun the database search when ordering a partial, paged, or server-filtered result set.

For the detailed behavior of tables, server-side filtering, ordering, and pagination, see Documentation:Tables, search and ordering.

Search parameters for identifiers

vSeekParam is the standard string seeker parameter. If a seeker compares a search value with Guid or integer keys, define the corresponding typed variables when needed:

Variable	Type	Use
vSeekParam	String	Standard free-text seeker parameter.
vSeekParamAsGuid	Guid	Filled before search when the key can be parsed as a Guid.
vSeekParamAsInt	Integer	Filled before search when the key can be parsed as an integer.

This avoids comparing a string parameter directly with a Guid in SQL, which can cause an SQL exception. This behavior is also relevant when a seeker participates in import or synchronization workflows; see Documentation:Convergence – ViewModels, import, export, multi search, synchronization and Excel.

Optional progressive search

You can trigger a seeker repeatedly while the user types by using a periodic action that is enabled only when there is new, non-empty input. Record the value last searched, and disable the periodic action after that value has been searched. This prevents unnecessary repeated queries while still allowing a user to narrow a result by entering more characters.

For example, a vehicle search can return fewer matches as the user enters successive license-plate characters. Limit the number of fetched rows so that a broad early input does not return an impractically large result set.

See also

• Documentation:Part 5 Searching in databases
• Documentation:Tables, search and ordering
• Training:Seeker view
• Documentation:MDriven Stylesheet
• Documentation:Convergence – ViewModels, import, export, multi search, synchronization and Excel