Spaces and dataset references

Hamelin separates spaces from namespaces (nested grouping within a space). Dataset references in FROM, JOIN, UNION, APPEND, LOOKUP, and MATCH use a single colon between the space and the rest of the path; dots continue to mean namespace nesting and field access elsewhere in the language.

Syntax

Form	Meaning
events	Table in the query default space (see below)
signals.events	Namespace signals, table events, in the default space
other:signals.events	Space other, namespace signals, table events

Colons appear at most once per dataset reference, and only in table positions. Field paths (event.original), map literals ({key: value}), and struct types are unchanged.

Canonical catalog keys

After resolution, catalog entries and datasets() output use the canonical form:

space:namespace.table

Nested namespaces add more dot segments after the colon, for example acme:connectors.s3.events.

Default space (query context)

Unqualified references (FROM events) require a default space supplied with the query, similar to an injected time_range:

• Ad-hoc queries: the management plane passes the space selected in the query editor.
• Deployed resources: the resource’s space is passed as default_space; the query source is not rewritten.

If no default space is provided, type-checking fails with an error such as “no default space for unqualified dataset reference”.

CLI

Set a default space in ~/.hamelin.toml:

default_space = "acme"

Or pass it per command (overrides config):

hamelin translate --default-space acme -f query.hmln
hamelin execute --default-space acme -f query.hmln

Compiler (WASM / TypeScript)

compileHamelinQuery and getDatasetsFromQuery accept an optional defaultSpace argument that is forwarded to the WASM bindings.

Cross-space access

Use an explicit space prefix when a query must read data outside the default space:

FROM other:signals.events
| WHERE ...