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

# JSON Column Parsing

> Automatically expand nested JSON columns into individual fields for charts and filters.

## Overview

Many databases store semi-structured data in JSON columns. JSON Column Parsing lets you expand these nested fields into separate, queryable columns - no ETL pipeline needed. Once activated, JSON properties appear as individual columns in your charts and filters.

**Before:** A single `metadata` column containing `{"region": "US", "plan": "pro", "mrr": 450}`

**After:** Three separate columns - `metadata.region`, `metadata.plan`, `metadata.mrr` - each usable in axes, filters, and groupings.

### Supported Databases

JSON parsing works with **Postgres**, **BigQuery**, **ClickHouse**, and databases connected via the **Data Plane**. The system generates the correct JSON extraction syntax for each database type automatically.

## Step 1: Recompute Connection Metadata

Before enabling JSON parsing, make sure your connection metadata is up to date.

1. Navigate to the **Connections** page
2. Find the connection that contains your JSON columns
3. Click **Recompute Metadata**
4. Wait for the metadata refresh to complete

<Frame>
  <img src="https://mintcdn.com/upsolve/dfxImnNgd-pHexMB/images/json-columns/recompute-metadata.png?fit=max&auto=format&n=dfxImnNgd-pHexMB&q=85&s=cfeaed94fb806fff02810dd1e762fafe" alt="Recompute metadata button on the connections page" width="824" height="214" data-path="images/json-columns/recompute-metadata.png" />
</Frame>

## Step 2: Activate JSON Parsing on a Column

After metadata is refreshed, columns containing JSON data will show a type of `json`.

1. In the metadata viewer, select the table containing your JSON column
2. Find the column with type `json`
3. Click the **Expose JSON** button next to it
4. A success notification confirms the column is now JSON-parsed

<Frame>
  <img src="https://mintcdn.com/upsolve/dfxImnNgd-pHexMB/images/json-columns/expose-json-button.png?fit=max&auto=format&n=dfxImnNgd-pHexMB&q=85&s=4d02d3032b4994045e795606deefe0c6" alt="Expose JSON button next to a json-type column" width="1400" height="1780" data-path="images/json-columns/expose-json-button.png" />
</Frame>

Once activated, the button is replaced with a green checkmark and "JSON" label.

<Frame>
  <img src="https://mintcdn.com/upsolve/dfxImnNgd-pHexMB/images/json-columns/json-parsed-confirmed.png?fit=max&auto=format&n=dfxImnNgd-pHexMB&q=85&s=fddabb640a12a1b8c2e5c2fa594891a3" alt="Column showing green JSON parsed confirmation" width="1402" height="1796" data-path="images/json-columns/json-parsed-confirmed.png" />
</Frame>

## Step 3: Use JSON Fields in Charts

The parsed JSON properties are now available as separate columns when building charts.

1. Go to your **Dashboard**
2. Create a new chart or edit an existing one
3. In the **Raw Tables** section, select the table with the JSON column
4. Save the chart

When the chart loads, all nested JSON properties appear as individual columns (e.g., `metadata.region`, `metadata.plan`).

<Frame>
  <img src="https://mintcdn.com/upsolve/dfxImnNgd-pHexMB/images/json-columns/chart-json-columns.png?fit=max&auto=format&n=dfxImnNgd-pHexMB&q=85&s=e8a5e51545ae42f83962963214ac894a" alt="Chart builder showing expanded JSON properties as separate columns" width="704" height="1332" data-path="images/json-columns/chart-json-columns.png" />
</Frame>

You can use these expanded columns for:

* **X-Axis and Y-Axis** values
* **Group By** segmentation
* **Aggregations** (sum, count, avg on numeric JSON properties)

<Frame>
  <img src="https://mintcdn.com/upsolve/dfxImnNgd-pHexMB/images/json-columns/chart-with-json-data.png?fit=max&auto=format&n=dfxImnNgd-pHexMB&q=85&s=d1101bead3e58dc93865ad2680c2e30d" alt="Rendered chart using JSON column data" width="1926" height="1008" data-path="images/json-columns/chart-with-json-data.png" />
</Frame>

## Step 4: Filter by JSON Fields

Parsed JSON fields also appear in the filter panel, letting users filter dashboards by nested properties.

1. Open the **Filters** section of your dashboard or chart
2. After selecting raw tables, the nested JSON properties appear in the filter column dropdown
3. Select a JSON property to filter by (e.g., `metadata.region`)
4. Choose a filter type (equals, contains, etc.) and set the value

<Frame>
  <img src="https://mintcdn.com/upsolve/dfxImnNgd-pHexMB/images/json-columns/filter-json-fields.png?fit=max&auto=format&n=dfxImnNgd-pHexMB&q=85&s=9ffe32b90620ed5a13425bd1a1294640" alt="Filter panel showing JSON properties as filterable columns" width="1976" height="1544" data-path="images/json-columns/filter-json-fields.png" />
</Frame>

All standard filter types work with JSON fields:

* **Input** filters (equals, contains, starts with)
* **Select** filters (single and multi-select)
* **Number** filters (greater than, less than, equal to) for numeric JSON properties
* **Date** filters for date-typed JSON properties

## Notes

* JSON parsing happens at query time. The original JSON column is replaced by its expanded properties in the chart's SQL query.
* If the JSON structure changes (new keys added), recompute metadata and re-save the chart to pick up new fields.
* Column names use dot notation (e.g., `metadata.region`) to indicate nesting.
* Deeply nested JSON is supported - each level is separated by dots (e.g., `metadata.address.city`).