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  │
                  └──────────────┬──────────────┘
                                 │ run
                                 ▼
                  ┌─────────────────────────────┐
                  │  Grid runtime               │
                  │  hosted or local validation │
                  └─────────────────────────────┘

A Grid file (.grid) is parsed to an AST, built into a model (a graph of typed cells), and then run by the Grid runtime. Hosted execution and local validation 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 synchronous and 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.

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."
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.

Managed Runtime, One Language

Grid uses the same parser, the same function library (548 functions), the same type system, and the same error model everywhere it runs. Hosted execution, previews, tests, and local validation all produce the same values for the portable subset.

In most models you can omit the RUNTIME directive. The platform picks the right execution profile for the deployment, and source-level runtime directives are reserved for advanced operator workflows.

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 — Hosting and 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.