{"title":"Query object","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-query-object/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-query-object, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-query-object","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Description of the AL query object.","date":"2024-11-22","meta":{"topic":"how-to"},"outline":[{"level":2,"title":"Creating a query object","slug":"creating-a-query-object","at":643,"chars":3127},{"level":2,"title":"Snippet support","slug":"snippet-support","at":3770,"chars":403},{"level":2,"title":"Query discoverability","slug":"query-discoverability","at":4173,"chars":527},{"level":2,"title":"Query example","slug":"query-example","at":4700,"chars":2619},{"level":2,"title":"View and analyze query data","slug":"view-and-analyze-query-data","at":7319,"chars":1399},{"level":2,"title":"Related information","slug":"related-information","at":8718,"chars":441}],"text":"Business Central query objects enable you to retrieve records from one or more tables and then combine the data into rows and columns in a single dataset. Query objects can also perform calculations on data, such finding the sum or average of all values in a column of the dataset.\nThere are two types of query objects: normal and API. This article describes normal query objects, which can be used to display data in the user interface. API query objects are used to generate web service endpoints and can't be displayed in the user interface. For information about creating a query of the type API, see API Query Type<devenv-api-querytype>.\n## Creating a query object\nA query object is comprised mainly of two different types of elements: dataitems and columns. A dataitem specifies the table to retrieve records from. A column specifies a field of the table to include in the resulting dataset of a query. The basic steps to create a query object are as follows:\n1. Add the query keyword, followed by the elements control.\n2. Build the dataset by adding dataitem controls and column controls within the elements control.\n The hierarchy of the dataitem and column controls is important because it determines the sequence in which data items are linked, which in turn controls the results. Working from top-to-bottom, you start by adding the dataitem control for first table that you want in the dataset, then add column controls for each table field that you want to include in the dataset. For the next table, you add another dataitem control that is embedded within the first dataitem control, then add column controls as needed. You continue this pattern for other tables and fields.\n3. When you specify the dataitem and column elements, create links and joins between the dataitem elements.\n Dataitem links and joins determine which records to include in the dataset based on the values of a common field between dataitems. You set a link between one or more fields of the dataitem tables with the properties/devenv-dataitemlink-query-property and you define the type of the link using the properties/devenv-sqljointype-property. Both properties must be set on the lower dataitem of the query object. See Linking and Joining Data Items<devenv-query-links-joins>.\nThe following code shows the basic structure of a query object.\n```al\nquery ID Name\n{\n\n    elements\n    {\n        dataitem(DataItem1; Table1)\n        {\n            column(Column1; Field1)\n            {\n            }\n            column(Column2; Field2)\n            {\n            }\n            dataitem(DataItem2; Table2)\n            {\n                // Sets a link between FieldY of Table2 and FieldX of Table1.\n                DataItemLink = FieldY = DataItem1.FieldX;\n                //The dataset contains records from Table1 and Table2 where a match is found between FieldY and FieldX.\n                SqlJoinType = InnerJoin;\n\n                column(Column1; Field1)\n                {\n                }\n                dataitem(DataItem3; Table3)\n                {\n                    DataItemLink = FieldZ = DataItem2.FieldY;\n                    SqlJoinType = InnerJoin;\n                    column(Column1; Field1)\n                    {\n                    }\n                }\n            }\n        }\n    }\n}\n```\n> NOTE\n> Extension objects can have a name with a maximum length of 30 characters.\n> IMPORTANT\n> You cannot run a query that gets data from both the application database and the business data database. This also applies to single-tenant deployments so that you do not have to rewrite queries if you decide to export the application. For a description of which tables are considered part of the application database, see ../deployment/separating-application-data-from-business-data.\n## Snippet support\nTyping the shortcut tquery creates the basic layout for a Query object when using the AL Language extension for Microsoft Dynamics 365 Business Central in Visual Studio Code.\n> TIP\n> Use Ctrl+Space to trigger IntelliSense and get assistance on code completion, parameter info, quick info, and member lists. For more information about snippets, see Syntax and snippets<devenv-syntax>.\n## Query discoverability\nAvailable from version 23, by setting the properties/devenv-usagecategory-property, you can make queries discoverable for users in Tell Me search and in the role explorer under Report and Analysis.\nYou can also provide teaching tips by setting the properties properties/devenv-abouttitle-property and properties/devenv-abouttext-property. Provide dedicated help links on the query object to help users understand how to use the query by setting the properties/devenv-contextsensitivehelppage-property.\n## Query example\nThe following example shows a query that displays a list of customers with sales and profit figures. The query primarily retrieves fields from the Customer table, but also displays fields from the Salesperson Purchaser and Country Region tables.\nThe query also uses the DataItemLink property to create a link between the Customer table, Salesperson Code field and the Salesperson Purchaser table, Code fields and a link between the Customer table, Country/Region Code field and the Country/Region table, Code field.\n```al\nquery 50102 \"Top Customer Overview\"\n{\n    QueryType = Normal;\n    Caption = 'Top Customer Overview';\n\n    // Teaching tip title and text. Available from version 23\n    AboutTitle = 'Analyze your customers (slice and dice your data)';\n    AboutText = 'Use this data cube to analyze your customers. You can group and/or the data on any dimension you like.';\n\n    // Controls the help link for this query. Available from version 23\n    ContextSensitiveHelpPage = 'customer_query_help.html';\n\n    // Category to show the query under in Tell Me (search) and in role explorer under Report and Analysis. Available from version 23\n    UsageCategory = ReportsAndAnalysis;\n\n    DataAccessIntent = ReadOnly; // use this to read data from the secondary database replica to speed up performance\n\n    elements\n    {\n        dataitem(Customer; Customer)\n        {\n            column(Name; Name)\n            {\n            }\n            column(No; \"No.\")\n            {\n            }\n            column(Sales_LCY; \"Sales (LCY)\")\n            {\n            }\n            column(Profit_LCY; \"Profit (LCY)\")\n            {\n            }\n            column(Country_Region_Code; \"Country/Region Code\")\n            {\n            }\n            column(City; City)\n            {\n            }\n            column(Global_Dimension_1_Code; \"Global Dimension 1 Code\")\n            {\n            }\n            column(Global_Dimension_2_Code; \"Global Dimension 2 Code\")\n            {\n            }\n            column(Salesperson_Code; \"Salesperson Code\")\n            {\n            }\n            dataitem(Salesperson_Purchaser; \"Salesperson/Purchaser\")\n            {\n                DataItemLink = Code = Customer.\"Salesperson Code\";\n                column(SalesPersonName; Name)\n                {\n                }\n                dataitem(Country_Region; \"Country/Region\")\n                {\n                    DataItemLink = Code = Customer.\"Country/Region Code\";\n                    column(CountryRegionName; Name)\n                    {\n                    }\n                }\n            }\n        }\n    }\n}\n```\n## View and analyze query data\nAvailable from version 23, you can view and analyze query data directly from the Business Central client by running the query, and then switching to in the analysis mode. The data is analyzed in real time and respects the data security that is set up for the users.\nThere are a couple ways to run a query. One way to run a query is to use the `query=<id>` in the web client URL. For example, this URL opens the query that has the ID 102:\n```http\nhttps://businesscentral.dynamics.com/?company=CRONUS%20USA%2C%20Inc.&query=102\n```\nAnother way to run the query is to add an action on a page and use the properties/devenv-runobject-property. The following example shows how to add an action that opens a query on the Item list page:\n```al\npageextension 50110 ItemListWithQuery extends \"Item List\"\n{\n\n    actions\n    {\n        addbefore(\"Inventory - List\")\n        {\n            action(\"Analyze customers\")\n            {\n                ApplicationArea = All;\n                Caption = 'Analyze customers';\n                RunObject = query \"Top Customer Overview\";\n                Tooltip = 'Open the customer query in analysis mode.';\n                Image = Item;\n            }\n        }\n    }\n}\n```\nOnce the query opens in the client, turn on the Analyze switch to change to analysis mode.\nSee Analyze list page and query data using data analysis mode</analysis-mode>.\n## Related information\nLinking and Joining Data Items<devenv-query-links-joins>\nAggregating Data in Query Objects<devenv-query-totals-grouping>\n../administration/optimize-sql-query-objects-and-performance\nproperties/devenv-query-properties\nQuery DataAccessIntent<properties/devenv-dataaccessintent-property>\nDeveloping Extensions<devenv-dev-overview>\nAL Development Environment<devenv-reference-overview>\nAPI Query Type<devenv-api-querytype>"}