Skip to content

docs: dedupe walkthrough posts a record the server rejects #575

Closed as not planned

Description

@EricAndrechek

What

The dedupe walkthrough in docs/src/content/docs/development.md:243-252 posts a record the server rejects, and annotates it with a response the server never sends.

The page creates clicks itself at development.md:69-75 as page / button / score / received_timestamp. The walkthrough then posts:

{"event_id": "550e8400-...", "page": "/home"}

annotated # → {"ok":true} and then # → {"duplicate":true}.

Three things are wrong with that:

  • internal/discovery/validation.go:24 rejects any key not in the schema, so event_id alone makes this 400 {"error":"unknown column \"event_id\" for table \"clicks\""}. There is no carve-out for the dedupe id field: processRecord runs Validate first (internal/api/ingest.go:526) and only reads data[idField] afterwards (ingest.go:633).
  • button and score are non-nullable with no default (score Float64, button String), so they are required too — validation.go:41.
  • Consequently neither annotated response can occur.

Fix

Add event_id String to the DDL at development.md:69 and send a complete record in both calls:

{"event_id": "550e8400-...", "page": "/home", "button": "signup", "score": 42.5}

Why it is filed rather than fixed in #555

Found by a docs reviewer during #555, but it is pre-existing — not in that branch's delta — and unrelated to its subject (excluding computed columns from the INSERT column list). Changing the shared clicks DDL on that page has a wider blast radius than the PR warrants, since other examples on the page read against it. Worth doing as its own change so the DDL edit can be checked against every example that depends on it.

Related: the same class of error was just corrected in docs/src/content/docs/sdk/queries.md (insert examples that omitted required button/score) and in several api.md examples, so a sweep for "documented example vs the schema the same page pins" may turn up more.

Activity

  1. EricAndrechek commented on Sep 9, 2026

    @EricAndrechek
    MemberAuthor

    Duplicate of #547, which covers the same walkthrough more thoroughly — it already names both failure reasons (event_id is not a column, and button/score are non-nullable with no default) and cites the DDL 170 lines up on the same page. I filed this during the #555 review without searching first. Closing in favour of #547.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions