Source macros

Source macros let an Athena query read raw files in S3 without you pre-registering a table. StrataBI rewrites the macro into a Glue external table before the query runs.

Syntax

Two formats are supported:

SELECT * FROM !parquet('s3://my-bucket/exports/sales/')
SELECT * FROM !csv('s3://my-bucket/exports/regions.csv')

These are not Athena SQL. StrataBI detects the macro, ensures a backing table exists, and substitutes the real table name into the query before submission.

How resolution works

1. The macro's S3 URI is parsed. A file (.../file.parquet) resolves to its parent prefix; a prefix (.../sales/) is used as-is. Athena external tables point at prefixes, not single files.
2. A deterministic table name is derived from the format + URI, so the same source always maps to the same table and is reused across queries.
3. If the table doesn't exist yet, StrataBI infers columns — from Parquet file metadata, or by sniffing the first rows of a CSV — and creates a Glue external table in the StrataBI catalog database.
4. The macro is replaced with the qualified table name and the query runs.

Common mistakes

• Full s3:// URI required. A bare key or a path without the scheme is rejected.
• Mixed schemas under one prefix. External tables assume a consistent schema across the prefix; mixing column layouts produces query errors.
• CSV headers. CSV tables are created with a header-row skip; make sure your files actually have a header row.