[kriszyp]

⊙ Problem

The SQL reference describes LIKE only as "Searches for a pattern". harper#3936 makes ESCAPE work and stops matching from backtracking in v5.4. No page says what a pattern means. Also undocumented: the new engine matches case-sensitively and the legacy engine does not. Under the default sql.engine: auto, the same LIKE can match different rows depending on indexes.

🤔 Is the requirement right?

Yes. The brief asks for the v5.4 matching rules. The case split is the part most likely to change which rows an UPDATE or DELETE touches, so it gets the most space.

💡 Solution

• A LIKE Pattern Matching section: wildcards (% and _ matching line breaks on both engines), literal characters, ESCAPE and its 400 errors, case sensitivity per engine, legacy-only [...] classes, and matching cost and pattern limits. Review the case section most closely: it says which statements auto runs on which engine.
• LIKE joins the behavior changes from the legacy engine: adding or dropping an index can change which rows it matches.
• The fallback contract defines sql.engine and sql.allowFullScan.
• A 5.4 release note.

🤔 Define sql.engine and sql.allowFullScan on the SQL page?

Yes, in two short paragraphs, because LIKE depends on them and no page defines them. A full sql entry in the configuration options page also needs maxSortRows and maxHashRows, which I did not check. It is tracked in #785.

⚖️ Alternatives

• Rewrite only the operators-table row: a table cell can't hold the per-engine case rules or the cost and full-scan rules.
• Make both engines match case the same way, in harper: harper#3936 keeps the split on purpose. These docs describe what ships.

🔧 Changes

• reference/operations-api/sql.md: the new LIKE section linked from the operators table, a LIKE bullet in the engine behavior changes, sql.engine / sql.allowFullScan in the fallback contract, and edits to the 5.2 callout, the Query Performance intro, the fallback list and the suffix LIKE bullet. Updated for harper#3936 at 48d0e92: _ matches line breaks on both engines, the 10,000-character segment limit and its 400 error JSON, the legacy >64-_ reserved noncharacter / Private Use Area pair 400 error JSON, escaped [ on the legacy engine, and literal-pattern checking before fallback under auto.
• release-notes/v5-lincoln/5.4.md: a ## SQL entry with the upgrade impact, including _ matching line breaks on both engines and both new 400 rejections.

✅ Verification

• Checked against harper#3936 (48d0e92) DESIGN.md, sqlEngine/expressions/like.ts, sqlTranslator/alasqlLike.ts, and integration/unit tests, plus a scratch Harper build under auto, new, new with allowFullScan, and legacy.
• Checked the "before v5.4.0" claims against harper@5.4.0-alpha.2. On the new engine, ESCAPE was ignored, * acted as a quantifier, and % and _ skipped line breaks. On the legacy engine, _ skipped line breaks and 'a\d' matched a5.
• npm run build passes, including links and anchors. So do format:check, lint, typecheck and test:examples.

Selected results (PR head, sql.engine: auto unless noted)

Query	Result
ip LIKE 't0!%' ESCAPE '!'	t0% only
ip LIKE 't0%' (indexed, new engine)	t0%, t0!z, t0a; not T0b
note LIKE 't0%' (unindexed, falls back)	also T0b
note LIKE 't0%' ORDER BY id	new engine, not T0b
ip LIKE '%T0B'	falls back, matches T0b
DELETE ... WHERE ip LIKE 't0%'	deletes 3, keeps T0b
note LIKE 'a_b'	matches a\nb and a\rb on both engines
note LIKE '[z-a]%'	400 (legacy)
ESCAPE '!!', ESCAPE '', ESCAPE 1, trailing escape	400 on all engines
Segment > 10,000 characters between % wildcards	400 on all engines
Legacy > 64 _ pattern naming every noncharacter and PUA pair	400 (legacy)
note LIKE '%_%_%_%_%_%_%_%_%_%_%_%_%_%_Z' on a 100 KB value	about 40 ms per request
sql.engine: new, note LIKE 't0%'	400, no usable index condition

🤔 Merge after harper#3936?

Yes. harper#3936 merged to main (ef427ad), and the v5.4.0-beta.1 tag includes it, but that release is not published yet, so the v5.4.0 badges match the next release.

Refs HarperFast/harper#3936

