{"title":"Using partial records","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-partial-records/","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-partial-records, 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-partial-records","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":"Describes the partial records capability in Business Central.","date":"2023-09-27","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Using partial records","slug":"using-partial-records","at":0,"chars":12678},{"level":2,"title":"API Overview","slug":"api-overview","at":756,"chars":2272},{"level":2,"title":"Example","slug":"example","at":3028,"chars":767},{"level":2,"title":"Usage guidelines","slug":"usage-guidelines","at":3795,"chars":1217},{"level":2,"title":"Just-in-time (JIT) loading","slug":"just-in-time-jit-loading","at":5012,"chars":891},{"level":2,"title":"Iterating over records","slug":"iterating-over-records","at":5903,"chars":1519},{"level":2,"title":"Preventing inconsistent read and JIT loading errors","slug":"preventing-inconsistent-read-and-jit-loading-errors","at":7422,"chars":2260},{"level":2,"title":"Partial records applied by platform","slug":"partial-records-applied-by-platform","at":9682,"chars":2759},{"level":3,"title":"Reports","slug":"reports","at":9951,"chars":996},{"level":3,"title":"OData pages","slug":"odata-pages","at":10947,"chars":628},{"level":3,"title":"List and ListPart pages","slug":"list-and-listpart-pages","at":11575,"chars":529},{"level":3,"title":"Table relation-based lookups","slug":"table-relation-based-lookups","at":12104,"chars":337},{"level":2,"title":"Related information","slug":"related-information","at":12441,"chars":237}],"text":"# Using partial records\n> APPLIES TO: Business Central 2020 release wave 2 and later\nThe partial records capability in Business Central allows for loading a subset of normal table fields when accessing a SQL based data source. Using partial records improves performance of objects like reports and OData pages - objects whose source code loops through records. It's particularly beneficial when table extensions are used in the application.\nAccessing a data source from AL code is typically done by using the record's methods devenv-get-find-and-next-methods, and so on. Without using partial records, the runtime loads all normal fields when accessing the data source. Using the partial records API, you can now select a set of fields and only load them.\n## API Overview\nTo accommodate partial record loading, the following methods are available on both the RecordRef and Record data type in AL. These methods operate on the record instance that they're called on, changing the set of fields to load until otherwise altered. The methods are divided into two groups: methods that pertain to subsequent loads and methods that pertain to the currently loaded record.\nSubsequent load methods\nMethod|Description|See more\nSetLoadFields|Specifies a set of fields to be initially loaded when the record is retrieved from its data source. A call to this method will overwrite any fields that were previously set to load.|methods-auto/record/record-setloadfields-method<br /><br />methods-auto/recordref/recordref-setloadfields-method\nSetBaseLoadFields|Adds all fields from the base table to be initially loaded when the record is retrieved from its data source. A call to this method will overwrite any fields that were previously set to load.|methods-auto/record/record-setbaseloadfields-method<br /><br />Note: The SetBaseLoadFields method was added in Business Central 2023 release wave 2.\nAddLoadFields|Adds fields to the current set of fields to be initially loaded when the record is retrieved from its data source. Subsequent calls to this method won't overwrite fields that were previously selected for loading.|methods-auto/record/record-addloadfields-method<br /><br />methods-auto/recordref/recordref-addloadfields-method\nCurrent load methods\nMethod|Description|See more\nAreFieldsLoaded|Checks whether the specified fields are all initially loaded.|methods-auto/record/record-arefieldsloaded-method<br /><br />methods-auto/recordref/recordref-arefieldsloaded-method\nLoadFields|Accesses the table's corresponding data source to load the specified fields.|methods-auto/record/record-loadfields-method<br /><br />methods-auto/recordref/recordref-loadfields-method\nA record instance that has been previously loaded with fields can be reset to a non-partial load either by calling methods-auto/record/record-setloadfields-method without any parameters, or by calling methods-auto/record/record-reset-method. After being reset, subsequent loads will behave as if SetLoadFields hadn't previously been called on the record instance.\n## Example\nThe following code shows a way to load only a single field from the Item table for computing the arithmetic mean.\n```al\nprocedure ComputeArithmeticMean(): Decimal\nvar\n    Item: Record Item;\n    SumTotal: Decimal;\n    Counter: Integer;\nbegin\n    Item.SetLoadFields(Item.\"Standard Cost\");\n    if Item.FindSet() then begin\n        repeat\n            SumTotal += Item.\"Standard Cost\";\n            Counter += 1;\n        until Item.Next() = 0;\n        exit(SumTotal / Counter);\n    end;\nend\n```\nNotice that the call to methods-auto/record/record-setloadfields-method occurs before the data fetching operations. This call determines which fields are needed for the FindSet call. You use the same pattern for methods-auto/record/record-addloadfields-method calls.\n## Usage guidelines\nThis feature gives you the ability to limit the fields that load for a record to only those fields that are necessary. In general, loading fewer fields will make operations faster. But the most significant performance gains can be seen with table extensions - by not loading unnecessary fields in table extensions. Table extensions that don't have any fields for loading won't be part of the data join, which saves time.\n> TIP\n> Testing on the previous example code showed that the execution time for loading only the \"Standard Cost\" field was nine times faster than loading all normal fields. Your performance numbers will vary depending on the machine and the setup with the SQL database.\nFor performance reasons, it's not recommended to use partial records on a record that will do inserts, deletes, renames, field transfers, or copies to temporary records. All these operations require that all fields on the record are loaded, so the platform will emit a JIT load if they're not already loaded. A JIT load requires to access the data source again, this cost is larger than the gains of loading fewer fields. For this reason, the feature is especially advantageous in reading-based scenarios.\n## Just-in-time (JIT) loading\nWhen a record is loaded as a partial record, the obvious question is: What happens when accessing a field that hasn't been selected for loading? The answer is JIT loading. The platform, in such a case, does an implicit methods-auto/record/record-get-method on the record and loads out the missing field.\nWhen JIT loading occurs, another access to the data source is required. These operations tend to be fast because they're Get calls. Get calls can often be served by the server's data cache or can be resolved as a clustered index operation on the database.\nA JIT load may fail for multiple reasons, like:\n The record has been modified between the original load and the subsequent JIT load.\n The record has been deleted between the original load and the subsequent JIT load.\n The record has been renamed between the original load and the subsequent JIT load.\n## Iterating over records\nWhen iterating over records in the database, an enumerator is created based on selected fields. Then, a row is fetched when methods-auto/record/record-next-method is called. This behavior is an optimization that allows for large parts of the operation to be done only once.\nCertain operations will invalidate the enumerator and force the creation of a new one, which adds some overhead. As long as the enumerator isn't invalidated too frequently, this model is an effective optimization. When accessing fields that aren't loaded, the platform does a JIT load, followed by an update of the enumerator. This process eliminates the need to trigger a JIT load on subsequent iterations.\nWhen passing a record by value, without using a var parameter<devenv-al-methods#Parameters>, a new copy of the record is created. The original record and its copy don't share filters, fields selected for load, and so on. So accessing an unloaded field will trigger a JIT load. But it won't update the enumerator, which means future iterations will also require JIT load.\nThere are a few options to remedy this situation:\n Pass the record reference using var parameter allows for updating of enumerator.\n Call AddLoadFields(fieldnames)<methods-auto/record/record-addloadfields-method> on the original record before passing by value.\n Before calling devenv-get-find-and-next-methods, and so on, use the SetLoadFields(fieldnames)<methods-auto/record/record-setloadfields-method> to set all fields needed for load.\n## Preventing inconsistent read and JIT loading errors\nSeeing the error Inconsistent read of field(s):... means that a read record has changed in the database sometime between the initial load and a subsequent load. When a subsequent load (JIT load) occurs, extra fields are loaded, and all previously loaded fields are checked for consistency to verify that they haven't changed. For example, suppose the Amount field in a table had the value of 42 on the initial load. But at sometime before the subsequent load, another user changed the value in the database to 9001.\nYou could categorize this error as a read skew consistency error. The platform, in this case, doesn't know whether the previously executed code made decisions based on the value being 42. So, instead of potentially ending up with inconsistent data, the platform invokes error handling by throwing an error.\nAnother error related to the Inconsistent read of field(s):... error is the JIT loading of field(s): ... failed ... error. This error is a more generic error that can happen for multiple reasons during a JIT load. But the most frequent cause is that the record has been deleted in the database. It's similar the Another User has Modified the record error you'll get when a record is modified, but the platform detects newer data in the database.\nAll these errors are the result of a race condition, meaning they depend on whether other users are also interacting with the same data concurrently.\nTo prevent these errors, avoid JIT loads if you can. If there are no subsequent loads (JIT), the previously described race condition will never occur. To avoid JIT loads, follow these guidelines:\n On the first load, select all and only the necessary fields by using methods-auto/record/record-setloadfields-method calls or subsequent methods-auto/record/record-addloadfields-method calls.\n When the platform implicitly uses partial records, add the extra fields by calling AddLoadFields from the triggers-auto/reportdataitem/devenv-onpredataitem-reportdataitem-trigger on reports or from the triggers-auto/page/devenv-onopenpage-page-trigger on OData pages.\nSee Reports and OData pages<#reports>. Optionally, you can add the fields as a data column on reports or fields on OData pages.\n## Partial records applied by platform\nThe platform will automatically apply partial records to certain types of AL objects based on their metadata. This is currently done in four places: reports, OData pages, list and listpart pages, and table relation-based lookups.\n### Reports\nWhen loading data for a report, the fields that are referenced in data columns on a data item will automatically be selected for load. This includes references in nested data items.\nOther fields aren't selected for load, even if they may be used in triggers. However, you can add extra fields the following ways:\n Add the field as a column in the data set.\n Add the field to the set of fields to load via the methods-auto/record/record-addloadfields-method method on the triggers-auto/reportdataitem/devenv-onpredataitem-reportdataitem-trigger trigger.\n  The following example code snippet illustrates how to use the AddLoadFields method on a report's OnPreDataItem trigger to add a field for loading:\n  ```al\n  trigger OnPreDataItem()\n  begin\n      CurrencyDataItem.AddLoadFields(CurrencyDataItem.\"ISO Numeric Code\");\n  end;\n\n  trigger OnAfterGetRecord()\n  begin\n      if (CurrencyDataItem.\"ISO Numeric Code\" <> 'DKK') then begin\n          CurrReport.Skip();\n      end;\n  end;\n  ```\n### OData pages\nFor pages opened by OData service calls, the page's metadata is used to define which fields to show. In this case, the fields referenced in the page's layout are loaded as a minimum. More fields may be required, for example, to enable subpage linking.\nLike with reports, other fields aren't selected for load, even if they may be used in triggers. But you can add extra fields the following ways:\n Add the field to the page layout.\n Add the field to the set of fields to be loaded via the methods-auto/record/record-addloadfields-method method on the triggers-auto/page/devenv-onfindrecord-page-trigger trigger.\n### List and ListPart pages\nPartial records are automatically applied based on the page's metadata for List and ListPart page types that are opened in the web client. As with OData pages, the page's definition is used to select which fields to load. More fields may be required, for example, to enable subpage linking.\n> NOTE\n> OnFindRecord and OnNextRecord triggers conflict with partial record feature with List and ListPart pages, so if these triggers are defined in the metadata, the partial record feature won't be applied.\n### Table relation-based lookups\nLookups that are based on table relations and not explicit lookup pages will automatically generate the set of fields to load by using the same logic as for determining which fields to show. Because these lookups don't have a defined page, it isn't possible, or necessary, to overrule the set of fields.\n## Related information\ndevenv-partial-records-faq\nPerformance Articles For Developers<../performance/performance-developer>\ndevenv-get-find-and-next-methods\nConfiguring Business Central Server<../administration/configure-server-instance>"}