On tests and documentation
2026-04-27
I'm working on a new semantic layer called 💫 Cantrip, where semantics are defined as VIEWs stored in the database: metrics, dimensions, relationships, metadata — everything lives in views. This has some nice features:
- Expressiveness. It uses native SQL to define metrics, so they can be as complicated as you want, and users don't need to learn a domain specific language (DSL) or a new dialect of SQL.
- Maintenance. There are no services to run. Cantrip is a library, and the code is efficient: it reads only metadata from the information_schema in order to build a semantic graph used for answering requests.
- Portability. There's no vendor lock-in, and it's easy to move it from one database to another: just recreate the views. Currently 3 different databases are supported (SQLite, Postgres, DuckDB), but I'm planning to support 14.
If you're not familiar with semantic layers, they are a way of formalizing the definition of metrics and their relationships, so you can compute metrics in a consistent way in different tools, and break them down by well known dimensions. The missing piece of the modern data stack is a nice article describing how they're useful.
The missing piece of the modern data stack
While getting Cantrip ready for an official release, two common patterns stood out to me:
- Unit tests find bugs. I always strive to have 100% unit test coverage in my projects, and it's impressive how many bugs I can find when I write tests pushing the coverage from 90% to 100%. Those are the tests that cover the edge cases, the not-so-happy paths, the uncommon scenarios. That final stretch is definitely worth the time it takes, because it will prevent the unexpected errors in the future.
- Documentation finds UX friction. I'm currently working on the documentation, and so many times I went back to the code and changed to make the documentation simpler. "If it's hard to explain the code should be simplified" is one of my mottos. I wouldn't call this Documentation Driven Development nor README Drive Development, and much less waterfall — it's more a back and forth between code and documentatin.
Anyway, this is nothing new. But even though I've seen this pattern before in other projects, it still surprises me how many things I've missed that are caught by unit tests and good documentation!