{"title":"Defining a report dataset","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-report-dataset/","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-report-dataset, 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-report-dataset","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":"The dataset determines the data extracted to print or display the information from the database.","date":"2024-01-18","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Defining a report dataset","slug":"defining-a-report-dataset","at":0,"chars":8035},{"level":2,"title":"Using tables in a dataset definition","slug":"using-tables-in-a-dataset-definition","at":321,"chars":694},{"level":2,"title":"Formatting field values in report datasets","slug":"formatting-field-values-in-report-datasets","at":1015,"chars":494},{"level":2,"title":"How to include field captions in report datasets","slug":"how-to-include-field-captions-in-report-datasets","at":1509,"chars":362},{"level":2,"title":"Using a query in a dataset definition","slug":"using-a-query-in-a-dataset-definition","at":1871,"chars":363},{"level":2,"title":"Snippet support","slug":"snippet-support","at":2234,"chars":405},{"level":2,"title":"Testing the dataset","slug":"testing-the-dataset","at":2639,"chars":532},{"level":2,"title":"Example: Joining tables to define a report dataset","slug":"example-joining-tables-to-define-a-report-dataset","at":3171,"chars":1858},{"level":2,"title":"Example: Define a report dataset with multiple top-level dataitems","slug":"example-define-a-report-dataset-with-multiple-top-level-dataitems","at":5029,"chars":1601},{"level":2,"title":"Example: Using a query to define a report dataset","slug":"example-using-a-query-to-define-a-report-dataset","at":6630,"chars":853},{"level":2,"title":"Report limit - maximum number of rows","slug":"report-limit---maximum-number-of-rows","at":7483,"chars":354},{"level":2,"title":"Related information","slug":"related-information","at":7837,"chars":198}],"text":"# Defining a report dataset\nYou use a report object in the AL Language development environment to define the data model, or dataset, of a report. The dataset determines the data that is extracted or calculated from the Dynamics 365 Business Central database tables that can be used in a report. See devenv-report-object.\n## Using tables in a dataset definition\nYou build the report dataset from data items and columns. A data item is a table. A column can be:\n A field in a table\n A variable\n An expression\n A text constant\nTypically, data items and columns correspond to fields in a table. When the report is run, each data item is iterated for all records in the underlying table. Filters are applied and the dataset is created. When a report is based on more than one table, you must set relations between the data items so that you can retrieve and organize the data.\nYou can also extend a dataset from an existing report, to add more columns for example. See Report Extension Object<devenv-report-ext-object>.\n## Formatting field values in report datasets\nIt's often useful to format data in the report dataset to reduce the complexity of the report layout. For example, if a decimal field in a table has precision of five digits, the same level of precision might not be needed in the report. Or maybe you want to format dates or currencies in a different way in the report as they appear on the page in Business Central.\nSee Formatting field values in report datasets<devenv-format-report-field-data>.\n## How to include field captions in report datasets\nFor texts that are present as captions on table fields in dataset columns, use the properties/devenv-includecaption-property property to include them in the dataset. See properties/devenv-includecaption-property.\nFor more information about the use of labels in reports, see devenv-report-object#report-labels.\n## Using a query in a dataset definition\nInstead of building the report dataset directly from tables, you can also use a query object. To achieve this, you must\n Add a global variable that points to the query object\n Use an Integer in the data item definition\n Add OnPreDataItem and OnAfterGetRecord triggers\nSee an example of how to do this in the next section.\n## Snippet support\nTyping the shortcut treport creates the basic layout for a report 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## Testing the dataset\n> TIP\n> From the Business Central client, you can export report results as raw data to a Microsoft Excel file. The file contains all columns of the dataset, but without the layout applied. Use the file to help validate that the report returns the expected data, and to ensure that the report layout controls match the dataset value types. To export a report dataset to Excel, run the report and select the Send to > Microsoft Excel Document (data only) on the request page. See /ui-work-report#send-to-excel.\n## Example: Joining tables to define a report dataset\nThe following example adds the Customer table as the data item and the CustomerName and CompanyName as fields of a column to the report. It then adds a secondary dataitem with data from the `Cust. Ledger Entry` table and joins the two.\n```al\ndataitem(Customer; Customer)\n{\n    // For each field that you want to display you add a column control.\n\n    column(No_Customer; \"No.\")\n    {\n        // Include the caption of the \"No.\" field in the dataset of the report.\n        IncludeCaption = true;\n    }\n    column(Name_Customer; Name)\n    {\n        IncludeCaption = true;\n    }\n    column(Phone_Customer; \"Phone No.\")\n    {\n        IncludeCaption = true;\n    }\n    column(Address_Customer; Address)\n    {\n        IncludeCaption = true;\n    }\n    column(EMail_Customer; \"E-Mail\")\n    {\n        IncludeCaption = true;\n    }\n\n    // If your dataset joins multiple tables, add secondary dataitems and link them\n    dataitem(CustLedger; \"Cust. Ledger Entry\")\n    {\n        // Set a filter on the child data item, **CustLedgerEntry** to select only the records where the\n        // value of `Customer.\"No.\"` field and the `\"Customer Ledger Entry\".\"Customer No.\"` field matches.\n        DataItemLink = \"Customer No.\" = field(\"No.\");\n        column(EntryNo_CustLedgerEntry; \"Entry No.\")\n        {\n            IncludeCaption = true;\n        }\n        column(CustomerNo_CustLedgerEntry; \"Customer No.\")\n        {\n            IncludeCaption = true;\n        }\n        column(PostingDate_CustLedgerEntry; \"Posting Date\")\n        {\n            IncludeCaption = true;\n        }\n        column(DocumentType_CustLedgerEntry; \"Document Type\")\n        {\n            IncludeCaption = true;\n        }\n        column(DocumentNo_CustLedgerEntry; \"Document No.\")\n        {\n            IncludeCaption = true;\n        }\n    }\n}\n```\n## Example: Define a report dataset with multiple top-level dataitems\nThe following example adds the `Cust. Ledger Entry` table as a top-level data item. It then add dimension data as a second top-level data item.\n```al\n// Example of how to have two top-level dataitems in a report dataset.\ndataset\n{\n    dataitem(CustLedger; \"Cust. Ledger Entry\")\n    {\n        column(EntryNo_CustLedgerEntry; \"Entry No.\")\n        {\n            IncludeCaption = true;\n        }\n        column(CustomerNo_CustLedgerEntry; \"Customer No.\")\n        {\n            IncludeCaption = true;\n        }\n        column(PostingDate_CustLedgerEntry; \"Posting Date\")\n        {\n            IncludeCaption = true;\n        }\n        column(DocumentType_CustLedgerEntry; \"Document Type\")\n        {\n            IncludeCaption = true;\n        }\n        column(DocumentNo_CustLedgerEntry; \"Document No.\")\n        {\n            IncludeCaption = true;\n        }\n        column(GlobalDim1Code_CustLedgerEntry; \"Global Dimension 1 Code\")\n        {\n            IncludeCaption = true;\n        }\n        column(GlobalDim2Code_CustLedgerEntry; \"Global Dimension 2 Code\")\n        {\n            IncludeCaption = true;\n        }\n    }\n    dataitem(Dimensions; \"Dimension Set Entry\")\n    {\n        column(EntryNo_CustLedgerEntry; \"Dimension Code\")\n        {\n            IncludeCaption = true;\n        }\n        column(EntryNo_CustLedgerEntry; \"Dimension Value Code\")\n        {\n            IncludeCaption = true;\n        }\n        column(EntryNo_CustLedgerEntry; \"Dimension Value ID\")\n        {\n            IncludeCaption = true;\n        }\n    }\n}\n```\n## Example: Using a query to define a report dataset\nLet's imagine that you have created the query object CustomerQuery that joins the customer data with data from some other table. The following example shows how you can use that query as the data source for a report dataset.\n```al\n// Example of how to use a query as the data source for a report dataset.\ndataset\n{\n    dataitem(Integer; Integer)\n    {\n        column(CustomerName; MyQuery.CustomerName)\n        {\n        }\n        column(SomeFieldFromAnotherTable; MyQuery.SomeFieldFromAnotherTable)\n        {\n        }\n\n        trigger OnPreDataItem()\n        begin\n            MyQuery.Open();\n        end;\n\n        trigger OnAfterGetRecord()\n        begin\n            if not MyQuery.Read() then\n                CurrReport.Break();\n        end;\n    }\n}\n\nvar\n    MyQuery: Query \"CustomerQuery\";\n\n```\n## Report limit - maximum number of rows\nThe Business Central platform has built-in limits to protect the stability of the system from a single report consuming too many resources. For example, there's a limit on the maximum number of rows that can be processed in a report.\nFor more information on report limits, see devenv-report-object#report-limits.\n## Related information\nproperties/devenv-includecaption-property\ndevenv-report-object\nReport Extension Object<devenv-report-ext-object>\nReports Overview<devenv-reports>\ndevenv-report-design-overview"}