Datasources

Overview

This folder contains implementations of Genesis datasource components, responsible for fetching data for Genesis Grid Pro components.

This document outlines the available features of our two "Grid Pro" datasources: <grid-pro-client-side-datasource> and <grid-pro-server-side-datasource>.

Enterprise features and licensing

Important: Server-side datasource features require AG Grid Enterprise licensing:

• Server-Side Row Model: Server-side datasource requires @ag-grid-enterprise/server-side-row-model
• Custom Sort Indicators: Server-side datasources automatically display always-visible sort indicators
• Advanced Filtering: Some advanced filtering features may require Enterprise modules

For production use, you must obtain appropriate AG Grid Enterprise licenses. Contact AG Grid for licensing information.

Enterprise module registration

REQUIRED for Server-Side Datasource Features

If you plan to use Server-Side datasource (<grid-pro-server-side-datasource>), you MUST register the appropriate AG Grid Enterprise module:

import { ModuleRegistry } from '@ag-grid-community/core';

// Required for Server-Side datasource (<grid-pro-server-side-datasource>)
import { ServerSideRowModelModule } from '@ag-grid-enterprise/server-side-row-model';

// Register the enterprise module
ModuleRegistry.registerModules([
  ServerSideRowModelModule, // Required for: <grid-pro-server-side-datasource>
]);

Module Requirements:

Feature	Required Module	Description
<grid-pro-server-side-datasource>	ServerSideRowModelModule	Server-side row model for large datasets with server-side operations

Note: This module requires a valid AG Grid Enterprise license for production use.

<grid-pro-client-side-datasource>

Client-side features

• Sorting: Order by any column, ASC or DESC.
• Filtering:
  • Filtering options are automatically generated based on the resource's metadata.
  • String Filters:
    • contains
    • not contains
    • equals
    • not equals
    • starts with
    • ends with
    • blank
    • not blank
  • Number/Date Filters:
    • equals
    • less than
    • less than or equal
    • greater than
    • greater than or equal
    • in range
• Filter Combinations (Max 2 filters can be combined):
  • filter1 AND filter2
  • filter1 OR filter2

Client-side notes

• Works with both DATASERVER and REQUEST_SERVER resources.
• Operations like sorting and filtering are performed on the client-side.
• Suitable for datasets that are small to medium in size and can be entirely loaded into the client.

Usage example

<rapid-grid-pro enable-row-flashing enable-cell-flashing>
  <grid-pro-client-side-datasource
    resource-name="ALL_TRADES"
    criteria="INSTRUMENT_ID == 'TSLA'"
  ></grid-pro-client-side-datasource>
</rapid-grid-pro>

<grid-pro-server-side-datasource>

Enterprise License Required: Server-side datasource requires AG Grid Enterprise licensing and the ServerSideRowModelModule to be registered (see Enterprise Module Registration above).

Server-side features

• Sorting: Order by any INDEX column/field, ASC or DESC.
  • This is a server limitation. For each column that needs to be sortable, you must have an index for it.
  • By default, sorting is disabled on all columns, but wherever a valid index is detected from the metadata, that column (field) will have sorting enabled.
  • If the user attempts to force sortable, we'll check its validity, warn in the logs if not, and mention other available indices, if any.
  • Custom Sort Indicators: Server-side datasources automatically display always-visible sort indicators on sortable columns, providing better visual feedback about which columns can be sorted even when not currently sorted.
• Filtering:
  • Filtering options are automatically generated, based on the resource's metadata.
  • String Filters:
    • blank
    • contains
    • equals
    • notBlank
    • notEqual
    • wordStartsWith
  • Number Filters:
    • equals
    • notEqual
    • greaterThan
    • greaterThanOrEqual
    • lessThan
    • lessThanOrEqual
    • inRange
    • blank
    • notBlank
  • Date Filters:
    • equals
    • lessThan
    • greaterThan
    • inRange
    • isToday
    • blank
    • notBlank

Server-side notes

• Operations like sorting and filtering are pushed to the back end.
  • Filtering uses CRITERIA_MATCH param.
  • Sorting uses ORDER_BY param.
  • Once filtering/sorting is applied, the datasource component resets itself, starting a new stream with the updated params.
• Limitations:
  • Sorting can only be applied to index fields/columns. Also mentioned here. More details here and here.
  • ROWS_COUNT doesn't reflect the correct amount when a CRITERIA_MATCH (filtering) is applied. For example, if a resource has 100 records and a criteria returns only 50, the server still reports 100. We have to calculate this manually.
