Adding tables to a connected source

A data source is catalogued once, when it’s created, and that create-time import studies the tables it finds. It’s the one moment study is automatic. After that, tables added to the warehouse sit outside the pack until you bring them in, and bringing them in is three separate stages, not one. This guide walks the stages, explains what each intermediate state looks like, and shows how to confirm the new tables are actually answerable.

Two things that don't trigger a re-catalog

Selection rules are a filter, not a trigger. Choosing “all tables” (the empty rule) or a schema-wide rule when you create a source only widens what a catalog pass may include. It doesn’t cause a pass. A table created later inside a schema the source already covers is in scope from the moment it exists, and still isn’t catalogued until you re-catalog.

No timer does it for you. There’s no scheduled re-catalog. import isn’t schedulable, data-sources enrich isn’t a schedulable verb, and a pack’s pack_maintenance schedule works over already-catalogued models rather than re-reading the warehouse.

The four states a table can be in

Two of these look nearly identical and both look like failure. Knowing which one you’re in saves a lot of retrying.

State	How it looks in data-sources models	Answerable?
Not catalogued	Absent from the list	No
Catalogued, unstudied	Listed with a placeholder description like Table DB.SCHEMA.NAME and a single measure	No
Studied, candidates pending	Still the placeholder. The study Action reports succeeded, but the catalog is unchanged	No
Applied	A real description and full measures and dimensions	Yes

The third state is the surprising one. A study proposes learning candidates (descriptions, metrics, relationships) and returns succeeded as soon as it has proposed them. A separate, event-driven review Action validates and applies those candidates later. Only after the review runs does the model change. There is no CLI verb to force, approve, or inspect that application. action get <study-id> lists the candidate ids, and then you wait.

Measured on one pack, the gap between a study succeeding and its candidates being applied ranged from about ten minutes to an hour. Budget for that.

Recipe

1. Re-catalog without studying. This is deterministic and free. It brings new tables into the source’s models and leaves already-studied models alone.

   edisyl import <pack> <data-source-id> --no-study

2. Confirm they landed. The new tables should now appear, with placeholder descriptions.

   edisyl data-sources models <data-source-id>

   Model names are fully qualified and lowercase, database.schema.table, and that exact string is what the next step takes.

3. Study only the new models. One study per new table. Use --guidance to say what matters about it.

   edisyl study <pack> <data-source-id> analytics.public.storm_event_details_2025 \
     --guidance "Yearly partition of storm events; event counts by type and state are what we report on"
   edisyl action watch <action-id>

   The Action reaching succeeded means candidates were proposed, not applied. Don’t re-run the study because the catalog hasn’t changed yet.

4. Wait for the review to apply. Poll the models list until the placeholder descriptions are replaced by real ones and the measure and dimension counts fill out.

   edisyl data-sources models <data-source-id>

5. Verify end to end with a question you know the answer to. The catalog listing proves the models exist. Only an ask proves the pack can reach and use them.

   edisyl ask <pack> "How many storm events were recorded in 2025?" --wait

   Check the number against the source of truth, for example the row count from the load that created the table.

Why not just run enrich or import?

Both study every model in the source, not just the new ones. On a source that already has well-studied models that means re-spending on tables that were fine and overwriting descriptions that were already good. import --no-study followed by targeted study calls avoids both.

enrich is still the right one-liner when nothing has been studied yet, which is the situation right after creating a source. See Semantic layer: pre-enrich or blank slate for that decision.

Selection rules can’t be widened later

--selection-rule is accepted only on data-sources create. There is no data-sources update, and neither import nor enrich takes the flag. A source created with a narrow rule (a single table, say) can’t be widened without deleting and recreating it.

The practical advice: scope at the schema level when you create a source, unless you’re certain the table list is fixed. A schema-level rule keeps future tables in scope, so this guide’s recipe is all you need to bring them in.

Automation

There’s no supported automatic path today. task is schedulable and its fleet does model tables and enrich the semantic layer, so a scheduled task with a brief like “bring in any new tables in the NOAA_STORMS schema” is the plausible route. It has not been tested whether a task can re-introspect the warehouse for tables not yet in the catalog, and the one scheduled maintenance task inspected worked only over already-catalogued models. Treat this as an open question rather than a recipe.

Dimension counts vary between identical tables

After a study, structurally identical tables can end up with slightly different dimension counts (12, 13, 12, 12 across four yearly tables with byte-identical headers, in one observed case). The study derives a varying number of extra dimensions per run. It isn’t schema drift, so don’t read it as one when comparing year-over-year models.

Verified against

This guide reflects the edisyl CLI at version 0.5.0, verified on 2026-09-09. Commands and behaviour here change with the CLI; edisyl <command> --help is authoritative for flags.