Grid Language Documentation

The complete language reference for Grid — the spreadsheet engine for products that need real-time computation with external data.

This documentation is for two audiences:

• People writing models by hand or reviewing them.
• AI agents generating Grid code from natural-language intent.

Both audiences share the same surface. The grammar accepts the same forms, the type system enforces the same rules, and the runtime returns the same values regardless of who wrote the code. The split is in how the docs are written, not what they cover.

Reading Order

If you've never written Grid before, read in order. If you're returning, jump to the section you need.

Conceptual Map

                  ┌─────────────────────────────┐
                  │  Source text (.grid files)  │
                  └──────────────┬──────────────┘
                                 │ parse
                                 ▼
                  ┌─────────────────────────────┐
                  │  Program AST                │
                  │  (statements + directives)  │
                  └──────────────┬──────────────┘
                                 │ build
                                 ▼
                  ┌─────────────────────────────┐
                  │  Model                      │
                  │  cells • deps • exec class  │
                  └──────┬───────────┬──────────┘
                         │           │
                  generate Lua    evaluate (TS)
                         │           │
                         ▼           ▼
                  ┌──────────┐ ┌──────────────┐
                  │  Redis   │ │  In-process  │
                  │  Lua     │ │  TS runtime  │
                  └──────────┘ └──────────────┘

A Grid file (.grid) is parsed to an AST, built into a model (a graph of typed cells), and then either compiled to Redis Lua or evaluated in the in-process TypeScript runtime. Both runtimes return identical values for the portable subset of the language.

Mental Model In One Page

Read this if you want the absolute minimum needed to understand any model.

1. A model is a set of named cells. Each cell name (A1, Revenue, Sheet1!B2) is a symbol. Each symbol holds one typed value.
2. Cells are computed by formulas. A formula is an expression that may reference other cells. Cyclic references are detected and reported as #CIRC!.
3. Two evaluation modes. = is eager — the cell recomputes whenever its inputs change. ~= is lazy — the cell only computes when read.
4. Two execution classes. Most functions are lua_sync (run in Redis/TS, return immediately). External functions (FX_RATE, HTTP_JSON, ML_SCORE) are external_async — they enqueue a job and return when the worker writes back.
5. Type tags carry semantic meaning. A1 as currency = 1000 says the value is currency, not just a number. Tags drive formatting, validation, and downstream consumers.
6. Errors are values. #N/A, #DIV/0!, #VALUE!, #REF!, #NUM!, #NAME?, #NULL!, #CALC!, #SPILL!, #TYPE!, #CIRC! flow through formulas. Use IFERROR, TRY, DEFAULT, or ASSERT to handle them.
7. Arrays spill. A formula that returns an array writes into a rectangle of cells anchored at its target. Use A1# to refer to the spilled rectangle as a single value.
8. Rules trigger on conditions or schedules. WHEN, EVERY, and AT blocks let a model react to state changes or time. They are currently TS-runtime-only.

That's the whole conceptual surface. The rest is syntax, function catalog, and operational concerns.

File Format Summary

A .grid file looks like this:

MODEL "My Model"
DESCRIPTION "What this model does."
RUNTIME "lua_generated"
VERSION "1.0.0"
AUTHOR "you@example.com"
TAGS "demo", "v1"
 
# Inputs
A1 as currency = 100000
A2 as percentage = 21pct
 
# Derivations
B1 as currency = A1 * (1 - A2)
B2 = B1 > 50000 THEN "ok" ELSE "small"
 
END MODEL

The header directives are all optional (the file will parse without them) but every shared model in the canonical library uses them.

Three Runtimes, One Language

Grid ships three runtime engines:

All three runtimes use the same parser, the same function library (496 functions), the same type system, and the same error model. Output values are byte-equivalent for the portable subset.

The default at deploy time is selected by the GRID_RUNTIME_ENGINE environment variable. Source-level RUNTIME "..." directives in the file header override the default per-model.

Other environment variables that affect deployment topology (tier, real-time transport, worker mode, Redis transport) are documented in docs/specs/deployment_tiers.md.

When in doubt, start with lua_generated and only switch to ts when you need rules.

How To Ask For Help

• Looking for a function? Open functions.md and search by name or category.
• Got a syntax error? Check errors.md and reference.md.
• Don't know how to express something? Look in cookbook.md.
• Generating code from an LLM? Read ai-agent-guide.md and feed it as system context to the agent.

Related Documents

These live outside docs/language/ and cover surrounding concerns:

• docs/architecture.md — How the engine is built.
• docs/api/http_api.md — REST + WebSocket endpoints.
• docs/specs/parser_authoring.md — The formal grammar contract.
• docs/specs/external_functions.md — The full async function spec.
• docs/specs/deployment_tiers.md — Fly.io Machine deployment contract.
• examples/canonical/ — Seven worked examples in increasing complexity.

Versioning

This documentation tracks the language as of Grid 1.0.0-rc.*. Breaking changes between RCs may move syntax around; pinned 1.0.0 will freeze the language surface for the lifetime of the major version.

The machine-readable grammar.json carries a version field that should be checked by tools that consume it.