Here’s a cool little trick to use Query Objects to create user interface, check it out:
In this video, Erik explores a lesser-known but powerful feature in Business Central: the QueryCategory property. This property allows developers to attach query objects to specific list pages, making them appear as views that users can select — bringing functionality reminiscent of Dynamics GP’s beloved Smart Lists into the BC world.
The Origin Story: Smart Lists in Dynamics GP
To understand why QueryCategory exists, we need to take a trip to Dynamics GP (Great Plains). One of GP’s most popular features is Smart Lists — a tool that lets users build queries, display various data views, and export results to Excel. It’s essentially an easy, data-driven reporting mechanism.
When GP users are asked what they love most about the product, Smart Lists come up constantly. Microsoft recognized that to attract GP users to Business Central, they needed something similar. Since BC doesn’t have a dynamic query system built in, Microsoft created the QueryCategory property — not as flexible as Smart Lists, but delivering some of the same results from a user perspective.
What Is QueryCategory?
The QueryCategory property serves as a loose coupling mechanism between query objects and list pages. Here’s how it works:
- On a query object, the
QueryCategoryproperty specifies one or more categories that the query supports - On a page, the
QueryCategoryproperty specifies which category that page supports - When the categories match, the query appears as a view on that page
In plain terms: you create a query object, tag it with a category that matches a list page, and the query shows up as a selectable view on that page.
Exploring the Base App
Using Stefan Maron’s excellent GitHub repository at co.history, Erik searched for all uses of QueryCategory in the Microsoft base application. The search returned only 24 hits, showing this isn’t a heavily-used feature yet. Various base app pages have the property set as a simple text string — for example, the Customer List page has:
QueryCategory = 'Customer List';An important gotcha: the category names aren’t always intuitive. There’s no category called just “Customer” or “Items” — they’re called “Customer List” and “Item List.” You need to check the actual page to find its exact category string.
Building a Query with QueryCategory
Erik demonstrates by creating a query that joins Sales Headers and Sales Lines, then attaches it to the Customer List page. Here’s the complete query object:
query 50100 "Sales of some sort"
{
QueryCategory = 'Customer List';
QueryType = Normal;
elements
{
dataitem(SH; "Sales Header")
{
column(No; "No.")
{
}
column(BilltoCustomerNo; "Bill-to Customer No.")
{
}
column(BilltoName; "Bill-to Name")
{
}
column(BilltoCity; "Bill-to City")
{
}
column(PostingDate; "Posting Date")
{
}
column(CustomerPostingGroup; "Customer Posting Group")
{
}
dataitem(SL; "Sales Line")
{
DataItemLink = "Document Type" = SH."Document Type", "Document No." = SH."No.";
column(Type; Type)
{
}
column(ItemNo; "No.")
{
}
column(Description; Description)
{
}
column(UnitPrice; "Unit Price")
{
}
column(Quantity; Quantity)
{
}
column(Amount; Amount)
{
}
}
}
}
}Key Points About the Query Structure
- The
QueryCategory = 'Customer List'property is what makes this query appear on the Customer List page - The
QueryType = Normalsetting is the standard type for display queries - The
DataItemLinkon the Sales Line data item creates the join between header and line, linking on bothDocument TypeandDocument No. - Column names must be unique within the query since the query collapses everything into a single flat record — that’s why the Sales Line “No.” field is renamed to
ItemNo
A Note on Multiple Categories
A query can appear on more than one page by specifying multiple categories. Conversely, multiple pages can share the same category. The documentation examples show some inconsistent patterns, so always verify the exact category string on your target page.
The Result in Action
After deploying the extension, navigating to the Customer List reveals a new entry in the Views panel: “Sales of some sort.” Selecting this view transforms the page to display the query results — Sales Header and Sales Line data collapsed into flat records. For example, one invoice with three line items appears as three rows, each showing the header information alongside the individual line details.
Users can also open the results in Excel, providing the same export-to-spreadsheet workflow that GP users expect from Smart Lists.
Understanding the Limitations
There are some important limitations to be aware of:
- No context awareness: The query has no idea which customer (or record) is currently selected. It’s a loose coupling — the query is essentially a fancy menu item placed into the views panel. It doesn’t filter based on the active record.
- Filtering is limited to query columns: Users can filter the results, but only on fields that exist in the query. You can filter on “Unit Price = 0” if Unit Price is a column, but you cannot add fields that aren’t part of the query definition.
- No dynamic field selection: Unlike GP Smart Lists where users can customize which fields appear, the query structure is fixed at development time.
Conclusion
The QueryCategory property is an underutilized gem in Business Central development. It provides a straightforward way to surface potentially complex queries as user-friendly views on list pages, complete with Excel export capability. While it doesn’t fully replicate the flexibility of GP’s Smart Lists — particularly lacking context awareness and dynamic field selection — it offers a legitimate, easy-to-implement way to give users access to joined and aggregated data right from the pages they already use. If you’re building extensions for Business Central, this is a feature worth adding to your toolkit.
