diff --git a/contents/docs/data-warehouse/run-sql-mcp.mdx b/contents/docs/data-warehouse/run-sql-mcp.mdx index 29a7f6e16228..a4c3889c69bd 100644 --- a/contents/docs/data-warehouse/run-sql-mcp.mdx +++ b/contents/docs/data-warehouse/run-sql-mcp.mdx @@ -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 @@ -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 @@ -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 diff --git a/contents/docs/data-warehouse/views/index.mdx b/contents/docs/data-warehouse/views/index.mdx index 5dd197798618..ec1c76cee95a 100644 --- a/contents/docs/data-warehouse/views/index.mdx +++ b/contents/docs/data-warehouse/views/index.mdx @@ -12,7 +12,7 @@ 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. @@ -20,9 +20,30 @@ For a query to be a valid view, all fields being accessed must be aliased (with ![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. @@ -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. -