The Coral Quirks I Learned the Hard Way

I Built an Unofficial Developer Guide for Coral While Debugging My Hackathon Project

Coral 🪸Atlas

Link to the guide: https://coral-atlas-query-ex-26t5.bolt.host/

When I started building RasmalAI for the Coral hackathon, I assumed the hardest part would be the AI correlation logic. It wasn’t. The hardest part was figuring out why my queries kept returning zero rows.

Coral is genuinely powerful. A SQL interface over live GitHub and Slack data, no API wrangling, no OAuth plumbing — just write a SELECT and get rows back. But like any new data layer, the gap between “it works in theory” and “it works for my specific query” is filled with small quirks that only reveal themselves when you’re deep in a debugging session at 1am.

So I started taking notes.

The query that broke me first

The one that cost me the most time was deceptively simple. I was querying GitHub issues to power the incident correlation engine in RasmalAI — looking for recent PRs, deploy events, open bugs. The query looked right. Coral accepted it. It returned zero rows every time.

After a lot of trial and error I found the issue. Coral expects repository-scoped filtering with explicit owner and repo fields:

WHERE owner = ‘your-org’ AND repo = ‘your-repo’

Not the repository_full_name format I had tried first. One field name difference, complete silence from the query engine, no error message to point you in the right direction. Once I knew, it was obvious. Before I knew, it was a black hole.

That moment is what pushed me to build Coral Atlas.

What Coral Atlas is

Coral Atlas is an unofficial developer guide for working with Coral connectors — specifically the GitHub and Slack connectors that most hackathon builders are likely to reach for first.

It covers the things that aren’t immediately obvious from the official docs:

Nested field access. Coral uses double underscores for nested fields. So if you want the author’s name from a GitHub issue, it’s author__name, not author.name. Small thing, completely non-obvious the first time.

Search query syntax. GitHub’s search parameter inside Coral SQL has its own semantics that differ from what you might expect coming from REST API experience.

Repository scoping. The owner and repo filter requirement described above, plus other connector-specific patterns that affect whether your query returns data at all.

Working examples. Copy-paste SQL for common operational intelligence workflows — security advisory feeds, Slack incident channel queries, cross-source data pulls.

Troubleshooting notes. The actual errors and silent failures I hit while building RasmalAI, documented so you don’t have to rediscover them.

Why I built it as a standalone tool

I could have just posted a list of tips on Discord. But the thing about connector quirks is that they’re contextual — a note about nested field syntax is much more useful when you can see it next to a working query that uses it. So I built it as an interactive guide at coral-atlas-query-ex-26t5.bolt.host where you can browse by connector, see working examples in context, and search for the specific thing you’re stuck on.

It’s unofficial, opinionated, and built entirely from my own experience debugging RasmalAI. Which means it probably has gaps — especially for connectors I haven’t used yet.

That’s where you come in

If you’re building on Coral and you’ve hit a quirk that isn’t documented anywhere, I want to hear about it. Every undocumented behavior that gets added to Coral Atlas is one less hour another builder spends staring at zero rows wondering what went wrong.

The guide is live at coral-atlas-query-ex-26t5.bolt.host. Feedback welcome — drop a comment here or find me in the Coral Discord.

RasmalAI, the project that started all this, is a real-time incident correlation platform connecting GitHub, Slack, and security advisory feeds into an AI-powered command center. If you’re curious about the architecture or the Deploy Regression Detector we built on top of Coral, that’s a separate post for another day. Soon a blog post on this as well :)