What lets OPA index the rules of a Rego document, and which body shapes defeat it?

## The problem indexing solves A Rego package typically defines one virtual document many times: dozens of rules all named `deny`, each matching a different object kind and each contributing a message. Evaluating the document means taking the union of every rule that produces a value. Done naively, every rule body runs for every input, and most of them go undefined on their very first expression because the object is the wrong kind. Rule indexing is OPA's answer. Before evaluation, the compiler inspects the bodies of the rules that define one virtual document and builds a lookup structure from the expressions it can interpret. At query time OPA reads the corresponding values out of the input and uses them to select the candidate rules; the rest are never evaluated. ## What the indexer can read The indexer understands a deliberately small set of expression forms. The workhorse is an equality between a **reference whose path is ground** — no variables in it, such as `input.request.kind.kind` or `input.request.object.metadata.namespace` — and a **constant** value written literally in the policy. Pattern matching with `glob.match` against a constant pattern is also indexable. Everything else is opaque to it. A rule whose body contains no expression the indexer can interpret simply has no key: it joins the set of rules that are always evaluated, which is the correct conservative behaviour, because skipping it could change the answer. ## What defeats it, in order of how often it happens - **Hiding the discriminator in a helper.** `is_namespace(input)` reads better than `input.request.kind.kind == "Namespace"`, but the indexer inspects expressions in the rule body, and a function call is opaque. Every rule that adopts the helper loses its key. - **Expressing the discriminator as a negation.** `not exempt_kind(input)` cannot serve as an index key; a negation tells the indexer nothing about what value would match. - **Comparing against a computed value.** `kind := lower(input.request.kind.kind); kind == "namespace"` puts a builtin call between the input and the constant. The comparison is now against a variable whose value the compiler does not know. - **Deriving the fact with a comprehension or `walk`.** Anything that has to run to produce the compared value is by definition not something the compiler can look up ahead of evaluation. - **Non-ground paths.** A reference that iterates, such as `input.spec.containers[_].image`, is not the ground reference the index is built on. ## How to write for it Open each rule of a large same-named set with a plain, literal equality on whatever discriminates it — object kind, apiVersion, operation — as a top-level conjunct of the body, before any helper does anything clever. Keep the constant a literal. Then let the helpers handle the parts that genuinely need logic. It costs nothing in readability, and it is the difference between a document whose rules are selected and one whose rules are all run. ## What indexing is not Indexing chooses **which rule bodies to evaluate**. It does nothing at all for a rule that has been selected and then iterates a large reference document inside its body — that is a data-shape problem, solved by how the document is keyed, not by how the rule opens. Nor is it caching: nothing is remembered between decisions; the index is a compile-time structure over the policy, not over the answers. ## Convincing yourself it is working Do not assert it — measure it. Profile the same query against the same input before and after restructuring: when the index is doing its job, the bodies of the rules whose key does not match the input stop appearing with evaluation counts at all, rather than appearing with a count of one and an immediately undefined first expression. That difference is visible directly in the profile output, which makes it a claim you can put in a review rather than a piece of folklore.