• Suitable for large datasets where only a subset of data is loaded into the client based on user interactions.

Usage example

<rapid-grid-pro enable-row-flashing enable-cell-flashing>
  <grid-pro-server-side-datasource
    resource-name="ALL_TRADES"
    criteria="INSTRUMENT_ID == 'TSLA'"
  ></grid-pro-server-side-datasource>
</rapid-grid-pro>

Datasource attributes

There are many attributes that can be set on a datasource component. These attributes can be used to customize the behavior of the datasource and the grid component.

Resource attributes

Some resource related attributes are DATASERVER or REQUEST_SERVER specific while others can be used with both.

Attributes that are common between DATASERVER and REQUEST_SERVER

Name	Type	Default	Description	Example
resource-name	string	-	Required. The name of the target Data Server query or Request Server requestReply.	<grid-pro-client-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME"> <grid-pro-server-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME">
is-snapshot	boolean	false	Request a snapshot from the server.	<grid-pro-client-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" is-snapshot> <grid-pro-server-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" is-snapshot>
criteria	string	-	Clients can send a Groovy expression to perform filters on the query server; these remain active for the life of the subscription.	<grid-pro-client-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" criteria="price > 100"> <grid-pro-server-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" criteria="price > 100">
max-rows	number	250	Maximum number of rows to be returned as part of the initial message and any additional MORE_ROWS messages. This will not affect the number of rows displayed.	<grid-pro-client-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" max-rows="1000"> <grid-pro-server-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" max-rows="1000">
view-number	number	-	The desired view/page you want data from.	<grid-pro-client-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" view-number="2"> <grid-pro-server-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" view-number="2">

Common datasource properties

Name	Type	Description	Example
:rowDataMapper	Function	Allows grid data updates to be processed via an external function before applying in grid. Function to map the row data before it is sent to the grid. The function should return an array of objects, where each object represents a row in the grid.	<grid-pro-client-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" :rowDataMapper="${(data) => data.map((row) => ({ ...row, calculatedValue: row.value1 + row.value2 }))}"> <grid-pro-server-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" :rowDataMapper="${(data) => data.map((row) => ({ ...row, calculatedValue: row.value1 + row.value2 }))}">

info

Criteria use groovy expressions to filter responses from the back end.

DATASERVER only attributes

Name	Type	Default	Description	Example
fields	string	-	This optional parameter allows you to select a subset of fields from the query if the client is not interested in receiving all of them.	<grid-pro-client-side-datasource resource-name="DATASERVER_NAME" fields="name,price,quantity"> <grid-pro-server-side-datasource resource-name="DATASERVER_NAME" fields="id,timestamp,value">
max-view	number	1000	Maximum number of rows to track as part of a client "view".	<grid-pro-client-side-datasource resource-name="DATASERVER_NAME" max-view="500"> <grid-pro-server-side-datasource resource-name="DATASERVER_NAME" max-view="1000">
moving-view	boolean	false	If true, when the maximum number of rows defined in max-view is reached, the Data Server will start discarding the oldest rows (in terms of timestamp) and sending newer rows. If false, updates in the server will be sent to the front end regardless of order. Note that this will only update the UI; no changes will be performed in the database.	<grid-pro-client-side-datasource resource-name="DATASERVER_NAME" moving-view> <grid-pro-server-side-datasource resource-name="DATASERVER_NAME" moving-view>
order-by	string	-	This option can be used to select a Data Server index (defined in the Data Server query), which is especially useful if you want the data to be sorted in a specific way. By default, Data Server rows are returned in order of creation (from oldest database record to newest).	<grid-pro-client-side-datasource resource-name="DATASERVER_NAME" order-by="price"> <grid-pro-server-side-datasource resource-name="DATASERVER_NAME" order-by="timestamp">
reverse	boolean	false	This option changes the Data Server index iteration. For example, if you are using the default index, the query will return rows in order from the newest database records to the oldest.	<grid-pro-client-side-datasource resource-name="DATASERVER_NAME" reverse> <grid-pro-server-side-datasource resource-name="DATASERVER_NAME" reverse>

REQUEST_SERVER only attributes

