3.9.6. Entity Statistics
The entity statistics mechanism provides the information on the current number of entity instances in the database. This data is used to automatically select the best lookup strategy for linked entities and to limit the size of search results displayed in UI screens.
Statistics is stored in the
SYS_ENTITY_STATISTICS table which is mapped to the
EntityStatistics entity. It can be updated automatically using the
refreshStatistics() method of the PersistenceManagerMBean JMX bean. If you pass an entity name as a parameter, the statistics will be collected for the given entity, otherwise - for all entities. If you want to update the statistics regularly, create a scheduled task invoking this method. Keep it mind that the collection process will execute
select count(*) for each entity and can put significant load on the database.
Programmatic access to entity statistics is available via
PersistenceManagerAPI interface on the middle tier and
PersistenceManagerService on the the client tier. Statistics is cached in memory, so any direct changes to statistics in the database will be applied only after the server restart or after calling the
EntityStatistics attributes are described below.
NAMEcolumn) – the name of the entity meta-class, for example,
INSTANCE_COUNTcolumn) – the approximate number of entity instances.
FETCH_UIcolumn) – the size of the data displayed on a page when extracting entity lists.
For example, the Filter component uses this number in the Show N rows field.
MAX_FETCH_UIcolumn) – the maximum number of entity instances that can be extracted and passed to the client tier.
This limit is applied when showing entity lists in such components as LookupField or LookupPickerField, as well as tables without a filter, when no limitations are applied to the connected data loader via
CollectionLoader.setMaxResults(). In this case the data loader itself limits the number of extracted instances to
LOOKUP_SCREEN_THRESHOLDcolumn) – the threshold, measured in number of entities, which determines when lookup screens should be used instead of dropdowns for entity lookup.
The Filter component takes this parameter into account when choosing filter parameters. Until the threshold is reached, the system uses the LookupField component, and once the threshold is exceeded, the PickerField component is used. Hence, if lookup screens should be used for a specific entity in a filter parameter, it is possible to set the value of
lookupScreenThresholdto a value lower than
PersistenceManagerMBean JMX bean enables setting default values for all of the parameters mentioned above via
DefaultLookupScreenThreshold attributes. The system will use the corresponding default values when an entity has no statistics, which is a common case.
PersistenceManagerMBean.enterStatistics() method allows a user to enter statistics data for an entity. For example, the following parameters should be passed to the method to set a default page size to 1,000 and maximum number of loaded into LookupField instances to 30,000:
entityName: sales_Customer fetchUI: 1000 maxFetchUI: 30000
Another example: suppose that you have a filter condition by the Customer entity, and you want to use a lookup screen instead of dropdown list when selecting Customer in the condition parameter. Then invoke the
enterStatistics() method with the following parameters:
entityName: sales_Customer instanceCount: 2 lookupScreenThreshold: 1
Here we ignore the actual number of Customer records in the database and manually specify that the threshold is always exceeded.