Glossary

The 144 terms Business Intelligence with Agents defines, each in the book's own words, with the section that defines it.

From Edition 2026.11.15, the book's current edition. Where a definition depends on a package, it says the version this edition pins and runs its examples on.

A

ablation also ablations

An ablation measures every layer the same way: it scores a series of configurations that differ by one layer each, on the same questions, under the same comparison rule.

Defined in Measure what each layer adds, chapter 4. In the book since Edition 2026.11.15. Permanent link to ablation

allowlist also allowlists

The allowlist is every table in the agent's database, read by allowed_schema() with each table's columns, and the same mapping is the schema qualify resolves columns against.

Defined in Allow only read-only queries on known tables, chapter 7. In the book since Edition 2026.11.15. Permanent link to allowlist

ambiguous question also ambiguous questions

An ambiguous question, such as "Who are our best customers?", has several reasonable answers, and the agent should say which choices it needs.

Defined in Cover declines and roles, not only answers, chapter 3. In the book since Edition 2026.11.15. Permanent link to ambiguous question

ambiguous SELECT column

an ambiguous SELECT column, where several valid SQLs differ in the columns they select

Defined in Kinds of questions the warehouse can't answer, chapter 8. In the book since Edition 2026.11.15. Permanent link to ambiguous SELECT column

analytics schema

The analytics schema holds the marts built from the raw tables in SQL, such as fct_orders, one row per real order with its amounts in euros.

Defined in Meet the shop and its warehouse, chapter 1. In the book since Edition 2026.11.15. Permanent link to analytics schema

ask_back also ask back, asking back, question back

The ask_back tool ends the run with a question to the person and the options the model offers.

Defined in Ask back when a question is ambiguous, chapter 6. In the book since Edition 2026.11.15. Permanent link to ask_back

audit entry also audit entries, audit log

every question the agent handles gets an audit entry, written by code beside the answer, never by the model

Defined in Log who asked what, and what ran, chapter 9. In the book since Edition 2026.11.15. Permanent link to audit entry

average order value also AOV

Average order value is a derived metric, net_revenue / kept_orders

net_revenue / kept_orders

Defined in Build ratio and derived metrics from simple ones, chapter 5. In the book since Edition 2026.11.15. Permanent link to average order value

B

binding the role at build also role binding, bind the role

Binding the role at build means one server per person, which is what stdio gives you: the host starts a process for its user, and the process lives as long as the host needs it

Defined in Carry the caller's role into every query, chapter 11. In the book since Edition 2026.11.15. Permanent link to binding the role at build

BIRD

BIRD, a text-to-SQL benchmark whose questions come with "external knowledge evidence"

Defined in Add the business glossary, chapter 4. In the book since Edition 2026.11.15. Permanent link to BIRD

business definition

Words such as revenue, order value or active customer have one meaning in a business, chosen by the people who own the number, and that meaning lives in a finance policy, a dashboard's SQL or someone's memory.

Defined in Definitions the schema doesn't hold, chapter 2. In the book since Edition 2026.11.15. Permanent link to business definition

business glossary also glossary

A business glossary lists the business words whose meaning a company's teams chose, and writes each meaning in terms of the warehouse's tables and columns.

Defined in Add the business glossary, chapter 4. In the book since Edition 2026.11.15. Permanent link to business glossary

C

check query also check_sql, check queries

Where you can, a second query written another way, the gold's check_sql, must return the same result as the golden SQL.

Defined in Check the gold before you trust it, chapter 3. In the book since Edition 2026.11.15. Permanent link to check query

client also MCP client, clients

an application, the host, runs a client for each server it connects to

Defined in Serve the semantic layer over MCP, chapter 11. In the book since Edition 2026.11.15. Permanent link to client

Cohen's kappa also kappa, κ

Cohen's kappa estimates chance agreement from each rater's own label shares

kappa, pi = (p_o − chance) / (1 − chance)

Defined in Calibrate the judge against reference labels, chapter 10. In the book since Edition 2026.11.15. Permanent link to Cohen's kappa

column mask also column masks, mask, masking

A column mask decides what a role sees in a column: the value replaced by something that reveals nothing, here the text (masked).

Defined in Mask columns in every path, chapter 9. In the book since Edition 2026.11.15. Permanent link to column mask

column note also column notes

A column note is a sentence about one table or column that says what its name doesn't: which rows the table holds, the unit and sign of an amount, the time zone of a timestamp, the values a column takes, or that a table is deprecated.

Defined in Describe columns where names mislead, chapter 4. In the book since Edition 2026.11.15. Permanent link to column note

comparison rule also results_match()

