> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Table Widget

> Display multi-dimensional data in rows and columns with grouping and sorting

<Info>
  **Using Sample Data**: The examples on this page use fields from our <a href="/assets/sample-data/sample-evaluation.csv" download>sample dataset</a>. Download it and create an evaluation with it to follow along with this tutorial.
</Info>

<Frame>
  <img src="https://mintcdn.com/scalegp/3SJ3nurBJCdCWISt/images/v5/evaluation-dashboards/widget-types/table/table-base-result.png?fit=max&auto=format&n=3SJ3nurBJCdCWISt&q=85&s=3e9b4e04543052bd89c7d4f0aa4c2efb" alt="Table Widget Example" width="2448" height="996" data-path="images/v5/evaluation-dashboards/widget-types/table/table-base-result.png" />
</Frame>

## When to Use

Use table widgets to:

* Show detailed breakdowns by multiple dimensions
* Display ranked lists (top/bottom performers)
* Present multi-column statistical summaries
* Create export-friendly data views
* Compare metrics across categories
* Show individual item details

## Configuration

### Required Fields

<ParamField body="title" type="string" required>
  Widget display name shown on the dashboard
</ParamField>

<ParamField body="type" type="string" required>
  Must be set to "table"
</ParamField>

<ParamField body="query" type="object" required>
  SeriesQuery returning multiple rows
</ParamField>

### Query Requirements

Table widgets require a **SeriesQuery** with:

* At least one item in the `select` clause
* Can mix `COLUMN` and `AGGREGATION` expressions
* Supports `filter` for row filtering
* Supports `groupBy` for dimensional breakdowns
* Supports `limit` for top-N results

<Info>
  When using `groupBy`, all non-aggregated columns in `select` must appear in the `groupBy` array.
</Info>

## Creating in the UI

<Steps>
  <Step title="Open Widget Creator">
    From your dashboard, click "Add Widget" and select "Table"
  </Step>

  <Step title="Turn off Grouping (Optional)">
    Decide whether to group by columns or not by toggling the "Group By" toggle. If you turn off grouping, you will not be able to aggregate data.

    <Info>
      When grouping is turned on, we will automatically output the count of the group.
    </Info>
  </Step>

  <Step title="Select Columns">
    If aggregating, specify which columns to group by, if not grouping select the columns you want to display.
  </Step>

  <Step title="Enter Title">
    Give your table a descriptive name (e.g., "Average Scores by Agent")
  </Step>

  <Step title="Add Aggregations (Optional)">
    <Frame>
      <img src="https://mintcdn.com/scalegp/3SJ3nurBJCdCWISt/images/v5/evaluation-dashboards/widget-types/table/table-base-form-aggregation.png?fit=max&auto=format&n=3SJ3nurBJCdCWISt&q=85&s=25e5c3768d58a6624470a0b2a49a611b" alt="Table Aggregation Builder" width="2484" height="1678" data-path="images/v5/evaluation-dashboards/widget-types/table/table-base-form-aggregation.png" />
    </Frame>

    Add metrics to display:

    * **Columns**: Select fields from your data
    * **Aggregations**: Add computed metrics (AVG, COUNT, etc.)
  </Step>

  <Step title="Add Filters (Optional)">
    <Frame>
      <img src="https://mintcdn.com/scalegp/3SJ3nurBJCdCWISt/images/v5/evaluation-dashboards/widget-types/table/table-base-form-filter.png?fit=max&auto=format&n=3SJ3nurBJCdCWISt&q=85&s=63582210c2d2589c6e281cbf5b400406" alt="Table Filter Builder" width="2484" height="1678" data-path="images/v5/evaluation-dashboards/widget-types/table/table-base-form-filter.png" />
    </Frame>

    Add conditions to narrow the data, these conditions will be applied to the data before it is aggregated.
  </Step>

  <Step title="Create Widget">
    Click "Add" to display the table

    <Frame>
      <img src="https://mintcdn.com/scalegp/3SJ3nurBJCdCWISt/images/v5/evaluation-dashboards/widget-types/table/table-base-result-steps.png?fit=max&auto=format&n=3SJ3nurBJCdCWISt&q=85&s=6ec4fb35b830a552b904c5295ec9873b" alt="Created Table Widget" width="2444" height="656" data-path="images/v5/evaluation-dashboards/widget-types/table/table-base-result-steps.png" />
    </Frame>
  </Step>
</Steps>

## Conditional Formatting

Apply color-coded formatting rules to table cells to highlight important values at a glance. Conditional formatting is available on grouped tables (tables with aggregations).