_{🤖 Generated by Gemini (gemini-4-argon-high); posted via @kriszyp.}

Related PRs: #783 overlaps, #788 overlaps
Complexity: medium

Deferred findings

• 58823b88daf1f164 minor documentation — reference/operations-api/sql.md — No sql.engine/allowFullScan/HARPER_SQL_ENGINE entries in configuration docs that the fallback contract links to — NOT FILED
• 6960e19497514b0b minor documentation — reference/operations-api/sql.md — 'no rows are changed' unverified for expression patterns checked per row in UPDATE/DELETE — NOT FILED
• 1fb37cf7647bc110 minor documentation — reference/configuration/options.md — No sql section in configuration options for sql.engine / allowFullScan / HARPER_SQL_ENGINE — filed Document the sql configuration block (engine, allowFullScan, maxSortRows, maxHashRows) in configuration options #785
• d2d3f81fc83e88c1 minor documentation — release-notes/v5-lincoln/5.4.md — harper#3936 release status unverified; SQL entry lacks 'not released yet' line unlike sibling sections — NOT FILED
• 426309ddbbac72bd nit documentation — reference/operations-api/sql.md — Open PR Assemble the v5 reference and open release notes from harper and harper-pro #788 also edits sql.md; the merge order can restore 'results don't change' — NOT FILED

Origin — the dispatch brief this PR was written from

Document SQL LIKE wildcards, ESCAPE, and case sensitivity (harper#3936)

Document SQL LIKE semantics in the operations-API SQL reference (reference/operations-api/sql.md, which today lists LIKE only as "Searches for a pattern"), following HarperFast/harper PR HarperFast/harper#3936 (milestone v5.4).

What to document, as user-facing behavior:

• Wildcards: % matches any run of characters, including line breaks; _ matches exactly one character other than a line break (\n, \r, U+2028, U+2029).
• LIKE pattern ESCAPE 'c': the escape character makes the next character literal (for example ip LIKE 't0!%' ESCAPE '!' matches exactly t0%). The escape must be exactly one character. A pattern ending in the escape character, an empty or multi-character ESCAPE, and a non-string ESCAPE are rejected with a 400. ESCAPE works in SELECT, UPDATE and DELETE.
• Case sensitivity: with sql.engine: new (and statements auto serves with the new engine) LIKE is case-sensitive; the legacy engine (sql.engine: legacy, and auto fallbacks) is case-insensitive. Say this plainly; a user running auto can see either.
• Legacy-only extension: [abc], [a-z] and [^abc] character classes; a reversed range such as [z-a] is a 400. Characters such as *, \, ^, $ are literals in patterns on both engines.
• Matching cost is linear in the value length for a given pattern (no pathological patterns), so a long pattern on a large table costs time proportional to data scanned; a LIKE with no other indexed condition may require sql.allowFullScan or fall back to the legacy engine under auto (link the existing sql.engine docs if present).

Version note: these are v5.4 behaviors; earlier versions ignored ESCAPE in the new engine and treated * as a wildcard-like regex quantifier there.

_{Dispatch: task docs-harper-3936 · queued by task:harper-sql-like-linear-matcher-escape · ran by claude/opus/xhigh · worker kzyp-xps-1}

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex; adjudicated=domain; declined=cursor-grok,muse; rounds=11; full=2 @ b85698e}

_{Review-Attention: skim ~2m (decisions: engine-dependent-like-case-documented, legacy-64-underscore-rejection-documented, historical-exception-granularity) @ b85698e}

[gemini-code-assist]

Code Review

This pull request updates the SQL documentation and release notes to detail the new SQL engine's behavior, specifically regarding case sensitivity, the new ESCAPE clause in LIKE pattern matching, and performance improvements that prevent backtracking. The review feedback suggests minor documentation improvements, such as avoiding the VersionBadge component mid-sentence inside tables, restructuring a section to place a list of rejected patterns immediately after its introductory sentence, and separating performance limitations from recommendations into distinct sentences for better readability.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-786

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-786

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-786

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-786

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-786

This preview will update automatically when you push new commits.

[kriszyp]

Moved to harper#4037: the v5 reference and 5.4 release notes now live in harper's docs/ (documentation#788).

— Claude Opus 5.5

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.