The comparison rule, results_match() in lib/golden.py, accepts an answer when it has as many rows as the golden result and its columns include every golden column's values.

Defined in Score both on five golden questions, chapter 1. In the book since Edition 2026.11.15. Permanent link to comparison rule

control also controls, access control

A control is something the model can't change.

Defined in A rule in the prompt is not a control, chapter 9. In the book since Edition 2026.11.15. Permanent link to control

correct

An answer is correct when the result matches the golden result, or when it declines a question that should be declined.

Defined in Score both on five golden questions, chapter 1. In the book since Edition 2026.11.15. Permanent link to correct

coverage

Coverage is the share of questions the system doesn't reject

coverage = questions answered with a number / questions asked

Defined in Measure declines, not only accuracy, chapter 8. In the book since Edition 2026.11.15. Permanent link to coverage

custom granularity also custom grain, custom grains, custom granularities

A custom granularity, such as fiscal_year, is a column of the time spine that names the period each day belongs to

True for metricflow 0.214.0, as this edition pins it.

Defined in Put the fiscal calendar in the time spine, chapter 5. In the book since Edition 2026.11.15. Permanent link to custom granularity

D

DABstep also Data Agent Benchmark for Multi-step Reasoning

DABstep asks questions about a payments processor's transactions, scores only the final answer, and keeps most of its tasks hidden for its leaderboard

Defined in Why a public benchmark isn't your test, chapter 3. In the book since Edition 2026.11.15. Permanent link to DABstep

database catalog also DuckDB's catalog

What no setting hides is DuckDB's catalog, such as information_schema and duckdb_settings(), which describes the database itself.

True for duckdb 2.0.0, as this edition pins it.

Defined in Give the agent a database with only what it may read, chapter 7. In the book since Edition 2026.11.15. Permanent link to database catalog

decline also declines, declining

A decline is an answer: it ends the run, it says why, and the person can act on it.

Defined in Decline with a reason, chapter 8. In the book since Edition 2026.11.15. Permanent link to decline

decline kind

A decline's kind, the reason's other part, comes from a fixed list, for the code, so declines can be counted, routed and scored by kind instead of read one at a time.

Defined in Decline with a reason, chapter 8. In the book since Edition 2026.11.15. Permanent link to decline kind

decline precision

Decline precision asks how many of the agent's declines were due

decline precision = correct declines / all declines

Defined in Measure declines, not only accuracy, chapter 8. In the book since Edition 2026.11.15. Permanent link to decline precision

decline reason also decline's reason, reason for declining

A decline's reason, the sentence that tells the person why no number came

Defined in Judge only what can't be compared, chapter 10. In the book since Edition 2026.11.15. Permanent link to decline reason

decline recall

decline recall asks how many of the due declines the agent made

decline recall = correct declines / questions whose right answer is a decline

Defined in Measure declines, not only accuracy, chapter 8. In the book since Edition 2026.11.15. Permanent link to decline recall

declined

A declined answer says it can't answer a question that has an answer.

Defined in Score both on five golden questions, chapter 1. In the book since Edition 2026.11.15. Permanent link to declined

denied column also denied columns

A denied column is left out of the role's database and its allowlist, so the guard refuses it, and the refusal, which lists the columns the model may use, doesn't name it.

Defined in Mask columns in every path, chapter 9. In the book since Edition 2026.11.15. Permanent link to denied column

deny by default

Deny by default means that any table a filtered role's filter doesn't name or list as unfiltered is refused, so a mart added later stays closed to the lead until someone writes its filter.

Defined in Apply row filters in the compiler, chapter 9. In the book since Edition 2026.11.15. Permanent link to deny by default

derived metric also derived metrics

a derived metric combines several metrics with an expression

Defined in Build ratio and derived metrics from simple ones, chapter 5. In the book since Edition 2026.11.15. Permanent link to derived metric

differencing also differencing attack

Differencing involves an intruder using multiple overlapping tables and subtraction

Defined in Subtracting two answers recovers a group, chapter 9. In the book since Edition 2026.11.15. Permanent link to differencing

dimension also dimensions

dimensions (what you can group and filter by)

Defined in Define metrics once in a semantic layer, chapter 5. In the book since Edition 2026.11.15. Permanent link to dimension

E

entity also entities

An entity is a key with a type.

True for metricflow 0.214.0, as this edition pins it.

Defined in Describe each table as a semantic model, chapter 5. In the book since Edition 2026.11.15. Permanent link to entity

error

An error is an answer whose SQL doesn't run.

Defined in Score both on five golden questions, chapter 1. In the book since Edition 2026.11.15. Permanent link to error

error prefix

