Optional Internal_Internal flag set by BaseEngine when loading entity configurations. When true, telemetry analyzers will skip false-positive warnings about "entity already loaded by engine" since the engine IS the one calling RunView.
This property is for framework internal use only.
OptionalAfteroptional - keyset (a.k.a. "seek") pagination using the entity's primary key.
When set, the query returns the next page of records after the given PK value,
ordered by the PK column. Unlike StartRow (which uses OFFSET and is O(N) in
the offset), keyset pagination stays O(log N) regardless of how deep you go —
making it the right choice for jobs that walk entire large tables.
// Page 1
let result = await rv.RunView({
EntityName: 'Tax Returns',
ExtraFilter: 'AddressLine1 IS NOT NULL',
MaxRows: 500,
ResultType: 'entity_object'
}, contextUser);
// Page 2+
while (result.Results.length === 500) {
const lastId = result.Results[result.Results.length - 1].ID;
result = await rv.RunView({
EntityName: 'Tax Returns',
ExtraFilter: 'AddressLine1 IS NOT NULL',
AfterKey: CompositeKey.FromID(lastId),
MaxRows: 500,
ResultType: 'entity_object'
}, contextUser);
}
Constraints (throw AfterKeyNotSupportedError when violated):
RunViewParams.StartRow
for composite-PK entities).OrderBy, if set, must reference only the PK column (any ASC/DESC direction).StartRow.Caching behavior: When AfterKey is present, the query bypasses the server
cache (both read and write) — keyset queries are inherently single-use (each call
uses a different seek key), so caching them is pure overhead.
End-of-data signal: When a page returns fewer rows than MaxRows, you've
reached the end of the result set.
OptionalAggregatesOptional aggregate expressions to calculate on the full result set. These run as a parallel query and are NOT affected by pagination (StartRow/MaxRows). The WHERE clause (including filters and RLS) IS applied to aggregates.
Results are returned in AggregateResults in the same order as this array.
OptionalAuditoptional - if provided and either ForceAuditLog is set, or the entity's property settings for logging view runs are set to true, this will be used as the Audit Log Description.
OptionalBypassWhen set to true, bypasses ALL server-side caching — both the PreRunView cache check and the post-query auto-cache storage. The query always hits the database and the result is NOT stored in the cache.
Use this for maintenance/audit operations that need to see the true database state, especially when querying for records that were inserted via direct SQL (bypassing BaseEntity.Save() and its cache invalidation events).
OptionalCacheWhen set to true, the RunView will first check the LocalCacheManager for cached results. If cached results exist and are still valid, they will be returned immediately without hitting the server. This is useful for frequently-accessed, relatively-static data.
Note: The LocalCacheManager must be initialized before this can work. Cached results are automatically invalidated when the underlying entity data changes.
OptionalCacheOptional TTL (time-to-live) in milliseconds for cached results when CacheLocal is true. After this time, cached results will be considered stale and fresh data will be fetched. If not specified, the LocalCacheManager's default TTL will be used (typically 5 minutes).
OptionalEntityoptional - this is only used if ViewID/ViewName/ViewEntity are not provided, it is used for Dynamic Views in combination with the optional ExtraFilter
OptionalExcludeoptional - if set to true, the resulting data will filter out ANY records that were ever returned by this view, when the SaveViewResults property was set to true. This is useful if you want to run a particular view over time and make sure the results returned each time are new to the view.
OptionalExcludeoptional - if provided, records that were returned in the specified UserViewRunID will NOT be allowed in the result set. This is useful if you want to run a particular view over time and exclude a specific prior run's resulting data set. If you want to exclude ALL data returned from ALL prior runs, use the ExcludeDataFromAllPriorViewRuns property instead.
OptionalExtraAn optional SQL WHERE clause that you can add to the existing filters on a stored view. For dynamic views, you can either run a view without a filter (if the entity definition allows it with AllowAllRowsAPI=1) or filter with any valid SQL WHERE clause.
Accepts either a plain string (backward compatible) or a PlatformSQL object for multi-platform support. When a PlatformSQL object is provided, the appropriate platform-specific SQL is resolved automatically before the query is executed.
OptionalFieldsAn optional array of field names that you want returned. The RunView() function will always return ID so you don't need to ask for that. If you leave this null then for a dynamic view all fields are returned, and for stored views, the fields stored in it view configuration are returned.
OptionalForceoptional - if set to true, the view run will ALWAYS be logged to the Audit Log, regardless of the entity's property settings for logging view runs.
OptionalIgnoreoptional - if set to true, if there IS any UserViewMaxRows property set for the entity in question, it will be IGNORED. This is useful in scenarios where you want to programmatically run a view and get ALL the data back, regardless of the MaxRows setting on the entity.
OptionalMaxoptional - if provided, and if IgnoreMaxRows = false, this value will be used to constrain the total # of rows returned by the view. If this is not provided, either the default settings at the entity-level will be used, or if the entity has no UserViewMaxRows setting, all rows will be returned that match any filter, if provided.
OptionalOnOptional callback invoked when the cached result set for this exact query fingerprint is updated by another server instance (via Redis pub/sub).
Use this to react to cross-server cache invalidation — for example, to reload data in an engine's in-memory array, refresh a UI grid, or trigger a re-fetch.
Requirements:
RedisLocalStorageProvider must be configured as the local storage providerRedisLocalStorageProvider.StartListening() must have been called to enable pub/subInMemoryLocalStorageProvider (single-server, no pub/sub)Lifecycle: If the caller is short-lived (e.g., an Angular component), call
result.Unsubscribe() during cleanup (e.g., ngOnDestroy) to avoid memory leaks.
For long-lived callers like engines, the callback persists for the process lifetime.
OptionalOrderAn optional SQL ORDER BY clause that you can use for dynamic views, as well as to OVERRIDE the stored view's sorting order.
Accepts either a plain string (backward compatible) or a PlatformSQL object for multi-platform support. When a PlatformSQL object is provided, the appropriate platform-specific SQL is resolved automatically before the query is executed.
OptionalOverrideoptional - if you are providing the optional ExcludeUserViewRunID property, you can also optionally provide this filter which will negate the specific list of record IDs that are excluded by the ExcludeUserViewRunID property. This can be useful if you want to ensure a certain class of data is always allowed into your view and not filtered out by a prior view run.
OptionalResultResult Type is: 'simple', 'entity_object', or 'count_only' and defaults to 'simple'. If 'entity_object' is specified, the Results[] array will contain BaseEntity-derived objects instead of simple objects. This is useful if you want to work with the data in a more strongly typed manner and/or if you plan to do any update/delete operations on the data after it is returned. The 'count_only' option will return no rows, but the TotalRowCount property of the RunViewResult object will be populated.
OptionalSaveoptional - if set to true, the LIST OF ID values from the view run will be stored in the User View Runs entity and the newly created UserViewRun.ID value will be returned in the RunViewResult that the RunView() function sends back to ya.
OptionalStartoptional - if provided, this value will be used to offset the rows returned.
Note on deep pagination: StartRow is implemented via SQL OFFSET semantics,
which is O(N) in the offset value — early pages are fine, but deep pages (offset
in the tens or hundreds of thousands) get progressively slower because the server
has to enumerate and discard the skipped rows.
For background jobs and bulk processing that iterate through entire tables, prefer
AfterKey (keyset / seek pagination), which stays O(log N) regardless of depth.
UI grid pagination (a few hundred pages at most) is fine to keep on StartRow.
OptionalTelemetryOptional telemetry controls for this view. Use to mark a view that is intentionally
separate, repeated, or redundant — e.g. a live read of volatile state that deliberately
must NOT use a cached engine's copy — so the telemetry optimization/redundancy analyzers
(Duplicate RunView, Entity Already in Engine, Sequential Queries, Multiple Calls)
skip it instead of flagging it as noise. The optional Reason is recorded with the
telemetry event and surfaced in verbose telemetry logging for auditability.
OptionalUseroptional - string that represents a user "search" - typically from a text search option in a UI somewhere. This field is then used in the view filtering to search whichever fields are configured to be included in search in the Entity Fields definition. Search String is combined with the stored view filters as well as ExtraFilter with an AND.
OptionalViewoptional - this is the loaded instance of the BaseEntity (UserViewEntityComplete or a subclass of it). This is the preferred parameter to use IF you already have a view entity object loaded up in your code becuase by passing this in, the RunView() method doesn't have to lookup all the metadata for the view and it is faster. If you provide ViewEntity, ViewID/ViewName are ignored.
OptionalViewoptional - ID of the UserView record to run, if provided, ViewName is ignored
OptionalViewoptional - Name of the UserView record to run, if you are using this, make sure to use a naming convention so that your view names are unique. For example use a prefix like _Entity_View etc so that you're likely to have a single result. If more than one view is available that matches a provided view name an exception will be thrown.
StaticEqualsCompares two RunViewParams objects for equality by comparing their property values. This is useful for determining if params have actually changed vs just being a new object reference. Note: ViewEntity comparison uses reference equality since comparing loaded entity objects deeply is expensive.
First RunViewParams object (can be null)
Second RunViewParams object (can be null)
true if the params are equivalent, false otherwise
Parameters for running either a stored or dynamic view. A stored view is a view that is saved in the database and can be run either by ID or Name. A dynamic view is one that is not stored in the database and you provide parameters to return data as desired programatically.
This class is fully backward compatible with object literal syntax - you can still use:
{ EntityName: 'Users', ExtraFilter: 'Active=1' }and it will work as expected.