<Frame>
  <img src="https://mintcdn.com/scalegp/xaXMSDdu7hTWY1jk/images/v5/evaluation-dashboards/widget-types/table/table-conditional-formatting.png?fit=max&auto=format&n=xaXMSDdu7hTWY1jk&q=85&s=473ece437616d7587ef967b968c78049" alt="Table with Conditional Formatting" width="2722" height="598" data-path="images/v5/evaluation-dashboards/widget-types/table/table-conditional-formatting.png" />
</Frame>

### Enabling in the UI

When creating or editing a grouped table widget, expand the "Formatting" section to add rules. Select the aggregation column to format, choose a rule type, and pick a color.

<Frame>
  <img src="https://mintcdn.com/scalegp/xaXMSDdu7hTWY1jk/images/v5/evaluation-dashboards/widget-types/table/table-conditional-formatting-form.png?fit=max&auto=format&n=xaXMSDdu7hTWY1jk&q=85&s=cd7d3467b681c585dc6f403ea0ffabfc" alt="Conditional Formatting Form" width="1400" height="900" data-path="images/v5/evaluation-dashboards/widget-types/table/table-conditional-formatting-form.png" />
</Frame>

### Rule Types

#### Threshold Rules

Apply formatting when a cell value meets a comparison condition.

| Field              | Type   | Description                                        |
| ------------------ | ------ | -------------------------------------------------- |
| `type`             | string | Must be `"threshold"`                              |
| `column`           | string | Aggregation column name to format                  |
| `operator`         | string | One of: `=`, `>`, `<`, `>=`, `<=`                  |
| `threshold`        | number | Value to compare against                           |
| `background_color` | string | One of: `green`, `yellow`, `red`, `purple`, `blue` |

#### Range Rules

Apply formatting when a cell value falls within a range (inclusive).

| Field              | Type   | Description                                        |
| ------------------ | ------ | -------------------------------------------------- |
| `type`             | string | Must be `"range"`                                  |
| `column`           | string | Aggregation column name to format                  |
| `min_threshold`    | number | Lower bound (inclusive)                            |
| `max_threshold`    | number | Upper bound (inclusive)                            |
| `background_color` | string | One of: `green`, `yellow`, `red`, `purple`, `blue` |

### SDK Example

<CodeGroup>
  ```python Python theme={null}
  widget = client.evaluation_dashboards.widgets.create(
      dashboard_id=dashboard.id,
      title="Agent Scores with Formatting",
      type="table",
      query={
          "select": [
              {"expression": {"type": "COLUMN", "column": "agent_name", "source": "data"}},
              {
                  "expression": {
                      "type": "AGGREGATION",
                      "function": "AVG",
                      "column": "overall_score",
                      "source": "data"
                  },
                  "alias": "avg_score"
              }
          ],
          "groupBy": ["agent_name"]
      },
      config={
          "conditional_formatting": [
              {
                  "type": "threshold",
                  "column": "avg_score",
                  "operator": ">=",
                  "threshold": 90,
                  "background_color": "green"
              },
              {
                  "type": "range",
                  "column": "avg_score",
                  "min_threshold": 70,
                  "max_threshold": 89,
                  "background_color": "yellow"
              },
              {
                  "type": "threshold",
                  "column": "avg_score",
                  "operator": "<",
                  "threshold": 70,
                  "background_color": "red"
              }
          ]
      }
  )
  ```

  ```json JSON theme={null}
  {
    "title": "Agent Scores with Formatting",
    "type": "table",
    "query": {
      "select": [
        {"expression": {"type": "COLUMN", "column": "agent_name", "source": "data"}},
        {
          "expression": {"type": "AGGREGATION", "function": "AVG", "column": "overall_score", "source": "data"},
          "alias": "avg_score"
        }
      ],
      "groupBy": ["agent_name"]
    },
    "config": {
      "conditional_formatting": [
        {
          "type": "threshold",
          "column": "avg_score",
          "operator": ">=",
          "threshold": 90,
          "background_color": "green"
        },
        {
          "type": "range",
          "column": "avg_score",
          "min_threshold": 70,
          "max_threshold": 89,
          "background_color": "yellow"
        },
        {
          "type": "threshold",
          "column": "avg_score",
          "operator": "<",
          "threshold": 70,
          "background_color": "red"
        }
      ]
    }
  }
  ```
</CodeGroup>

### Formatting Behavior

* Rules are evaluated in order -- the **first matching rule wins**
* Only applies to aggregation columns in grouped tables
* Available colors: `green`, `yellow`, `red`, `purple`, `blue`
* For percentage columns, formatting comparisons use the display value (0-100), not the raw decimal (0-1)

## Output Format

Table widgets return an array of row objects:

```json theme={null}
{
  "type": "series",
  "data": [
    {"category": "Quality", "count": 342, "avg_score": 0.89},
    {"category": "Accuracy", "count": 298, "avg_score": 0.85},
    {"category": "Helpfulness", "count": 411, "avg_score": 0.91}
  ]
}
```