the SDK's tool wrapper puts "Error executing tool" and the tool's name in front of the message of any ToolError a tool raises

True for mcp 2.3.0, as this edition pins it.

Defined in Return answers with their provenance, chapter 11. In the book since Edition 2026.11.15. Permanent link to error prefix

execution accuracy

execution accuracy, which compares the rows each query returns

Defined in Compare results, not SQL text, chapter 3. In the book since Edition 2026.11.15. Permanent link to execution accuracy

execution match

An execution match means the agent's result equals the golden result under the question's comparison rule.

Defined in Compare results, not SQL text, chapter 3. In the book since Edition 2026.11.15. Permanent link to execution match

EXPLAIN also query plan

For cost, the guard asks DuckDB's EXPLAIN for the plan, which plans the query without running it and gives each step an estimated number of rows

True for duckdb 2.0.0, as this edition pins it.

  • Implemented by: duckdb 2.0.0

Defined in Bound the rows and the cost, chapter 7. In the book since Edition 2026.11.15. Permanent link to EXPLAIN

external knowledge evidence

hints that link a question's words to the database, such as what a term means as a formula over columns

Defined in Add the business glossary, chapter 4. In the book since Edition 2026.11.15. Permanent link to external knowledge evidence

F

failure kind also failure kinds, kinds of plausible wrong number

Five kinds of plausible wrong number: fan-out, a definition the schema doesn't hold, time zones and the fiscal calendar, a tempting table, and an unwritten filter.

Defined in Decisions this chapter made, chapter 2. In the book since Edition 2026.11.15. Permanent link to failure kind

familiarity

familiarity, text that has low perplexity for the judge

Defined in Calibrate the judge against reference labels, chapter 10. In the book since Edition 2026.11.15. Permanent link to familiarity

fan-out

Fan-out is what happens when a query joins a table to another that has several rows for each of its rows, and then sums a column of the first.

Defined in Joins that fan out and inflate a sum, chapter 2. In the book since Edition 2026.11.15. Permanent link to fan-out

fiscal year also fiscal years

The shop's fiscal year starts on February 1, and is named for the year it ends in.

Defined in Meet the shop and its warehouse, chapter 1. In the book since Edition 2026.11.15. Permanent link to fiscal year

forbidden question also forbidden questions

A forbidden question is answerable, but not for the role asking: the shop's finance team may not see customers' emails, and a regional lead may see only their own region.

Defined in Cover declines and roles, not only answers, chapter 3. In the book since Edition 2026.11.15. Permanent link to forbidden question

foreign entity also foreign entities

A foreign entity is a key that points at another table's primary entity, and it repeats.

True for metricflow 0.214.0, as this edition pins it.

Defined in Describe each table as a semantic model, chapter 5. In the book since Edition 2026.11.15. Permanent link to foreign entity

freshness also data freshness

Freshness is how far a source's events have arrived, read from when its rows were loaded.

Defined in Check freshness before answering, chapter 8. In the book since Edition 2026.11.15. Permanent link to freshness

freshness check

The freshness check in lib/declining.py compares each feed's newest load with the end of the period a request filters on, plus the settling window of the metrics that read the feed.

Defined in Check freshness before answering, chapter 8. In the book since Edition 2026.11.15. Permanent link to freshness check

G

golden question also golden questions

A golden question is a question with its checked answer: the golden SQL, written against the owner's definition, the golden result that SQL returns, and the kind of answer expected.

Defined in Run the SQL and check the number, chapter 1. In the book since Edition 2026.11.15. Permanent link to golden question

golden result also golden results

the golden result: the question's answer from SQL written against the finance team's definitions and checked by running it

Defined in Where raw text-to-SQL gets the number wrong, chapter 2. In the book since Edition 2026.11.15. Permanent link to golden result

guarded SQL also guarded SQL path

Guarded SQL is the fallback, not the default, for questions no metric covers, written with chapter 4's four layers of context.

Defined in Decisions this chapter made, chapter 7. In the book since Edition 2026.11.15. Permanent link to guarded SQL

H

held-out split also held-out set, test split

A held-out split is the usual defence: tune on one part, and score the other only when you report a result.

Defined in Hold out a test split, chapter 3. In the book since Edition 2026.11.15. Permanent link to held-out split

host also MCP host, hosts

A host is the application that runs the model and calls the server's tools for it

Defined in Answer questions through a host, chapter 11. In the book since Edition 2026.11.15. Permanent link to host

I

in-memory client also in-memory clients

The Python SDK's Client connects to a server object in the same process when you pass it one instead of a URL

