The Query By Example (QBE) pattern locates records that match specified criteria in a table.

• The QBE bar appears directly above the table column or column group headers, one QBE field per column.
• When the QBE bar is used in conjunction with a Search panel:
• Criteria entered in the QBE fields is appended using the AND operator to criteria entered into the search fields.
• The query is run when the user clicks the Search button in the search panel, selects the View, Refresh command, clicks the Search icon button on the table toolbar, or presses the Enter key while the focus is in one of the search fields.

The QBE bar is hidden by default until the user selects View, Query by Example or clicks the Query by Example icon button on the toolbar. Product teams can choose to show the QBE bar by default when they expect the frequency of use to be high.

Refreshing Table Data

Place a Search icon button on the table toolbar and a redundant Refresh command in the View menu.

There must be a visual affordance for rerunning the query that populates the table. Without it, users must discover that they can requery the table data by pressing the Enter key when a QBE field has the focus or by clicking the Search button in the query panel when one is present.

Removing Query by Example Criteria

QBE cells default to blank on page load. After entering filter critiera, users must manually clear each QBE field. You should provide a Clear button in the table toolbar to enable users to clear all QBE fields with a single click. You should also provide a redundant Clear Filters command in the View menu.

QBE can be enabled for a table with an associated search region. See the QBE Bar section and QBE Fields section of the Table Usage: Table Elements guideline.

Search criteria entered in QBE fields are ANDed with the search criteria. For example, a search criterion of Supplier="Oracle" plus a QBE criterion of Status="On Time" yields the query Supplier="Oracle" AND Status="On Time".

QBE cell values interact with search criteria as follows:

• Editing search fields does not affect any QBE fields.
• Editing QBE fields does not affect any search fields.
• Saving the search saves all search criteria whether entered in search fields or QBE fields.
• Selecting a saved search will populate search fields and QBE fields as they appeared when the search was saved.