Skip to content

Commit dcdbff2

Browse files
docs: expand .table() per-dialect rules and quoting guidance (#315)
Adds MySQL, Snowflake, and Trino/Presto entries to the Table Connection Method section, plus BigQuery wildcard syntax, DuckDB globs and dotted identifiers, a DuckDB literal-quote escape hatch, and a quoting/reserved- words subsection. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent be353b8 commit dcdbff2

1 file changed

Lines changed: 25 additions & 1 deletion

File tree

src/documentation/language/connections.malloynb

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,18 +25,42 @@ In the official Malloy connection implementations, the behavior is as follows:
2525

2626
In BigQuery, the string passed to the `.table()` connection method can be a two- or three-segment path including the (optional) project ID, dataset ID, and table name, e.g. `bigquery.table('project-id.dataset-id.table-name')` or `bigquery.table('dataset-id.table-name')`. If the project ID is left off, the default project ID for the connection will be used, or else the system default if none is set on the connection.
2727

28+
To use a BigQuery wildcard table, the segment containing the wildcard must be backtick-quoted inside the string, e.g. `` bigquery.table('`my-project.analytics.events_*`') ``.
29+
2830
### Databricks
2931

3032
In Databricks, the string passed to the `.table()` connection method can be a one-, two-, or three-segment path: `table`, `schema.table`, or `catalog.schema.table`. If the catalog or schema is omitted, the configured defaults (or workspace defaults) are used.
3133

3234
### DuckDB
3335

34-
In DuckDB, the `.table()` method accepts the path (relative to the Malloy file) of a CSV, JSON, or Parquet file containing the table data, e.g. `duckdb.table('data/users.csv')` or `duckdb.table('../../users.parquet')`. URLs to such files (or APIs) are also allowed: see [an example here](../patterns/apijson.malloynb).
36+
In DuckDB, the `.table()` method accepts the path (relative to the Malloy file) of a CSV, JSON, or Parquet file containing the table data, e.g. `duckdb.table('data/users.csv')` or `duckdb.table('../../users.parquet')`. URLs to such files (or APIs) and glob patterns (`duckdb.table('data/*.parquet')`) are also allowed; see [an example here](../patterns/apijson.malloynb). DuckDB also accepts dotted identifier paths (`schema.table`) for tables defined inside the database.
37+
38+
If Malloy doesn't recognize the argument as a file path, wrap it in literal single quotes — `` duckdb.table("'/actual/path'") `` — to pass the quoted string straight through to DuckDB.
39+
40+
### MySQL
41+
42+
In MySQL, the string passed to the `.table()` connection method can be a one- or two-segment path: `table` or `database.table`. If the database is omitted, the connection's default database is used.
3543

3644
### Postgres
3745

3846
In Postgres, the string passed to the `.table()` connection method can be a two- or three-segment path including the (optional) database ID, schema name, and table name, e.g. `postgres.table('database-id.schema-name.table-name')` or `postgres.table('schema-name.table-name')`. If the database ID is left off, the default database for the connection will be used, or else the system default if none is set on the connection.
3947

48+
### Snowflake
49+
50+
In Snowflake, the string passed to the `.table()` connection method can be a one-, two-, or three-segment path: `table`, `schema.table`, or `database.schema.table`. Omitted segments fall back to the connection's configured database and schema.
51+
52+
### Trino / Presto
53+
54+
In Trino and Presto, the string passed to the `.table()` connection method can be a one-, two-, or three-segment path: `table`, `schema.table`, or `catalog.schema.table`. Omitted segments fall back to the connection's configured catalog and schema.
55+
56+
### Quoting and reserved words
57+
58+
To use a reserved word or a name containing special characters as a path segment, quote it with the dialect's identifier quote character: `"…"` for Postgres, Snowflake, and Trino/Presto; `` `…` `` for MySQL, Databricks, and BigQuery. For example:
59+
60+
```malloy
61+
source: orders is postgres.table('public."order"')
62+
```
63+
4064
## SQL Connection Method
4165

4266
The `.sql()` connection method is used to define a source or query based on a SQL query. See the [SQL Sources](./sql_sources.malloynb) section for more information.

0 commit comments

Comments
 (0)