True for mcp 2.3.0, as this edition pins it.

  • A kind of: client
  • Implemented by: mcp 2.3.0

Defined in Test the server in memory, chapter 11. In the book since Edition 2026.11.15. Permanent link to in-memory client

J

judge also judges, model as a judge, LLM judge

a judge, a model call that grades an answer against a rubric and returns a verdict

Defined in Judge only what can't be compared, chapter 10. In the book since Edition 2026.11.15. Permanent link to judge

judge calibration also calibrating a judge, calibrate the judge

Calibrating a judge against reference labels measures how often the judge agrees with a check you trust, and in which direction it errs.

Defined in Calibrate the judge against reference labels, chapter 10. In the book since Edition 2026.11.15. Permanent link to judge calibration

K

kept_orders

kept_orders is the orders metric with the rule on cancelled orders applied as an input filter

Defined in Build ratio and derived metrics from simple ones, chapter 5. In the book since Edition 2026.11.15. Permanent link to kept_orders

L

layered context

Layered context is the most direct fix for what a schema can't say: write the rules down where the model reads them.

Defined in Give the agent layered context, chapter 4. In the book since Edition 2026.11.15. Permanent link to layered context

least privilege

Least privilege means that the agent's SQL runs on a connection that can reach what the agent may query and nothing else.

Defined in Give the agent a database with only what it may read, chapter 7. In the book since Edition 2026.11.15. Permanent link to least privilege

legacy table also legacy tables, tempting table

Most warehouses keep tables that nobody should query any more and nobody can drop: an older mart that old dashboards read, a copy from a migration, a table built for one analysis.

Defined in The table with the tempting name, chapter 2. In the book since Edition 2026.11.15. Permanent link to legacy table

lexical retrieval

Lexical retrieval matches words

Defined in What goes wrong in production, chapter 4. In the book since Edition 2026.11.15. Permanent link to lexical retrieval

line_net_revenue also line-level net revenue, line-level revenue

line_net_revenue is net revenue counted on the lines themselves, in the order_lines semantic model, with net revenue's rule on cancelled orders.

Defined in Join through entities so sums can't fan out, chapter 5. In the book since Edition 2026.11.15. Permanent link to line_net_revenue

local business day also local business days

The shop counts each order on its region's local business day, stored as order_date_local in the orders mart, beside the UTC timestamp placed_at.

Defined in Time zones and the fiscal calendar, chapter 2. In the book since Edition 2026.11.15. Permanent link to local business day

long tail

The questions no metric covers are the long tail: how much revenue came from orders that included a tent, or what share of sessions converted.

Defined in Let the agent write SQL inside guards, chapter 7. In the book since Edition 2026.11.15. Permanent link to long tail

M

MCP tool also MCP tools

An MCP tool is a name, a description the model reads, a JSON Schema for its arguments and, optionally, a schema for its result.

Defined in Turn metrics into tools, chapter 11. In the book since Edition 2026.11.15. Permanent link to MCP tool

measure also measures

the measure: an aggregation declared on the semantic model, which a metric then names

True for metricflow 0.214.0, as this edition pins it.

Defined in Describe each table as a semantic model, chapter 5. In the book since Edition 2026.11.15. Permanent link to measure

metric also metrics, defined metric

A metric is a business measure written down once, by the people who own it: a name, a description a person can check, one aggregate over one mart, the rule for which rows count, and the dimensions it may be grouped and filtered by.

Defined in Answer from one defined metric, chapter 1. In the book since Edition 2026.11.15. Permanent link to metric

metric filter

A metric's filter is a Jinja template

True for metricflow 0.214.0, as this edition pins it.

Defined in What goes wrong in production, chapter 5. In the book since Edition 2026.11.15. Permanent link to metric filter

metric request also metric requests

A metric request names the metric, the dimensions to group by and one value per filtered dimension, and compile_request() turns it into SQL.

Defined in Answer from one defined metric, chapter 1. In the book since Edition 2026.11.15. Permanent link to metric request

metric tool also metric tools

A metric tool exposes what a semantic layer holds in the shape a person asks for it: metric names with their descriptions, the dimensions each can be grouped and filtered by, and the time grains.

Defined in Give the agent metrics, not tables, chapter 6. In the book since Edition 2026.11.15. Permanent link to metric tool

metrics-first also governed metrics first

Routing a question to governed metrics first takes writing the query away from the model: its job shrinks to choosing which metric, grouped by what, filtered how, and the layer, which people own and test, writes the SQL.

Defined in Route questions to governed metrics first, chapter 6. In the book since Edition 2026.11.15. Permanent link to metrics-first

minimum group size also minimum group sizes

