Skip to main content

Magpie DSL

The Magpie DSL is the command language behind the Magpie Notebook's default %magpie interpreter, the CLI, and .magpie script files — it's what create table, alter cluster, grant role, and every other command in the command reference are written in. This page covers the syntax fundamentals that cut across all of those commands, rather than repeating them on every reference page.

Quoting​

The DSL accepts three kinds of string literal:

  • Single-quoted — 'like this'
  • Double-quoted — "like this"
  • Triple-quoted — """like this""" ('''like this''' is also accepted, but every example in this documentation uses """)

Single- and double-quoted strings are a single line — a literal newline inside one ends the string early rather than becoming part of it. Triple-quoted strings can span multiple lines, and are the form to reach for whenever a value itself contains quote characters you don't want to escape, such as a password or a block of SQL.

Variable and secret substitution ($#{...}) is processed inside single- and double-quoted strings, but not inside triple-quoted ones — see that page for the full substitution syntax and why triple-quoting is also how you stop it from happening.

Backtick-quoted identifiers​

Object names — table names, schema names, and the rest — are ordinarily written as bare identifiers: my_table, sales. Two things follow from that:

  • Bare identifiers are lowercased. create table MyTable ... and create table mytable ... refer to the same object. If you need to preserve mixed case, quote the name in backticks: `MyTable`.
  • Bare identifiers can't contain spaces or most punctuation. Backticks let a name contain anything except a backtick or a newline, so `my table` or `my-table` are only reachable by quoting them this way.

Semicolons​

Each command is terminated by a semicolon. This is what lets a single command span multiple lines, and what lets a .magpie script or a piped CLI session contain more than one command — see Getting Started with the Magpie CLI for how that plays out when running scripts or piping commands.

Object references​

Most commands identify the object they act on with a reference, and the shape of that reference depends on what kind of object it is — there's no single universal format. The two you'll see most:

  • Table reference: [<schema>.]<table> — a table name, optionally qualified by its schema (sales.transactions, or just transactions to use the current schema).
  • Job reference: [<project>.]<job> — the same pattern, one level up, for jobs within a project.

Both take at most one qualifier, immediately to the left of the name. A repository is never one of those qualifiers — repository.schema.table is not valid syntax; a repository reference always stands alone. Some references go one level deeper still (a field is [<schema>.]<table>.<field> — a bare field name by itself isn't enough, it always needs at least its table), and some take none at all. When a reference command page shows a parameter as <x> reference, that page's syntax block is the place to check exactly what it accepts, rather than assuming it follows the table/job pattern.