Language reference
This is the full GDQL (Grateful Dead Query Language) reference. Start with Conventions for the rules that apply everywhere, then drill into the query type or condition you need.
Query types
Every GDQL statement starts with one of these four keywords. They define what kind of result you get back.
| Query | Returns | Read more |
|---|---|---|
SHOWS | One row per concert. The workhorse — filter by venue, date, era, segue, set position, played, guest. | SHOWS |
SONGS | One row per song in the catalog. Filter by lyrics and written date. | SONGS |
PERFORMANCES | One row per time a song was played. Filter by date and length. | PERFORMANCES |
SETLIST | The full setlist for a single show. | SETLIST |
There are also:
| Query | Returns | Read more |
|---|---|---|
COUNT | How many performances or shows match a filter. | COUNT |
FIRST / LAST | The first or last time a song was played. | FIRST / LAST |
RANDOM SHOW | A random show’s setlist, optionally from an era. | RANDOM SHOW |
Conditions and operators
| Topic | What it covers |
|---|---|
| Conventions | Case rules, strings, comments, statement termination, whitespace |
| WHERE conditions | Segues (>, >>, ~>), set positions, PLAYED, GUEST, LENGTH, and combining with AND/OR/NOT |
| Operators | The complete token reference: segues, comparisons, dates, eras, and output formats |
How the pieces fit together
A typical query reads like a sentence: a query type, optional filters, and an output shape.
SHOWS AT "Winterland" FROM 1977-1978 WHERE "Scarlet Begonias" > "Fire on the Mountain" AND PLAYED "Estimated Prophet" ORDER BY DATE LIMIT 10 AS JSON;That single statement asks: “Give me the first 10 Winterland shows from 1977 or 1978 where Scarlet went into Fire and they also played Estimated Prophet, oldest first, as JSON.”
For more queries like this, see Cookbook.
New to GDQL? Start at Getting Started to install the CLI, or jump straight into the Sandbox to try queries in the browser.