Every refusal you have met in this book is a consequence, not a policy. The laws on this page sit under the whole grammar, and each one exists to refuse a specific temptation. Each temptation is something another tool does, that costs its users more than it gives them. This chapter collects the laws in one place, with the temptation beside each, because the vocabulary above them will grow and these will not.
by groups, wherever it appears. as names, wherever it appears. where asks, wherever it appears. The temptation is the convenience argument, a word that means roughly similar things in different places. The cost is that a reader can never again be sure, and checks the manual for the rest of their life. You met this law working in the chapter on the small words. It is the reason a verb you have never seen is mostly made of words you have.
No ascending beside the default, no drop beside keep, no distinct beside pick and drop_duplicates, no second spelling of anything. Synonyms read as generosity and cost every reader a doubt: if both exist, they must differ, so what is the difference? Where you catch this grammar saying one thing two ways, that is a bug, and the afterword says where to report it.
A condition about a column’s name writes name; about its kind writes kind; the column under work in a sweep writes value. And where the grammar has to decide something you did not say, it prints the decision back. The sentence below is written in the text form, so the call is the same string in both tabs:
run('marks then widen name [question], value [mark]')assumption: `by` was not given, so the rows that go together are the ones agreeing on every other column: student. Say it outright if that is not what you meant: `by [student]`
|
1 | marks then widen name [question], value [mark]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^| student | q1 | q2 |
|---|---|---|
| ann | 1 | 2 |
| bob | 4 | 5 |
run('marks then widen name [question], value [mark]')assumption: `by` was not given, so the rows that go together are the ones agreeing on every other column: student. Say it outright if that is not what you meant: `by [student]`
|
1 | marks then widen name [question], value [mark]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
student q1 q2
0 ann 1 2
1 bob 4 5The line above the table is the law at work: the grouping was assumed, and the assumption was said aloud rather than exercised in private. Nothing in this grammar decides quietly.
No value in a step can read a column made beside it, and no name can be made twice in one step. The temptation is the one-liner; the cost is a hidden pipeline inside the line, where written order silently becomes execution order. Adding a column stages the first refusal and names the second, which only the text form can spell.
A pipeline is a plan. Building one costs nothing, printing it runs it, and collect hands over the table. The temptation this refuses is eager execution, where every intermediate step materializes whether or not anyone wanted it; the chapter that opens this part shows what the plan buys.
One checker reads the whole pipeline before anything runs. So every message in every language is written by the same voice, names the step you wrote, and carries its repair. The temptation is delegating errors to whatever engine hits the problem first, which is how a beginner meets a Java stack trace with their column name somewhere inside it. The previous chapter is this law’s whole demonstration.
drop_duplicates returns a settled order. Windows that walk rows demand a sort first. A grouped take without an order is refused. The temptation is “whatever order the engine liked today”, which is invisible until the day two runs of one pipeline disagree and a test you trusted goes quiet. If an answer could vary, the grammar either settles it or asks you to.
show_as renders any pipeline as dplyr, pandas, polars, PySpark, two dialects of SQL, or the grammar itself. The printed code is executed by this project’s own checks, not merely printed. The temptation being refused is on the other side of the fence this time: a tool that holds your work hostage to its own continued existence. The whole argument for adopting a small grammar stands on this exit being real, and it has its own chapter.
god has no table type, no session state, and no import format. A pandas frame goes in and a pandas frame comes out; an R data frame likewise; a Spark frame stays on its cluster. The temptation is the platform move, where the price of the grammar is migrating your data into it. There is nothing to migrate into, which is also why walking away from god costs one show_as per pipeline.
The grammar guarantees that a sentence means one thing. It does not guarantee the sentence was worth writing, and it never refuses one for that:
run('
sales
then add [loud] as upper(lower(upper([product])))
then pick [product, loud]
then take 2
')| product | loud |
|---|---|
| Widget | WIDGET |
| Gadget | GADGET |
sales |>
add(loud = upper(lower(upper(product)))) |>
pick(product, loud) |>
take(2)| product | loud |
|---|---|
| Widget | WIDGET |
| Gadget | GADGET |
(sales
>> add(loud = upper(lower(upper(col.product))))
>> pick(col.product, col.loud)
>> take(2))| product | loud |
|---|---|
| Widget | WIDGET |
| Gadget | GADGET |
Folding a value’s case three times is pointless and perfectly well formed, and the engine answered it, because pointless is your judgment to make and not its. A combination nobody wants today is one somebody means tomorrow, and a grammar that vetoed the useless would be imposing taste and calling it law. The temptation this law refuses points the other way from all the others: not a feature that would cost every reader, but a refusal that would. So every no in this grammar stands on one of the laws on this page and names what to write instead, never on “nobody would want that”. And where each word can stand is one table, asked from the engine, whose every cell the engine’s own tests hold.
None of these laws is about data. They are about what a person can retain, which is the promise this book opened with. A grammar with no exceptions is the only kind that survives a year of not being used. The laws are how the promise is enforced against the vocabulary’s own growth, and they bind the author before they bind you. A proposed word that would break one does not get in, however useful its best day looks.