signals

What this skill does

# Querying Signals

## What Are Signals?

Signals are automated observations that PostHog generates by monitoring a customer's product data across multiple sources — error tracking, web analytics, experiments, session replay, and more. Each signal is a short natural-language description of something noteworthy (e.g. "Error rate spiked 3× on /checkout").

Signals are grouped into **Signal Reports**. When a report accumulates enough weight it gets summarized and assessed for actionability. A signal report represents a cluster of related observations that together describe a meaningful issue or trend.

Signals and their embeddings are stored in the `document_embeddings` ClickHouse table, queryable via HogQL through the `posthog:execute-sql` MCP tool. They may provide a useful way to semantically query for recent things that happened in the user's product.

## When to use this skill vs. `inbox-exploration`

The two skills cover different layers of the same product:

- **`inbox-exploration`** — curated report layer via dedicated MCP tools (`inbox-reports-list`, `inbox-reports-retrieve`, `inbox-source-configs-list`, `inbox-source-configs-retrieve`). Use for "what's in my inbox?", "what's actionable?", filtering reports by status / source / suggested reviewer, looking up a specific report by ID or URL.
- **This skill (`signals`)** — raw signal layer via HogQL on `document_embeddings`. Use when the curated report layer is not enough: semantic search over signal text, fetching every signal that contributed to a specific report, listing what kinds of signals exist, or any ad-hoc analytics that the report tools don't expose.

The typical pattern is to start with `inbox-exploration`, get a `report_id` or a sense of the area the user cares about, then drop into this skill when the user wants to see the raw observations.

## Table and Column Reference

The HogQL table alias is `document_embeddings`. HogQL automatically constrains queries to the current team — you never need to filter on `team_id`. Key columns for signals:

| Column          | Type           | Description                                                                  |
| --------------- | -------------- | ---------------------------------------------------------------------------- |
| `product`       | String         | Product bucket — always `'signals'` for signals                              |
| `document_type` | String         | Document type — always `'signal'` for signals                                |
| `model_name`    | String         | Embedding model — always `'text-embedding-3-small-1536'`                     |
| `document_id`   | String         | Unique signal ID (UUID)                                                      |
| `timestamp`     | DateTime64(3)  | When the signal was created                                                  |
| `inserted_at`   | DateTime64(3)  | When this row version was inserted (used for deduplication and soft deletes) |
| `content`       | String         | The signal description text                                                  |
| `metadata`      | String         | JSON string with report_id, source info, weight, deleted flag, etc           |
| `embedding`     | Array(Float64) | 1536-dimensional embedding vector                                            |

## Mandatory Filters

Every signals query MUST include all four of these filters. Missing any of them can cause the query to fail with an invalid model error, return wrong data, or trigger unnecessarily expensive scans:

```sql
WHERE model_name = 'text-embedding-3-small-1536'
  AND product = 'signals'
  AND document_type = 'signal'
  AND timestamp >= now() - INTERVAL 30 DAY
```

The `model_name` filter is especially critical — the HogQL engine uses it to route to the correct underlying ClickHouse table. If the `WHERE model_name = ...` equality filter is missing or uses an unknown model, the query will fail with an "Invalid model name" error (you cannot use `IN` or other expressions here).

The `product` and `document_type` filters are equally important — the same model contains data from multiple products (e.g. error tracking, AI memory). Without these filters you will get unrelated data mixed in.

The `timestamp` filter is required for performance — the table is partitioned by week and has a 3-month TTL. Always include a time bound using `now() - INTERVAL N DAY` (or `WEEK`, `MONTH`, etc.). Default to 30 days unless you have a reason to look further back. Generally, more recent data is more likely to be relevant, unless investigating a long-standing issue.

## Deduplication Pattern

The underlying table can contain multiple versions of the same signal (e.g. after a soft-delete re-emission). You MUST always deduplicate by wrapping reads in a subquery using `argMax(..., inserted_at)` grouped by `document_id`.

**Note:** HogQL supports `metadata.field_name` dot access on the raw `metadata` JSON column, but this type information is lost when the column passes through aggregate functions like `argMax()`. You MUST extract individual metadata fields inside the inner dedup subquery — do NOT pass the whole `metadata` blob through `argMax` and dot into it in the outer query, as this will fail with a type error.

HogQL's JSON dot access always extracts values as `Nullable(String)`, regardless of the underlying JSON type. This means `metadata.deleted` is the string `'true'`/`'false'`/`null`, not a Bool. Use `deleted != 'true'` — do NOT use `NOT deleted`.

```sql
SELECT ... FROM (
    SELECT
        document_id,
        argMax(content, inserted_at) as content,
        argMax(metadata.report_id, inserted_at) as report_id,
        argMax(metadata.source_product, inserted_at) as source_product,
        argMax(metadata.source_type, inserted_at) as source_type,
        argMax(metadata.deleted, inserted_at) as deleted,
        argMax(embedding, inserted_at) as embedding,
        argMax(timestamp, inserted_at) as signal_ts
    FROM document_embeddings
    WHERE model_name = 'text-embedding-3-small-1536'
      AND product = 'signals'
      AND document_type = 'signal'
      AND timestamp >= now() - INTERVAL 1 MONTH
    GROUP BY document_id
)
WHERE deleted != 'true'
```

Only select the `embedding` column in the inner subquery when you actually need it for similarity searches — it's a 1536-element float array and expensive to materialize otherwise.

## The `embedText()` Function

`embedText()` is a HogQL function that converts a text string into an embedding vector at query compile time. It calls the embedding API and inlines the resulting vector as a constant before executing the query. This means you can do semantic search in a single query without any external embedding step.

**Signature:** `embedText(text, model_name)`

- `text` — the string to embed. **Must be a string literal**, not a column reference.
- `model_name` — the embedding model to use. **For signals, always use `'text-embedding-3-small-1536'`.**

Both arguments must be literal strings. You cannot pass column values or expressions — the function resolves at compile time, not per row.

## `cosineDistance()` for Similarity Search

Use `cosineDistance(embedding, ...)` to rank signals by semantic similarity. Lower values = more similar. Always `ORDER BY distance ASC` and add a `LIMIT`.

```sql
cosineDistance(embedding, embedText('your search text', 'text-embedding-3-small-1536')) as distance
```

The embedding model (`text-embedding-3-small-1536`) uses matryoshka representation learning, so the embedding dimensions are ordered by importance. This means similarity search works well even at high dimensionality — the curse of dimensionality is not a significant concern here.

## Metadata JSON Fields

The `metadata` column is a JSON string. HogQL supports `metadata.field_name` dot access **only on the raw table column**. After aggregation (e.g. `argMax`), the JSON type is lost and dot access will fail. Always extract the fields you need inside the dedup