Retrieving data for UI components

User interface (UI) components rely on data to display meaningful information. In the C3 AI Platform, specifications define how UI components retrieve and structure data. This topic focuses on UiSdlBaseDataGridDataSpec for structured records and UiSdlTimeseriesLineBarChartDataSpec for time-series data visualization. These Types configure filtering criteria, column settings, and data evaluation logic within UI components. Instead of calling methods like fetch or evalMetric, components retrieve data based on a JSON configuration.

Copy link to this section

Understanding JSON configuration in UI components

A specification, or spec, defines how a UI component retrieves, processes, and displays data. Users configure UI components by providing JSON files that describe the data sources, filtering rules, and display settings. These JSON configurations directly map to the Type definitions that dictate component behavior.

Each JSON file follows a structured format, specifying:

• Component Type (type): Defines which UI component will be rendered.
• Data Specification (dataSpec): Determines how data will be retrieved.
• Filtering and Sorting Rules: Applies conditions to limit data retrieval.
• Column or Series Configuration: Specifies what fields or metrics should appear in the UI.

Since UI components rely on JSON-driven configurations, developers and non-developers can adjust settings without writing additional code.

Copy link to this section

Retrieving relational data for UI components

To retrieve and display structured entity data in grid-based components, use UiSdlBaseDataGridDataSpec. The filter property applies conditions to limit retrieved records, and columnFields specifies which data fields appear in the UI.

Copy link to this section

Understanding UiSdlDataGridDataSpec

The UiSdlDataGridDataSpec Type defines how structured data is retrieved and displayed in UiSdlDataGrid components. The dataSpec field in a UiSdlDataGrid JSON configuration references an instance of UiSdlDataGridDataSpec, ensuring that data retrieval follows the predefined specifications.

A JSON configuration for a UiSdlDataGrid might look like this:

{
  "type": "UiSdlConnected<UiSdlDataGrid>",
  "component": {
    "header": {
      "title": "Wind Turbine Dataset"
    },
    "dataSpec": {
      "dataType": "WindTurbine",
      "filter": "location == 'San Francisco'",
      "columnFields": [
        {
          "fieldName": "id",
          "label": "ID"
        },
        {
          "fieldName": "location",
          "label": "Location"
        },
        {
          "fieldName": "manufacturer",
          "label": "Manufacturer"
        }
      ]
    }
  }
}

To understand how to create the JSON definition for a UiSdlDataGrid UI component, go to the API reference for UiSdlDataGrid. You can add all fields of that Type to your JSON as a configuration.

Copy link to this section

When data retrieval occurs

• UiSdlBaseDataGridDataSpec dynamically applies filters to ensure UI components display relevant entity records.
• The component retrieves data during initialization and updates the displayed records when users modify filters or pagination settings.
• The filter property defines which records the component retrieves and displays.

Copy link to this section

Evaluating time-series data in UI components

To retrieve and visualize time-series data in UI charts, use UiSdlTimeseriesLineBarChartDataSpec. Instead of directly fetching data, this Type evaluates metrics using predefined configurations.

Copy link to this section

Understanding UiSdlTimeseriesLineBarChartDataSpec

Time-series data retrieval differs from entity-based retrieval because it evaluates values over time rather than fetching static records. The UiSdlTimeseriesLineBarChartDataSpec Type defines how these values are retrieved and visualized.

A JSON configuration for a UiSdlTimeseriesLineBarChart component:

{
  "type": "UiSdlConnected<UiSdlTimeseriesLineBarChart>",
  "component": {
    "header": {
      "title": "Wind Turbine Power Output"
    },
    "dataSpec": {
      "dataType": "WindTurbine",
      "evaluateAction": "EVAL",
      "interval": "DAY",
      "timeRangeStart": "2024-01-01T00:00:00Z",
      "timeRangeEnd": "2024-01-07T00:00:00Z",
      "bindings": [
        {
          "metricName": "powerOutput",
          "fieldName": "power"
        }
      ]
    }
  }
}

To learn how to create the JSON definition for a UiSdlTimeseriesLineBarChart UI component, navigate to the API reference of {@ UiSdlTimeseriesLineBarChartDataSpec}. You can add all fields of that Type to your JSON as a configuration.

Copy link to this section

How FeatureEvaluatable Relates to Time-Series Data Retrieval

Time-series evaluation often involves features, which represent computed values over time. The FeatureEvaluatable Type provides evaluation methods like evalFeature and evalFeatureSet, which retrieve and compute data for specific features.

For example, evaluating a feature using FeatureEvaluatable:

wt1 = c3.WindTurbine.make({'id': 'TURBINE-1'})
wt1.evalFeature(feature="activePowerAvgFeature", start='2018-01-01', end='2022-01-01')

This evaluation aligns with UiSdlTimeseriesLineBarChartDataSpec, where the "evaluateAction": "EVAL" instructs the system to retrieve and compute time-series metrics.

Copy link to this section

Choosing the Right Approach

• Use UiSdlBaseDataGridDataSpec for structured entity records with dynamic filtering.
• Use UiSdlTimeseriesLineBarChartDataSpec for evaluating metric values over time.