a minimum group size, a number of people below which a group's values are held back

Defined in Suppress groups small enough to identify someone, chapter 9. In the book since Edition 2026.11.15. Permanent link to minimum group size

Model Context Protocol also MCP

MCP is an open protocol in which an application, the host, runs a client for each server it connects to, and a server offers tools that the host's model can call.

  • Implemented by: mcp 2.3.0

Defined in Serve the semantic layer over MCP, chapter 11. In the book since Edition 2026.11.15. Permanent link to Model Context Protocol

N

net revenue

The golden SQL for gq-002 follows the shop's definition of net revenue, which the finance team owns: revenue in euros after discounts and before tax, from real orders that weren't cancelled, on the order's local business day.

Defined in Run the SQL and check the number, chapter 1. In the book since Edition 2026.11.15. Permanent link to net revenue

NL2SQL-BUGs

One detailed taxonomy, NL2SQL-BUGs, sorts semantic errors in text-to-SQL into 9 categories and 31 subcategories, from 2,018 expert-annotated cases

Defined in Definitions the schema doesn't hold, chapter 2. In the book since Edition 2026.11.15. Permanent link to NL2SQL-BUGs

nonexistent filter value also nonexistent filter values

a nonexistent filter value, in PRACTIQ's terms, is a filter value no row holds, such as a region called Europe.

Defined in Kinds of questions the warehouse can't answer, chapter 8. In the book since Edition 2026.11.15. Permanent link to nonexistent filter value

nonexistent SELECT column

a nonexistent SELECT column, where "The column that contains the results asked in the question do not exist in the database"

Defined in Kinds of questions the warehouse can't answer, chapter 8. In the book since Edition 2026.11.15. Permanent link to nonexistent SELECT column

O

order_refunds

order_refunds, a metric counted on the order's local day

Defined in Build ratio and derived metrics from simple ones, chapter 5. In the book since Edition 2026.11.15. Permanent link to order_refunds

output schema also outputSchema

a tool can declare an outputSchema and return structuredContent that conforms to it

Defined in Return answers with their provenance, chapter 11. In the book since Edition 2026.11.15. Permanent link to output schema

P

paired difference also paired differences, mean paired difference

Comparison in lib/regressions.py takes, for each question, the share of runs correct under the base and under the candidate, and their difference.

Defined in Gate a change in CI, chapter 10. In the book since Edition 2026.11.15. Permanent link to paired difference

parsing

Parsing turns the text into a tree, with one node for each statement, table, column and function, so each later check asks about nodes, not characters.

Defined in Parse the SQL before it runs, chapter 7. In the book since Edition 2026.11.15. Permanent link to parsing

penalty score

In the penalty score, each question scores one point for a right answer or a right decline, nothing for declining an answerable question, and minus c for a wrong number, including an answer to a question it should have declined; the score is the mean over the questions

penalty score = (right answers + correct declines − c × wrong numbers) / questions asked

Defined in Measure declines, not only accuracy, chapter 8. In the book since Edition 2026.11.15. Permanent link to penalty score

PolicyLayer

PolicyLayer is the semantic layer as one role sees it, and passes every query it compiles through apply().

Defined in Apply row filters in the compiler, chapter 9. In the book since Edition 2026.11.15. Permanent link to PolicyLayer

PolicyToolbox

PolicyToolbox, chapter 6's metric tools over PolicyLayer, which end the run with a decline whose reason starts with "forbidden" when the policy refuses a request

Defined in Measure access on the golden questions, chapter 9. In the book since Edition 2026.11.15. Permanent link to PolicyToolbox

primary entity also primary entities

A primary entity is unique in its table, so other tables can join to it many rows to one.

True for metricflow 0.214.0, as this edition pins it.

Defined in Describe each table as a semantic model, chapter 5. In the book since Edition 2026.11.15. Permanent link to primary entity

principal also principals

the principal, meaning whoever your sign-in system says is asking

Defined in Log who asked what, and what ran, chapter 9. In the book since Edition 2026.11.15. Permanent link to principal

provenance

An answer's provenance is the metric or SQL behind it, the filters, the role it was computed for and how fresh the data was.

Defined in Show the provenance with every answer, chapter 8. In the book since Edition 2026.11.15. Permanent link to provenance

public benchmark also public benchmarks

A public benchmark for text-to-SQL or data agents gives you questions, a database and a gold answer for each question, and a score that others have reported on the same set.

Defined in Why a public benchmark isn't your test, chapter 3. In the book since Edition 2026.11.15. Permanent link to public benchmark

Q

qualify also qualification, qualifies

check() qualifies every column against the columns of the tables the query may read, with sqlglot's qualify, which raises an error for a column it can't place.

