Conventions

A handful of small rules apply across every GDQL statement. Learn them once and the rest of the language reads like English.

Case#

Keywords and identifiers are case-insensitive. Write whichever style you find readable — SHOWS, shows, and Shows all parse identically. The convention in these docs is uppercase keywords because they stand out from song names, but the parser doesn’t care.

SETLIST FOR 5/8/77;

setlist for 5/8/77;

Shows From 1977 Limit 5;

String literals (song names, venue names) keep whatever case you typed inside the quotes — but the lookup itself is also case-insensitive, so "dark star" and "DARK STAR" find the same song.

Strings#

Wrap string literals in double quotes. Use them for song titles, venue names, city names, guest musicians — anything that isn’t a number, date, or keyword.

PERFORMANCES OF "Eyes of the World";

SHOWS AT "Winterland";

SHOWS WHERE PLAYED "Scarlet Begonias";

Single quotes work too. They’re handy when shell escaping gets ugly:

gdql 'SHOWS WHERE PLAYED "Scarlet Begonias"'

GDQL is forgiving about punctuation and exact spelling — "Help on the Way!" and "Help on the Way" resolve to the same song, and apostrophes in titles like "Franklin's Tower" work as written. Specifically, song lookup will:

• Strip apostrophes — "Truckin" finds "Truckin'"
• Strip periods — "St Stephen" finds "St. Stephen"
• Normalize spacing — "Wharfrat" finds "Wharf Rat"
• Expand Saint to St. — "Saint Stephen" finds "St. Stephen"
• Tolerate trailing exclamation marks and other punctuation

When you can’t remember a title, run SONGS ORDER BY NAME or SONGS WITH LYRICS("...") to find the canonical form.

Comments#

Line comments start with -- and run to the end of the line. Use them to label queries you’re sharing or to leave notes in saved files.

SETLIST FOR 5/8/77;

Trailing comments work too:

SHOWS FROM 1977;             -- Europe '77 + Cornell year SONGS WITH LYRICS("rose");   -- the rose songs

Comments work in multi-statement blocks too — handy for labeling each query in a batch:

-- Cornell '77 and the next two nights
SETLIST FOR 5/7/77;
SETLIST FOR 5/8/77;  -- the famous one
SETLIST FOR 5/9/77;

There is no block comment syntax. If you need to comment out several lines, prefix each one with --.

Statement termination#

Semicolons end statements but are optional for a single query. Use them whenever you want to chain multiple queries into one input.

SETLIST FOR 5/8/77

When you have more than one query, separate them with ;:

SHOWS FROM 1977 LIMIT 5;

SETLIST FOR 5/8/77;

SONGS WITH LYRICS("train");

The CLI runs each statement in order and prints the results back-to-back.

Try in Sandbox

Whitespace#

Whitespace exists for readability. Spaces, tabs, and newlines are interchangeable wherever they’re allowed, but at least one whitespace character must separate adjacent tokens — SHOWS WHERE is valid, SHOWSWHERE is not.

Indent and break long queries however you like:

SHOWS AT "Winterland" FROM 1977-1978 WHERE "Scarlet Begonias" > "Fire on the Mountain" AND PLAYED "Estimated Prophet" ORDER BY DATE LIMIT 10;

Quick summary#

Next up: read WHERE conditions for filtering, or Operators for the full token list.