When Fabric regressions force literal OneLake URLs, document the workaround
Parameterized DataLake expressions can work for months and then fail across stages overnight. Teams panic-rewrite convention docs as if literal OneLake URLs were always the design goal. That erases history and guarantees the workaround becomes religion.
Reframe "literal URL required" failures as service regressions. Ship validators and literal patches as temporary controls. Keep a Test to Preprod to Prod promotion story under the workaround. File and track the Microsoft support trail next to the repo convention. Do not pretend the platform always wanted hard-coded URLs.
Figure 1. Direct Lake on OneLake is the intended pattern. Literal URL patches are controls when parameters regress. Source: Microsoft Learn: Direct Lake storage.
I learned this when promotion pipelines that had been boring suddenly demanded literal paths. The temptation was to rewrite every standard as "always use literals." The better move was validators, a staged promotion playbook, and a support case that kept the long-term parameterized intent alive.
The core idea
A regression workaround is not an architecture principle until you decide it is, in writing, after the bug is gone or accepted.
Temporary literal patches can unblock Prod. Permanent dogma without a support trail and a revisit date becomes unpaid debt. Validators catch the failure mode early. Promotion still needs an explicit story per stage. Repo conventions should label workarounds as workarounds.
A model that stays explainable
1. Name the failure as a regression in the ticket
Write what used to work, what failed, which stages, and which error text. Avoid "OneLake requires literals" as the title if parameters worked last month. Accurate naming drives accurate fixes.
2. Ship validators beside patches
Automate checks that fail the pipeline when parameterized expressions break in a stage. Validators turn surprise Prod breaks into Test failures. Pair them with the literal patch so operators know when the patch is still required.
3. Keep parameterized intent in the docs
Document the preferred pattern (parameters/variables) and the temporary literal control. If you only document literals, newcomers will carve them into stone. Dual documentation is honest: desired state versus current control.
4. Write the promotion playbook under the workaround
Test, Preprod, and Prod may need different literal values while the regression lives. Spell the steps: where to patch, who approves, how to verify Direct Lake after promote. Do not rely on one engineer's memory during a Friday promote.
5. Keep the support trail next to the repo
Store case numbers, key emails, and repro notes in the same folder as the convention doc. When the service fixes the regression, you need a path back. Without a trail, nobody will dare remove literals.
6. Schedule a revisit
Put a date or a "revisit when case closes" note on the workaround. Expired workarounds without owners are how temporary becomes eternal. Calendar the revisit like you would a certificate expiry.
Failure modes I design against
Dogma rewrite. Conventions pretend literals were always required.
Patch without validator. Next stage breaks the same way.
No promotion story. Each environment invents a ritual.
Support tribal knowledge. Case id lives in one inbox.
No revisit. Temporary controls outlive the bug by years.
Silent SemPy/script drift. One tool still parameters; another literals; chaos.
What to tell stakeholders
Say: parameterized OneLake paths are still the intended design; a platform regression forces literals in these stages; we are validating, patching, promoting with a playbook, and tracking support; we will remove literals when the case allows. That narrative protects standards better than pretending you chose hard-coding for purity. Stakeholders can accept temporary ugliness. They smell permanent confusion.
Coordinating SemPy and portal edits
Regressions often show up differently in portal actions versus SemPy scripts. Inventory every path that sets DataLake/OneLake expressions. Apply the same workaround policy to each path. Split-brain tooling is how Test looks fixed while automation reintroduces parameters on the next run. One policy, many entry points, shared validators.
How to remove the workaround without drama
When support confirms the fix, re-enable parameters in Test first. Run validators expecting parameters to succeed. Promote with the same playbook in reverse: remove literals stage by stage. Keep the case notes archived. Celebrate the removal in the same channel that announced the workaround so the team learns that temporary meant temporary.
Do not let SemPy samples become the new standard
Example notebooks that hard-code literals to unblock a blog post or an internal sample will be copied into Prod. Mark samples with WARNING headers when they demonstrate a workaround. Better: samples show parameters, and a separate "regression control" snippet shows literals with a link to the ADR. Copy-paste culture will follow whatever you leave unmarked.
Trade-offs
Literal patches are ugly and environment-specific. Failed promotes are uglier. Maintaining dual docs (desired vs workaround) costs attention; single docs that lie cost more. Support cases take time; without them you never get permission to revert. Validators add CI minutes and save weekends.
What I would put on an ADR
- Preferred pattern remains parameterized OneLake/Direct Lake configuration.
- Active regressions may require literal URL controls labeled as temporary.
- Validators detect the failure mode per stage before Prod.
- Promotion playbooks cover literal patches across Test/Preprod/Prod.
- Support case artifacts live beside the convention in Git.
- Workarounds have owners and revisit dates; removal is a tracked task when fixed.
Primary references: Direct Lake overview and OneLake path guidance on Microsoft Learn, plus your internal support notes. Pair product docs with the workaround ADR so engineers know which reality they are operating in.
Closing
When the platform regresses, do not rewrite history to match the bug.
Patch to survive. Validate to detect. Promote with a playbook. Track support. Revisit on purpose. Literal OneLake URLs can be a control. They should not become your architecture story by accident.