True for sqlglot 30.31.0, as this edition pins it.

  • Implemented by: sqlglot 30.31.0

Defined in Parse the SQL before it runs, chapter 7. In the book since Edition 2026.11.15. Permanent link to qualify

question kind

A golden question's kind says what a right answer looks like: answer when the warehouse can answer it, decline when it can't, and forbidden when the role may not see the answer.

Defined in Write questions from the work people do, chapter 3. In the book since Edition 2026.11.15. Permanent link to question kind

R

ratio metric also ratio metrics

A ratio metric divides one metric by another

Defined in Build ratio and derived metrics from simple ones, chapter 5. In the book since Edition 2026.11.15. Permanent link to ratio metric

raw schema

The raw schema holds what the source systems loaded: orders, order lines, refunds, customers, products, sessions, marketing spend and exchange rates.

Defined in Meet the shop and its warehouse, chapter 1. In the book since Edition 2026.11.15. Permanent link to raw schema

recording also recordings

A recording is a saved set of model replies with a manifest, made once by a script in the repository's recordings/ folder and replayed by the examples.

Defined in Ask a question, get SQL from a model, chapter 1. In the book since Edition 2026.11.15. Permanent link to recording

reference label also reference labels

Reference labels computed by results_match() are nobody's opinion: anyone can recompute them from questions.toml and the recordings, and when one looks wrong, the fix is to the golden question, where it's open to correction like the rest of the book.

Defined in Calibrate the judge against reference labels, chapter 10. In the book since Edition 2026.11.15. Permanent link to reference label

refund rate

The shop's finance team defines the refund rate in golden question gq-028: refunded euros over gross revenue of the same orders, those placed in the period that weren't cancelled.

Defined in Build ratio and derived metrics from simple ones, chapter 5. In the book since Edition 2026.11.15. Permanent link to refund rate

regression gate also gate, CI gate

gate() applies two rules of our choosing: it fails on a stable break, a question the base got right in at least four runs of five and the candidate in at most one, and when the whole interval of the mean difference lies below zero.

Defined in Gate a change in CI, chapter 10. In the book since Edition 2026.11.15. Permanent link to regression gate

repair

Repair means giving the model the guard's refusal or the warehouse's error, once, and running what it writes next.

Defined in Repair once from the error, chapter 7. In the book since Edition 2026.11.15. Permanent link to repair

request validation also validating a request, validation

Validating a request means checking it against the layer's definitions and the warehouse's values before it compiles, and sending every problem back to the model with what would be allowed instead.

Defined in Validate the request against the layer, chapter 6. In the book since Edition 2026.11.15. Permanent link to request validation

role also roles

A role is who is asking, role in the code

Defined in Keep the agent inside who may see what, chapter 9. In the book since Edition 2026.11.15. Permanent link to role

role's view also role view, role's views

A role's view of a table returns the rows that role may see, with a masked column holding a constant and a denied column left out.

Defined in Give each role a database of views, chapter 7. In the book since Edition 2026.11.15. Permanent link to role's view

row access policy also row access policies

Snowflake's row access policies "determine which rows to return in the query result"

Defined in Apply row filters in the compiler, chapter 9. In the book since Edition 2026.11.15. Permanent link to row access policy

row filter also row filters

A row filter takes the decision away from the model: a condition on a table, such as region = 'EMEA', that every query reading the table gets, whatever else the query says.

Defined in Apply row filters in the compiler, chapter 9. In the book since Edition 2026.11.15. Permanent link to row filter

S

schema also schemas

A schema tells a model which tables exist, what their columns are called and what type each column holds.

Defined in What the schema says, and what it doesn't, chapter 4. In the book since Edition 2026.11.15. Permanent link to schema

schema layer

The schema layer is the whole warehouse: all 16 tables, about 912 tokens.

Defined in What the schema says, and what it doesn't, chapter 4. In the book since Edition 2026.11.15. Permanent link to schema layer

schema-only text-to-SQL also schema-only SQL

Schema-only text-to-SQL means the model is given the name and type of every column and the person's question, and nothing else, and writes the SQL.

Defined in Ask a question, get SQL from a model, chapter 1. In the book since Edition 2026.11.15. Permanent link to schema-only text-to-SQL

scorecard also scorecards

a scorecard reports wrong numbers, declines and failures apart, the decline measures from chapter 8, and the cost in model calls and prompt tokens, beside accuracy

Defined in Score a run on more than accuracy, chapter 10. In the book since Edition 2026.11.15. Permanent link to scorecard

Scott's pi also pi, π