Each object in the `data` array represents one row, with keys corresponding to column names.

## Example Use Cases

### Use Case 1: Agent Performance Breakdown

Show statistics grouped by agent with multiple metrics.

<Frame>
  <img src="https://mintcdn.com/scalegp/3SJ3nurBJCdCWISt/images/v5/evaluation-dashboards/widget-types/table/table-agent-breakdown.png?fit=max&auto=format&n=3SJ3nurBJCdCWISt&q=85&s=c27d3734925fb1700fe13aecb1b9b3ec" alt="Agent Performance Table" width="2484" height="2260" data-path="images/v5/evaluation-dashboards/widget-types/table/table-agent-breakdown.png" />
</Frame>

<CodeGroup>
  ```python Python theme={null}
  widget = client.evaluation_dashboards.widgets.create(
      dashboard_id=dashboard.id,
      title="Performance by Agent",
      type="table",
      query={
          "select": [
              {
                  "expression": {
                      "type": "COLUMN",
                      "column": "agent_name",
                      "source": "data"
                  }
              },
              {
                  "expression": {
                      "type": "AGGREGATION",
                      "function": "COUNT",
                      "column": "*"
                  }
              },
              {
                  "expression": {
                      "type": "AGGREGATION",
                      "function": "AVG",
                      "column": "overall_score",
                      "source": "data"
                  }
              },
              {
                  "expression": {
                      "type": "AGGREGATION",
                      "function": "MIN",
                      "column": "overall_score",
                      "source": "data"
                  }
              },
              {
                  "expression": {
                      "type": "AGGREGATION",
                      "function": "MAX",
                      "column": "overall_score",
                      "source": "data"
                  }
              }
          ],
          "groupBy": ["agent_name"],
      }
  )
  ```

  ```json JSON theme={null}
  {
    "title": "Performance by Agent",
    "type": "table",
    "query": {
      "select": [
        {"expression": {"type": "COLUMN", "column": "agent_name", "source": "data"}},
        {"expression": {"type": "AGGREGATION", "function": "COUNT", "column": "*"}},
        {"expression": {"type": "AGGREGATION", "function": "AVG", "column": "overall_score", "source": "data"}},
        {"expression": {"type": "AGGREGATION", "function": "MIN", "column": "overall_score", "source": "data"}},
        {"expression": {"type": "AGGREGATION", "function": "MAX", "column": "overall_score", "source": "data"}}
      ],
      "groupBy": ["agent_name"]
    }
  }
  ```
</CodeGroup>

***

### Use Case 2: Top 10 Highest-Scoring Evaluations

Display the best-performing individual evaluations without aggregation.

<Info>
  In the UI sort using the table header, this will not be reflected in the query.
</Info>

<Frame>
  <img src="https://mintcdn.com/scalegp/3SJ3nurBJCdCWISt/images/v5/evaluation-dashboards/widget-types/table/table-top-10-items.png?fit=max&auto=format&n=3SJ3nurBJCdCWISt&q=85&s=6edf26fa2ed1609ed031497726736187" alt="Top 10 Evaluations Table" width="2484" height="2260" data-path="images/v5/evaluation-dashboards/widget-types/table/table-top-10-items.png" />
</Frame>

<CodeGroup>
  ```python Python theme={null}
  widget = client.evaluation_dashboards.widgets.create(
      dashboard_id=dashboard.id,
      title="Top 10 Evaluations",
      type="table",
      query={
          "select": [
              {
                  "expression": {
                      "type": "COLUMN",
                      "column": "agent_name",
                      "source": "data"
                  }
              },
              {
                  "expression": {
                      "type": "COLUMN",
                      "column": "task_type",
                      "source": "data"
                  }
              },
              {
                  "expression": {
                      "type": "COLUMN",
                      "column": "overall_score",
                      "source": "data"
                  }
              }
          ],
          "orderBy": [
              {
                  "column": "overall_score",
                  "direction": "DESC"
              }
          ],
          "limit": 10
      }
  )
  ```

  ```json JSON theme={null}
  {
    "title": "Top 10 Evaluations",
    "type": "table",
    "query": {
      "select": [
        {"expression": {"type": "COLUMN", "column": "agent_name", "source": "data"}},
        {"expression": {"type": "COLUMN", "column": "task_type", "source": "data"}},
        {"expression": {"type": "COLUMN", "column": "overall_score", "source": "data"}}
      ],
      "orderBy": [{"column": "overall_score", "direction": "DESC"}],
      "limit": 10
    }
  }
  ```
</CodeGroup>

***

### Use Case 3: Agent Comparison with Multiple Metrics

Compare agents across several statistical measures including accuracy and relevance.