Name	Type	Default	Description	Example
disable-polling	boolean	false	This option disables polling if set to true (data updates for the grid will not be fetched automatically).	<grid-pro-client-side-datasource resource-name="REQUEST_SERVER_NAME" disable-polling> <grid-pro-server-side-datasource resource-name="REQUEST_SERVER_NAME" disable-polling>
polling-interval	number	5000	This option enables you to set a custom polling frequency (in milliseconds) for a Request Server resource. Note that this option only works with Request Server resources; if your resource is a Data Server query, your grid is updated in real time.	<grid-pro-client-side-datasource resource-name="REQUEST_SERVER_NAME" polling-interval="5000"> <grid-pro-server-side-datasource resource-name="REQUEST_SERVER_NAME" polling-interval="3000">
request-auto-setup	boolean	true	This option, if set to true, will automatically set up the request based on the datasource's metadata.	<grid-pro-client-side-datasource resource-name="REQUEST_SERVER_NAME" request-auto-setup> <grid-pro-server-side-datasource resource-name="REQUEST_SERVER_NAME" request-auto-setup>

REQUEST_SERVER only properties

Name	Type	Description	Example
:request	any	Similar to fields but for Request Server scenarios. This optional parameter enables you to specify request fields, which can include wildcards.	<grid-pro-client-side-datasource resource-name="REQUEST_SERVER_NAME" :request="Trade.*"> <grid-pro-server-side-datasource resource-name="REQUEST_SERVER_NAME" :request="Position.*,Price.*"> <grid-pro-client-side-datasource resource-name="REQUEST_SERVER_NAME" :request="${() => ({ TRADE_ID: '00001' })}">

Component attributes

There are additional attributes that can affect the behaviour of a datasource component.

<grid-pro-client-side-datasource>

Name	Type	Default	Description	Example
restart-on-reconnection	boolean	true	This option, if set to true, will force the resource data to be reloaded upon a reconnection event.	<grid-pro-client-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" restart-on-reconnection>
keep-col-defs-on-clear-row-data	boolean	false	This option, if set to true, will retain column definitions upon a restart or clearRowData event.	<grid-pro-client-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" keep-col-defs-on-clear-row-data>

<grid-pro-server-side-datasource>

Name	Type	Default	Description	Example
zero-based-view-number	boolean	false	This option, if set to true, will make the starting VIEW_NUMBER zero-based (starting from 0 instead of 1).	<grid-pro-server-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" zero-based-view-number>
live-updates	boolean	false	Enable live updates for the grid. Only works with DATASERVER resources (StreamDatasource) right now.	<grid-pro-server-side-datasource resource-name="DATASERVER_OR_REQUEST_SERVER_NAME" live-updates>

Events emitted by <grid-pro-genesis-datasource>

The <grid-pro-genesis-datasource> component emits several custom events to notify consumers about important changes or errors. You can listen for these events on the component to react to data loading, errors, and other state changes.

List of events

Event Name	When It Fires	Payload Type & Example
datasource-init	When the datasource is successfully initialized and ready to load data.	(none)
datasource-error	When an error occurs during data loading, streaming, or initialization.	{ message: string } Example: { message: "Failed to load data" }
datasource-size-changed	When the number of rows in the datasource changes (e.g., after data update).	{ value: number, oldValue: number } Example: { value: 100, oldValue: 50 }
more-rows-changed	When the server indicates more rows are available to load (infinite scroll).	{ moreRows: boolean, sourceRef: string } Example: { moreRows: true, sourceRef: "abc123" }

Event details

• datasource-init

  • Description: Emitted when the datasource has been initialized and is ready to load or stream data.
  • Payload: None.

• datasource-error

  • Description: Emitted when an error occurs during any datasource operation (initialization, data loading, streaming, etc.).
  • Payload: { message: string } — A message describing the error.

• datasource-size-changed

  • Description: Emitted whenever the number of rows in the datasource changes (for example, after new data is loaded or rows are removed).
  • Payload: { value: number, oldValue: number } — The new and previous row counts.

• more-rows-changed

  • Description: Emitted when the server signals that more rows are available to be loaded (typically in infinite scroll scenarios).
  • Payload: { moreRows: boolean, sourceRef: string } — Indicates if more rows are available and provides a reference for loading them.

Summary

• Client-Side Datasource: Suitable for smaller datasets where all data can be loaded into the client. Operations like sorting and filtering are performed on the client side.
• Server-Side Datasource: Ideal for large datasets, where operations are pushed to the back end to ensure performance and consistency. Data is fetched as needed, based on user interactions. Requires AG Grid Enterprise licensing.