How Hook works

Everything you build in the builder is saved as a small description of the question, called the query. It holds the conditions, the output, the sub-hooks, and also your names, notes, collapsed blocks and spacing. It holds no data and no site.

• In the builder it is what you edit. In a Copy link it sits in the address, so the link reopens the exact question.
• Whoever opens a link runs it against their own current site. Your site is never in the link.
• A query from anywhere (a link, the code panel) is treated as untrusted. It is upgraded to the current format, then checked for size and structure, then checked for types, on every run.
• Queries are versioned. When Hook changes, old links are upgraded step by step and keep working, and Hook tells you when it did that.

1. Who and which site. The server works out who you are and which site you are looking at, exactly as every page in the dashboard does. The browser is never asked to name a site.
2. Upgrade and check. An older query is upgraded; the query is checked against the limits and types.
3. Sub-hooks first. Every sub-hook runs once, inside the database, and its result is held ready for the hook above it.
4. Estimate. Hook asks the database how many rows each top-level step would keep. This is a planning question answered from the statistics the database already holds, so no visitor data is read.
5. Plan and cost. Hook decides the order, works out the credits, and compares them with your limit.
6. Run. If the cost is within the limit, the database runs the whole question in one statement.
7. Answer and account. The answer comes back with how it was found: the order, what each sub-hook carried, the cost and the timings.

The top-level conditions are the steps of a question. When their sizes are very different, Hook runs the smallest first and each next step only checks what survived. When they are similar, it runs them together and the database orders them itself. Either way the answer is identical; only the speed differs.

If you set the order by hand and it would be at least 10 times slower, Hook runs the faster order and tells you, unless you switched that safeguard off. An estimate can be wrong when conditions are correlated or when a measure over connected rows is rough, and a wrong estimate costs speed, never correctness.

Connected rows

A connected-row condition looks at rows linked by the identifiers the tracker records (session, visitor, page address). Its conditions apply to the same row together. A count or total is measured over exactly the connected rows that match.

Tunnels

• A sub-hook runs once. Its result never travels to the browser and back, so its size does not change the cost the way manual copying would.
• One value feeds comparisons; a list feeds is any of and is none of. Types must match. Breaking a rule is an error naming both sides, never a silent conversion.
• Sub-hooks can nest, and the depth is capped.

The cost is known before anything runs. Hook asks the database for its own estimate of the work in the exact statement it is about to run, and converts that into credits, with a minimum of 1. If the estimate is over your limit, nothing runs. Because the estimate is for the real statement, the cost you are shown is the cost you pay.

• One site only. The site comes from the server, never from the query. Every table in the statement is pinned to it.
• Read only. Hook runs through a database login that can read, not write.
• Values are never pasted into the statement. Every value you type is passed separately, so text cannot change the meaning of a question.
• A run is stopped after 8 seconds so a heavy question cannot hold the database.
• Errors tell you what to change. Server problems show only a short reference code; the details stay in the server log.

Nothing runs on its own. Every run is started by a person, because every run is metered.

• Custom form answers are not available as fields in conditions yet.
• The referrer is raw text; the classified traffic source is not a field yet.
• Hours and weekdays are UTC, not the visitor's local time.
• Share of page seen uses where the visitor entered, went deepest, and scrolled back to. The session replay chart can show finer detail.
• Very large questions make long links. Saved hooks will remove this.