<Frame>
  <img src="https://mintcdn.com/scalegp/3SJ3nurBJCdCWISt/images/v5/evaluation-dashboards/widget-types/table/table-agent-comparison.png?fit=max&auto=format&n=3SJ3nurBJCdCWISt&q=85&s=0bc5687ce49ad7a584177afad49533ec" alt="Agent Comparison Table" width="2484" height="2260" data-path="images/v5/evaluation-dashboards/widget-types/table/table-agent-comparison.png" />
</Frame>

<CodeGroup>
  ```python Python theme={null}
  widget = client.evaluation_dashboards.widgets.create(
      dashboard_id=dashboard.id,
      title="Agent Performance Comparison",
      type="table",
      query={
          "select": [
              {
                  "expression": {
                      "type": "COLUMN",
                      "column": "agent_name",
                      "source": "data"
                  }
              },
              {
                  "expression": {
                      "type": "AGGREGATION",
                      "function": "COUNT",
                      "column": "*"
                  }
              },
              {
                  "expression": {
                      "type": "AGGREGATION",
                      "function": "AVG",
                      "column": "overall_score",
                      "source": "data"
                  }
              },
              {
                  "expression": {
                      "type": "AGGREGATION",
                      "function": "AVG",
                      "column": "accuracy_score",
                      "source": "data"
                  }
              },
              {
                  "expression": {
                      "type": "AGGREGATION",
                      "function": "AVG",
                      "column": "relevance_score",
                      "source": "data"
                  }
              }
          ],
          "groupBy": ["agent_name"]
      }
  )
  ```

  ```json JSON theme={null}
  {
    "title": "Agent Performance Comparison",
    "type": "table",
    "query": {
      "select": [
        {"expression": {"type": "COLUMN", "column": "agent_name", "source": "data"}},
        {"expression": {"type": "AGGREGATION", "function": "COUNT", "column": "*"}},
        {"expression": {"type": "AGGREGATION", "function": "AVG", "column": "overall_score", "source": "data"}},
        {"expression": {"type": "AGGREGATION", "function": "AVG", "column": "accuracy_score", "source": "data"}},
        {"expression": {"type": "AGGREGATION", "function": "AVG", "column": "relevance_score", "source": "data"}}
      ],
      "groupBy": ["agent_name"]
    }
  }
  ```
</CodeGroup>

***

### Use Case 4: Low-Scoring Evaluations Review

Show evaluations scoring below 80 that need attention.

<Frame>
  <img src="https://mintcdn.com/scalegp/3SJ3nurBJCdCWISt/images/v5/evaluation-dashboards/widget-types/table/table-filtered-items.png?fit=max&auto=format&n=3SJ3nurBJCdCWISt&q=85&s=051d10cdd369cf2ac6fe1a0fbd792721" alt="Filtered Evaluations Table" width="2484" height="2260" data-path="images/v5/evaluation-dashboards/widget-types/table/table-filtered-items.png" />
</Frame>

<CodeGroup>
  ```python Python theme={null}
  widget = client.evaluation_dashboards.widgets.create(
      dashboard_id=dashboard.id,
      title="Low-Scoring Evaluations",
      type="table",
      query={
          "select": [
              {"expression": {"type": "COLUMN", "column": "agent_name", "source": "data"}},
              {"expression": {"type": "COLUMN", "column": "task_type", "source": "data"}},
              {"expression": {"type": "COLUMN", "column": "overall_score", "source": "data"}},
              {"expression": {"type": "COLUMN", "column": "accuracy_score", "source": "data"}}
          ],
          "filter": {
              "conditions": [
                  {
                      "column": "overall_score",
                      "source": "data",
                      "operator": "<",
                      "value": 80
                  }
              ]
          }
      }
  )
  ```

  ```json JSON theme={null}
  {
    "title": "Low-Scoring Evaluations",
    "type": "table",
    "query": {
      "select": [
        {"expression": {"type": "COLUMN", "column": "agent_name", "source": "data"}},
        {"expression": {"type": "COLUMN", "column": "task_type", "source": "data"}},
        {"expression": {"type": "COLUMN", "column": "overall_score", "source": "data"}},
        {"expression": {"type": "COLUMN", "column": "accuracy_score", "source": "data"}}
      ],
      "filter": {
        "conditions": [
          {
            "column": "overall_score",
            "source": "data",
            "operator": "<",
            "value": 80
          }
        ]
      }
    }
  }
  ```
</CodeGroup>

## Related Documentation

* [Query Language Reference](../query-language) - `GROUP BY` and `ORDER BY` syntax
* [Bar Chart Widget](./bar) - Visual alternative to tables
* [Metric Widget](./metric) - For single-value displays
* [API Reference](/reference/v5/evaluation-dashboards) - Programmatic table creation