Scott's pi estimates chance agreement from the two raters' shares pooled

kappa, pi = (p_o − chance) / (1 − chance)

Defined in Calibrate the judge against reference labels, chapter 10. In the book since Edition 2026.11.15. Permanent link to Scott's pi

secondary suppression also complementary suppression

Secondary suppression, which the handbook also calls complementary suppression (section 4.2.2), plans the breakdowns in advance and suppresses further cells across them.

Defined in Subtracting two answers recovers a group, chapter 9. In the book since Edition 2026.11.15. Permanent link to secondary suppression

secure view also secure views

Snowflake's secure views exist to limit access to sensitive data

Defined in Give each role a database of views, chapter 7. In the book since Edition 2026.11.15. Permanent link to secure view

selective risk

selective risk is the error rate on the questions the system answers

selective risk = wrong numbers / questions answered with a number

Defined in Measure declines, not only accuracy, chapter 8. In the book since Edition 2026.11.15. Permanent link to selective risk

self-preference also self-enhancement bias

Self-preference, a judge that "scores its own outputs higher than others' while human annotators consider them of equal quality" (Panickssery et al.), is a known bias

Defined in Calibrate the judge against reference labels, chapter 10. In the book since Edition 2026.11.15. Permanent link to self-preference

semantic layer also semantic layers

A semantic layer is where the choices behind joins, grains and ratios are written down once.

True for metricflow 0.214.0, as this edition pins it.

Defined in Define metrics once in a semantic layer, chapter 5. In the book since Edition 2026.11.15. Permanent link to semantic layer

semantic model also semantic models

A semantic model is one table described for the layer: which table it reads, the entities it holds, the dimensions it offers and the time dimension its numbers are counted on.

True for metricflow 0.214.0, as this edition pins it.

Defined in Describe each table as a semantic model, chapter 5. In the book since Edition 2026.11.15. Permanent link to semantic model

semantic server

the shop's semantic layer becomes one MCP server, which this chapter calls the semantic server

Defined in Serve the semantic layer over MCP, chapter 11. In the book since Edition 2026.11.15. Permanent link to semantic server

server also MCP server, servers

a server offers tools that the host's model can call

Defined in Serve the semantic layer over MCP, chapter 11. In the book since Edition 2026.11.15. Permanent link to server

ServerToolbox

ServerToolbox has the call() method the loop expects, and makes each call through an MCP client.

Defined in Answer questions through a host, chapter 11. In the book since Edition 2026.11.15. Permanent link to ServerToolbox

settling window also settling windows

A metric's settling window, as we call it, is the time until every event it counts for a period has come.

Defined in Check freshness before answering, chapter 8. In the book since Edition 2026.11.15. Permanent link to settling window

simple metric also simple metrics

Simple metrics, like the line-level revenue, aggregate one column of one table.

True for metricflow 0.214.0, as this edition pins it.

Defined in Build ratio and derived metrics from simple ones, chapter 5. In the book since Edition 2026.11.15. Permanent link to simple metric

small-group suppression also suppression, suppressed group

PolicyLayer then replaces each value of a group behind fewer than 10 customers with (under N), where N is the role's minimum group size.

Defined in Suppress groups small enough to identify someone, chapter 9. In the book since Edition 2026.11.15. Permanent link to small-group suppression

Spider 2.0

Spider 2.0, a benchmark of enterprise text-to-SQL tasks

Defined in The table with the tempting name, chapter 2. In the book since Edition 2026.11.15. Permanent link to Spider 2.0

stable break also stable breaks

a stable break, a question the base got right in at least four runs of five and the candidate in at most one

Defined in Gate a change in CI, chapter 10. In the book since Edition 2026.11.15. Permanent link to stable break

step limit

A run that uses all four model calls without an answer is a failure, and grade() scores it as step limit, apart from the declines the model chose.

Defined in Measure metrics-first on the golden questions, chapter 6. In the book since Edition 2026.11.15. Permanent link to step limit

structured content also structuredContent

Structured content is what lets a host's code, rather than its model, read an answer's role and filters.

Defined in Return answers with their provenance, chapter 11. In the book since Edition 2026.11.15. Permanent link to structured content

structured reply also structured replies

A structured reply is one the code can parse into a typed object and check field by field.

Defined in Ask for a request, not SQL, chapter 6. In the book since Edition 2026.11.15. Permanent link to structured reply

T

t interval

a t interval, the standard error times Student's t for one fewer degrees of freedom than questions

Defined in Gate a change in CI, chapter 10. In the book since Edition 2026.11.15. Permanent link to t interval

time spine

the time spine, a table with one row per day

True for metricflow 0.214.0, as this edition pins it.

