To use SearchPickerField component, you need to create collectionDatasource and specify a query, which contains corresponding search conditions. Condition must contain a parameter named custom$searchString. This parameter will be populated with a substring entered by the user. A data source with a search condition should be defined in the optionsDatasource attribute of the component. For example:

<dsContext>
    <datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
    <collectionDatasource id="coloursDs" class="com.company.sample.entity.Colour" view="_local">
        <query>
            select c from sample$Colour c
            where c.name like :(?i)custom$searchString
        </query>
    </collectionDatasource>
</dsContext>
<layout>
    <searchPickerField datasource="carDs" property="colour" optionsDatasource="coloursDs"/>

select c from ref$Colour c
where c.name like :(?i)custom$searchString or c.description like :(?i)custom$searchString escape '\'

Using the minSearchStringLength attribute the minimum number of characters, which the user should enter to search for values, can be defined.

In the screen controller, two component methods can be implemented that will be invoked:

@Inject
private SearchPickerField colourField;

@Override
public void init(Map<String, Object> params) {
    colourField.setSearchNotifications(new SearchField.SearchNotifications() {
        @Override
        public void notFoundSuggestions(String filterString) {
            showNotification("No colours found for search string: " + filterString,
                             NotificationType.TRAY);
        }

        @Override
        public void needMinSearchStringLength(String filterString, int minSearchStringLength) {
            showNotification("Minimum length of search string is " + minSearchStringLength,
                             NotificationType.TRAY);
        }
    });
}

SearchPickerField implements LookupField and PickerField interfaces. Thus, it inherits the same functionality except the default list of actions added when defining the component in XML: for SearchPickerField these are lookup and open actions.