AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

querying-posthog-data

Explains how to query PostHog data, defaulting to typed runners for supported product analytics. Read it before you write HogQL/SQL. Also read it before you call execute-sql against PostHog. Use it to find or aggregate PostHog entities. These entities include insights, dashboards, cohorts, feature flags, experiments, surveys, hog flows, warehouse data, and persons. Use it for trends, funnels, retention, lifecycle, paths, stickiness, web analytics, error tracking, logs, sessions, and LLM traces. Before you calculate a governed business or telemetry measure, check system.information_schema.metrics for an approved definition. Examples include MRR, activation, billable usage, active organizations, and failure rates. Use the approved definition before you derive a measure from raw events or use a typed domain tool. It also covers HogQL differences, system table schemas, functions, query examples, and schema discovery.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--querying-posthog-data at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 65

references/models-variables.md

SQL Variables and Filters

Variables

Variables enable dynamic value injection in HogQL queries using {variables.<code_name>} syntax.

Schema (system.insight_variables)

Column | Type | Description id | uuid | Primary key name | varchar(400) | Display name in UI code_name | varchar(400) | Query key (auto-generated from name) type | varchar(128) | String, Number, Boolean, List, or Date default_value | jsonb | Default value values | jsonb | Available values (List type only) is_multi | boolean | Whether a List variable accepts multiple selected values values_query | text | HogQL query whose first result column supplies List options values_query_connection_id | text | External data source connection values_query runs against (null for PostHog)

Types

Type | Example default_value String | "example" Number | 42 Boolean | true List | "$pageview" or ["$pageview", "$autocapture"] when is_multi is enabled Date | "2024-01-01" or a rolling value such as "-7d"

Usage

-- Basic
SELECT * FROM events WHERE event = {variables.event_names}

-- Optional string (empty check)
WHERE (coalesce({variables.org}, '') = '' OR properties.org = {variables.org})

-- Optional nullable (null check)
WHERE ({variables.browser} IS NULL OR properties.$browser = {variables.browser})

-- Multiselect List variable
WHERE event IN {variables.event_names}

List options can be entered manually or loaded from a HogQL query. For query-backed options, the first result column becomes the option values, and an optional second column supplies their display labels. Queries without a LIMIT return at most 100 rows, and the UI keeps at most 1000 options. The query can run against an external data source connection via values_query_connection_id.

Relative Date defaults resolve each time a query runs. For example, -7d means seven days before the current time.

code_name Generation

Auto-generated from name: strips non-alphanumeric characters (except spaces/underscores), replaces spaces with underscores, lowercases. Example: "Event Names" -> "event_names"

Queries

-- List all
SELECT id, name, code_name, type, default_value FROM system.insight_variables

-- Find by name
SELECT * FROM system.insight_variables WHERE name ILIKE '%event%'

-- Find by type
SELECT * FROM system.insight_variables WHERE type = 'List'

-- Get by code_name
SELECT * FROM system.insight_variables WHERE code_name = 'event_names'

Filter Placeholders

Dashboard/query-level filters injected into HogQL queries.

Available Placeholders

Placeholder | Description | When not set {filters} | Full filter expression | Returns TRUE {filters.dateRange.from} | Start date/time | Comparison skipped {filters.dateRange.to} | End date/time | Comparison skipped

Usage

-- Full filter (includes properties, date range, test account exclusions)
SELECT * FROM events WHERE {filters}

-- Direct date access
SELECT * FROM events
WHERE timestamp >= {filters.dateRange.from}
  AND timestamp < {filters.dateRange.to}

-- Combined with variables
SELECT * FROM events
WHERE event = {variables.event_names}
  AND timestamp >= {filters.dateRange.from}

Notes

  • filterTestAccounts and properties only apply via {filters}, not directly accessible
  • Date values support ISO format (2024-01-01) and relative strings (-7d, -1w)
  • When unset, date comparisons become TRUE = TRUE

Table-Specific Behavior

Table | Timestamp field events | timestamp sessions | $start_timestamp logs / log_attributes | timestamp groups | created_at