Defined in Describe each table as a semantic model, chapter 5. In the book since Edition 2026.11.15. Permanent link to time spine

token audience also intended audience

servers must check that each access token was issued for them, as its intended audience

Defined in Carry the caller's role into every query, chapter 11. In the book since Edition 2026.11.15. Permanent link to token audience

token budget

A token budget is the most context the agent may send with one question.

Defined in Fit the context to a budget, chapter 4. In the book since Edition 2026.11.15. Permanent link to token budget

token estimate

Token counts in lib/context.py are estimates: estimate_tokens() divides the number of characters by 3.5, because the examples don't load the model's tokenizer.

Defined in Fit the context to a budget, chapter 4. In the book since Edition 2026.11.15. Permanent link to token estimate

TokenVerifier also AccessToken

the server is given a TokenVerifier whose verify_token() returns an AccessToken with the client's ID, its scopes and the token's claims

True for mcp 2.3.0, as this edition pins it.

  • Implemented by: mcp 2.3.0

Defined in Carry the caller's role into every query, chapter 11. In the book since Edition 2026.11.15. Permanent link to TokenVerifier

tolerance also absolute slack

Numbers must agree with the gold within 0.05% relative by default, plus an absolute slack of half a unit in the last place the gold rounds to.

Defined in Order, rounding and column names, chapter 3. In the book since Edition 2026.11.15. Permanent link to tolerance

tool also tools

A tool is a function the model may ask the code to run, by replying with a JSON object that names it and gives its arguments.

Defined in Answer from one defined metric, chapter 1. In the book since Edition 2026.11.15. Permanent link to tool

tool execution error also tool error, tool errors, ToolError

The MCP specification reports a tool execution error as a result with isError set, with "actionable feedback that language models can use to self-correct"

Defined in Return answers with their provenance, chapter 11. In the book since Edition 2026.11.15. Permanent link to tool execution error

ToolReply

Every tool of the semantic server returns a ToolReply, a pydantic model with two fields: text, the text the in-process tool shows the model, and answer, the answer with its rows and provenance, or nothing when the result doesn't end the run.

Defined in Return answers with their provenance, chapter 11. In the book since Edition 2026.11.15. Permanent link to ToolReply

trace also traces

The trace is every step of one run, kept by run_agent(): each model reply, and each tool result sent back.

Defined in Read the trace of one run, chapter 1. In the book since Edition 2026.11.15. Permanent link to trace

U

unanswerable question also unanswerable questions

An unanswerable question, such as the cost of shipping, asks for data the warehouse doesn't hold, and the agent should say so.

Defined in Cover declines and roles, not only answers, chapter 3. In the book since Edition 2026.11.15. Permanent link to unanswerable question

unwritten filter also unwritten filters

Some rules about which rows count are so familiar to the people who own a number that nobody writes them down: cancelled orders don't count as revenue, test accounts aren't customers, a refund belongs to the month of its order.

Defined in Filters nobody wrote down, chapter 2. In the book since Edition 2026.11.15. Permanent link to unwritten filter

V

verified query also verified queries

A verified query shows the shop's rules applied: a question someone asked, with SQL a person checked against the shop's definitions.

Defined in Retrieve verified queries as examples, chapter 4. In the book since Edition 2026.11.15. Permanent link to verified query

verified query repository

Snowflake's Cortex Analyst keeps a verified query repository of "questions and corresponding SQL queries to answer them"

Defined in Retrieve verified queries as examples, chapter 4. In the book since Edition 2026.11.15. Permanent link to verified query repository

W

Wilson interval also Wilson's interval, Wilson score interval

Wilson's interval inverts the test of a proportion: it holds every true accuracy that the observed one wouldn't reject at the chosen level, so it never runs below 0 or above 1.

centre = (p + z² / 2n) / (1 + z² / n) half = z × √( p(1 − p) / n + z² / 4n² ) / (1 + z² / n) interval = centre − half to centre + half

Defined in Score a run on more than accuracy, chapter 10. In the book since Edition 2026.11.15. Permanent link to Wilson interval

worker also worker process

The guard plans and runs the agent's query in a worker, a separate process started by Worker in lib/sql_guard.py that opens the agent's database file read-only with the guard's settings, and kills it when the 5-second deadline passes.

Defined in Enforce the deadline by killing a process, chapter 7. In the book since Edition 2026.11.15. Permanent link to worker

wrong answer also wrong answers

A wrong answer returns a different result, or returns any result for a question that should be declined.

Defined in Score both on five golden questions, chapter 1. In the book since Edition 2026.11.15. Permanent link to wrong answer