Skip to content

docs(data-warehouse): document view folders feature #16146

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
inkeep wants to merge 2 commits into
base: master
Choose a base branch
from
+40 −20
Open

docs(data-warehouse): document view folders feature #16146

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2e115f1
docs: add view folders documentation for data warehouse views
inkeep[bot] Apr 2, 2026
7cbae48
docs: document folder_id parameter for view MCP tools
inkeep[bot] Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 17 additions & 17 deletions contents/docs/data-warehouse/run-sql-mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ This works in any MCP client – Cursor, Windsurf, Claude Code, VS Code, and oth

## How it works


With MCP, your coding agent can:

- **Run ad-hoc queries** – "How many `purchase_completed` events happened this week?" to quickly check data
Expand All @@ -21,28 +20,28 @@ With MCP, your coding agent can:

The MCP server provides these tools for running SQL:

| Tool | Description |
|------|-------------|
| `query-run` | Run a HogQL query and return results. Supports any valid HogQL syntax including joins, CTEs, subqueries, and window functions. |
| Tool | Description |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query-run` | Run a HogQL query and return results. Supports any valid HogQL syntax including joins, CTEs, subqueries, and window functions. |
| `query-generate-hogql-from-question` | Generate a HogQL query from a natural language question. Returns the query string so you can review or modify it before running. Requires [AI data processing approval](/docs/posthog-ai/allow-access). |
| `property-definitions` | List all event and person properties in your project. Useful for understanding what data is available before writing a query. |
| `event-definitions-list` | List all event definitions in your project with volume and usage data. |
| `property-definitions` | List all event and person properties in your project. Useful for understanding what data is available before writing a query. |
| `event-definitions-list` | List all event definitions in your project with volume and usage data. |

## View management tools

The MCP server also provides tools for managing [Data Warehouse views](/docs/data-warehouse/views):

| Tool | Description |
|------|-------------|
| `warehouse-saved-queries-list` | List all saved views in your project with their materialization status, sync frequency, and column schema. |
| `warehouse-saved-queries-retrieve` | Get full details of a specific view by ID, including its HogQL query and run history. |
| `warehouse-saved-queries-create` | Create a new view from a HogQL query. Upserts by name if a view with the same name exists. |
| `warehouse-saved-queries-partial-update` | Update a view's name, HogQL query, or sync frequency. |
| `warehouse-saved-queries-destroy` | Delete a view (soft delete). |
| `warehouse-saved-queries-materialize-create` | Enable materialization for a view with a 24-hour refresh schedule. |
| `warehouse-saved-queries-revert-materialization-create` | Revert a materialized view back to a virtual query. |
| `warehouse-saved-queries-run-create` | Trigger a manual refresh of a materialized view. |
| `warehouse-saved-queries-run-history-retrieve` | Get the last 5 materialization run statuses for a view. |
| Tool | Description |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `warehouse-saved-queries-list` | List all saved views in your project with their materialization status, sync frequency, and column schema. |
| `warehouse-saved-queries-retrieve` | Get full details of a specific view by ID, including its HogQL query and run history. |
| `warehouse-saved-queries-create` | Create a new view from a HogQL query. Upserts by name if a view with the same name exists. Accepts an optional `folder_id` to organize the view into a folder. |
| `warehouse-saved-queries-partial-update` | Update a view's name, HogQL query, sync frequency, or `folder_id` to move it between folders. |
| `warehouse-saved-queries-destroy` | Delete a view (soft delete). |
| `warehouse-saved-queries-materialize-create` | Enable materialization for a view with a 24-hour refresh schedule. |
| `warehouse-saved-queries-revert-materialization-create` | Revert a materialized view back to a virtual query. |
| `warehouse-saved-queries-run-create` | Trigger a manual refresh of a materialized view. |
| `warehouse-saved-queries-run-history-retrieve` | Get the last 5 materialization run statuses for a view. |

## Example prompts

Expand All @@ -68,6 +67,7 @@ For view management:
- `Materialize my 'revenue_summary' view for faster queries.`
- `Trigger a refresh of my 'user_metrics' materialized view.`
- `Show me the run history for my 'sales_data' view.`
- `Move my 'user_metrics' view into a folder.`

## Install the MCP server

Expand Down
26 changes: 23 additions & 3 deletions contents/docs/data-warehouse/views/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,17 +12,38 @@ In the PostHog data warehouse, you can save your most used queries as **views**

## Creating a view

Query views are created directly inside SQL insights. If the query has valid view characteristics, the **Save as view** button is enabled. When clicked, you are prompted to give the view a name which can then be referenced in other queries.
Query views are created directly inside SQL insights. If the query has valid view characteristics, the **Save as view** button is enabled. When clicked, you are prompted to give the view a name which can then be referenced in other queries.

For a query to be a valid view, all fields being accessed must be aliased (with the SQL `as` keyword). The alias names are how you access the fields on the view. This also means that we cannot use `SELECT *...` type SQL syntax for a query we would like to be a view since none of the columns are aliased.

> **Note:** Nested views are supported. You can create a view based on other views.

![valid view](https://res.cloudinary.com/dmukukwp6/image/upload/v1710055416/posthog.com/contents/images/features/data-warehouse/valid-view.png)

## Organizing views with folders

You can organize views into folders for easier navigation in the SQL editor sidebar.

### Creating folders

Right-click on the **Views** section in the SQL editor sidebar and select **New folder**. Enter a name for the folder and press **Submit**.

### Assigning views to folders

When saving a new view, select a folder from the **Folder** dropdown in the **Save as view** dialog. You can also create a new folder directly from this dropdown by clicking **+ Add new folder**.

To move existing views, drag and drop them into folders in the sidebar. You can also drag views back to the root level.

### Managing folders

Right-click a folder to access these options:

- **Rename folder** - Change the folder name
- **Delete folder** - Delete the folder and all views inside it. This cannot be undone.

## Extending PostHog models with views

Views are a powerful tool for extending existing PostHog models for easier data access. For example, if you wanted to associate your Stripe customer data with product usage data of your users, you would normally need to manually set up a join. With views, you can attach views to PostHog models so that you can directly access those fields on the PostHog table.
Views are a powerful tool for extending existing PostHog models for easier data access. For example, if you wanted to associate your Stripe customer data with product usage data of your users, you would normally need to manually set up a join. With views, you can attach views to PostHog models so that you can directly access those fields on the PostHog table.

To link a view to a [PostHog table](/docs/data-warehouse/sources/posthog), go to the [data warehouse section](https://app.posthog.com/data-warehouse/posthog), select the PostHog tab, and click **Link table to view**. Select your tables, keys to join, and press save. Once done, when you query that PostHog table, you can access the data from your view.

Expand All @@ -31,4 +52,3 @@ To link a view to a [PostHog table](/docs/data-warehouse/sources/posthog), go to
## Materializing views

Views can also be materialized and stored in the PostHog data warehouse, offering significant query performance benefits and improvements. You can learn more in the [materializing views](/docs/data-warehouse/views/materialize) guide.

Loading