Release: profile query hotfix and identify docs

[izadoesdev]

Fixes profile_list/profile_detail failing in production: ClickHouse substitutes select aliases into GROUP BY and WHERE expressions, so the max(profile_id) alias made the visitor-key expression an illegal aggregation. Internal aliases renamed; external fields unchanged.

Also reworks the Identify Users docs page and adds it to the sidebar.

---

Summary by cubic

Fixes a production error in profile queries by renaming a shadowed aggregate alias that ClickHouse was substituting into GROUP BY/WHERE. Also updates the Identify Users docs and adds it to the sidebar.

• Bug Fixes

  • Renamed internal aggregate alias to latest_profile_id to avoid ClickHouse alias substitution errors.
  • Preserved external field as profile_id to keep the API response unchanged.

• New Features

  • Added “Identify Users” to the docs sidebar.
  • Reworked the guide with a quick start (tabs for React/Next.js, Script Tag, Node), clearer trait updates, revenue attribution examples, and a concise API reference.

^{Written for commit 5ddc363. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
databuddy-status	Ready	Preview, Comment	Jul 3, 2026 7:26pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
dashboard (staging)	Skipped		Jul 3, 2026 7:26pm
documentation (staging)	Skipped		Jul 3, 2026 7:26pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: fc4824a5-515d-423e-bbcb-e8a169ccd09e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch staging

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[unkey-deploy]

The latest updates on your projects. Learn more about Unkey Deploy

Name	Status	Preview	Inspect	Updated (UTC)
api (preview)	Ready	Visit Preview	Inspect	Jul 3, 2026 7:21pm

[greptile-apps]

Greptile Summary

This PR fixes a production breakage in the profile_list and profile_detail ClickHouse queries caused by alias substitution — ClickHouse was expanding the profile_id SELECT alias (bound to an aggregate) back into EVENTS_VISITOR_KEY's column reference inside GROUP BY, producing an illegal aggregate-inside-aggregate error. It also reworks the Identify Users docs page with tabbed examples and adds it to the docs sidebar.

• profiles.ts: Renames the internal CTE alias from profile_id to latest_profile_id in both visitor_profiles and profile_context, then re-aliases it back to profile_id in the outer SELECT — external field names are unchanged.
• identify-users.mdx: Adds tabbed code examples for React/Next.js, Script Tag, and Node.js; reorganises sections and headings.
• sidebar-content.tsx: Inserts the "Identify Users" entry (using the already-imported IdBadgeIcon) between "Configuration" and "Web SDKs".

Confidence Score: 5/5

Safe to merge — the ClickHouse fix is minimal and surgical, and the docs changes are self-contained.

The alias rename in both CTEs is correct and complete: the internal alias no longer shadows the profile_id column, eliminating the substitution chain, while the outer SELECT re-exposes profile_id to preserve the existing API contract. All three query builders (profile_list, profile_detail, profile_sessions) were checked — profile_sessions was unaffected and correctly left unchanged. The documentation and sidebar changes carry no functional risk.

No files require special attention.

Important Files Changed

Filename	Overview
packages/ai/src/query/builders/profiles.ts	Renames internal CTE aliases from profile_id to latest_profile_id in both profile_list and profile_detail queries to prevent ClickHouse alias substitution from turning a column reference inside EVENTS_VISITOR_KEY into an illegal aggregate; outer-facing field names are preserved.
apps/docs/content/docs/sdk/identify-users.mdx	Documentation rewrite adding tabbed framework examples (React/Next.js, Script Tag, and Node.js), reorganising Traits and Revenue Attribution sections, and improving introductory prose.
apps/docs/components/sidebar-content.tsx	Adds "Identify Users" sidebar entry with the already-imported IdBadgeIcon, placed between "Configuration" and "Web SDKs".

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[profile_list / profile_detail query] --> B[visitor_profiles CTE]
    B --> C["SELECT EVENTS_VISITOR_KEY as visitor_id\nmax(profile_id) as latest_profile_id\n...aggregates...\nGROUP BY visitor_id"]
    C -->|"Before fix: ClickHouse substituted 'profile_id' alias\n(= aggregate) into EVENTS_VISITOR_KEY in GROUP BY\n→ illegal aggregate-in-aggregate"| D["❌ ClickHouse error in production"]
    C -->|"After fix: alias renamed to 'latest_profile_id'\n→ no name clash with column 'profile_id'"| E["✅ GROUP BY visitor_id resolves cleanly"]
    E --> F[Outer SELECT]
    F --> G["vp.latest_profile_id AS profile_id\n(external field name unchanged)"]
    G --> H[API response / downstream consumers]

    subgraph profile_detail
        I["profile_context CTE\nargMaxIf(...) as latest_profile_id"]
        I --> J["pc.latest_profile_id AS profile_id"]
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[profile_list / profile_detail query] --> B[visitor_profiles CTE]
    B --> C["SELECT EVENTS_VISITOR_KEY as visitor_id\nmax(profile_id) as latest_profile_id\n...aggregates...\nGROUP BY visitor_id"]
    C -->|"Before fix: ClickHouse substituted 'profile_id' alias\n(= aggregate) into EVENTS_VISITOR_KEY in GROUP BY\n→ illegal aggregate-in-aggregate"| D["❌ ClickHouse error in production"]
    C -->|"After fix: alias renamed to 'latest_profile_id'\n→ no name clash with column 'profile_id'"| E["✅ GROUP BY visitor_id resolves cleanly"]
    E --> F[Outer SELECT]
    F --> G["vp.latest_profile_id AS profile_id\n(external field name unchanged)"]
    G --> H[API response / downstream consumers]

    subgraph profile_detail
        I["profile_context CTE\nargMaxIf(...) as latest_profile_id"]
        I --> J["pc.latest_profile_id AS profile_id"]
    end

Loading

_{Reviews (1): Last reviewed commit: "docs(sdk): rework identify guide and add..." | Re-trigger Greptile}

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Client as Frontend Client
    participant SDK as Browser SDK
    participant API as API Server
    participant Builder as ProfilesBuilder
    participant CH as ClickHouse
    participant DB as Profile Store

    Note over Client,DB: Identify Flow (precondition for profile data)
    Client->>SDK: identify(userId, traits)
    SDK->>API: POST /identify { profileId, traits }
    API->>DB: Store profile mapping
    DB-->>API: OK
    API-->>SDK: 200
    SDK-->>Client: Profile linked

    Note over Client,CH: Profile List Query
    Client->>API: GET /profiles (list/detail)
    API->>Builder: getProfiles()
    Builder->>Builder: Build SQL with CTE `visitor_profiles`
    Note over Builder: CHANGED: Internal alias renamed to `latest_profile_id`<br/>to avoid ClickHouse alias substitution in GROUP BY/WHERE
    Builder->>CH: SELECT ... max(profile_id) as latest_profile_id ...
    alt No alias conflict (fixed)
        CH->>CH: Execute query, GROUP BY visitor_id using `latest_profile_id` column name (not `profile_id`)
        CH-->>Builder: Result with column `latest_profile_id`
    else Previous alias `profile_id` would be substituted
        Note over CH: Would cause "Illegal aggregation" error
    end
    Builder->>Builder: Outer SELECT: `latest_profile_id` AS `profile_id`
    Builder-->>API: Result set with `profile_id` field
    API-->>Client: JSON response { profile_id: ..., ... }

Loading

<sub>Shadow auto-approve: would require human review. Code fix in profile query builder renames an internal alias, altering SQL logic. Though small, it could impact profile queries and requires human review.

Re-trigger cubic</sub>