Session 16: ClickHouse parity audit and documentation hardening - #33
Merged
Conversation
…ntation hardening Audit ClickHouse parity against official parametric functions documentation. Fix strict_deduplication mode mapping to match ClickHouse semantics (alias for strict). Add quality standards, session protocol, and web analytics project plan. Changes: - Fix FunnelMode::parse_mode_str: 'strict_deduplication' now maps to STRICT (0x01), matching ClickHouse where it is an alias for 'strict'. The previous timestamp-based dedup behavior is now available as 'timestamp_dedup'. - Update FunnelMode Display: STRICT_DEDUPLICATION displays as 'timestamp_dedup' - Add test_parse_modes_all_modes_including_extensions test (435 total) - Update CLAUDE.md: precise ClickHouse parity scope table, mode mapping details, extensions list, known semantic differences, mandatory session protocol, anti-pattern list, Session 16 entry - Update clickhouse-compatibility.md: non-behavioral function scope table, semantic difference notes, extensions section - Update window-funnel.md, faq.md: corrected mode tables - Update CHANGELOG.md: strict_deduplication mapping change - Update SQL test comment for strict_deduplication - Add WEB_ANALYTICS_PLAN.md: comprehensive project plan for DuckDB-based web analytics showcasing the behavioral extension Verified: 435 tests + 1 doc-test pass, zero clippy warnings, zero fmt issues. https://claude.ai/code/session_01MvYKE1YxJC564kEQCkq3HL
…plan details - clickhouse-compatibility.md: Replace terse scope table with rigorous per-function analysis (signature, return type, what it does, why not behavioral) for all 4 out-of-scope functions - CLAUDE.md: Expand scope table with per-function detail and link to full justification document - WEB_ANALYTICS_PLAN.md: Add tiered project name candidates with availability verification, framework evaluation (Axum selected), quality standards matching duckdb-behavioral, CI/CD pipeline requirements, testing requirements, updated sprint plans https://claude.ai/code/session_01MvYKE1YxJC564kEQCkq3HL
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rigorous verification of ClickHouse parity claims against official documentation, with corrections to mode semantics and comprehensive documentation updates. Discovered and fixed
'strict_deduplication'mode mapping, clarified behavioral vs. non-behavioral parametric functions, and hardened quality standards with mandatory session protocol.Changes
Fixed
'strict_deduplication'mode mapping: Correctedparse_mode_strso both'strict'and'strict_deduplication'SQL strings map toSTRICT(0x01), matching ClickHouse's behavior where these are aliases. The timestamp-based deduplication mode is now available as'timestamp_dedup'(extension-only mode).Clarified mode semantics in
window_funnel.rs: Updated documentation to distinguish between five ClickHouse-compatible modes (STRICT,STRICT_ORDER,STRICT_INCREASE,STRICT_ONCE,ALLOW_REENTRY) and one extension mode (STRICT_DEDUPLICATION/'timestamp_dedup'). Rewrote mode descriptions to match ClickHouse's actual behavior (e.g.,STRICTprevents "previously-matched condition firing again" rather than "condition i-1 must not fire").Added non-behavioral parametric functions scope clarification: New section in
clickhouse-compatibility.mddocumenting the four non-behavioral parametric functions (histogram,uniqUpTo,sumMapFiltered,sumMapFilteredWithOverflow) with detailed rationale for why they are out of scope. Includes precise definition of "behavioral analytics functions" (sequences of user actions over time, requiring timestamps).Hardened quality standards in CLAUDE.md: Added mandatory requirements section (zero test failures, zero clippy warnings, zero formatting violations, zero doc errors), anti-patterns list (no unverified claims, no guessed semantics), and formal session protocol (read docs, establish baseline, verify claims, update documentation).
Updated test count documentation: Corrected test count from 434 to 435 (one additional test added in Session 16).
Updated CHANGELOG.md: Added entries for
'timestamp_dedup'mode string and mandatory session protocol.Updated FAQ and function documentation: Clarified mode availability (5 ClickHouse + 1 extension) and corrected
strict_deduplicationdescription inwindow-funnel.mdandfaq.md.Added WEB_ANALYTICS_PLAN.md: Comprehensive project plan for a DuckDB-based web analytics platform (
Webfoot) showcasing the behavioral extension. Includes architecture, technology stack (Axum, Parquet, Preact), feature roadmap (MVP → behavioral analytics → production hardening → ecosystem), data model, SQL query examples, and 8-week development plan.Testing
cargo testpasses (435 unit tests + 1 doc-test)cargo clippy --all-targetsproduces zero warningscargo fmt -- --checkpassescargo doc --no-depsbuilds without errors or warningsNotes
Session 16 focused on rigorous verification against official ClickHouse documentation. The
'strict_deduplication'fix corrects a semantic error where the mode was previously mapped to timestamp-based deduplication instead of the ClickHouse-compatible "prevent backward movement" behavior. The WEB_ANALYTICS_PLAN.md is a comprehensive specification for a production-ready analytics platform that demonstrates real-world usage of the behavioral extension, serving as both a reference implementation and a deployment option for users.https://claude.ai/code/session_01MvYKE1YxJC564kEQCkq3HL