Key takeaways
- Preferred pattern remains parameterized OneLake and Direct Lake configuration.
- Active regressions may require literal URL controls labeled as temporary.
- Ship validators beside patches so Test fails before Prod.
- Keep a Test to Preprod to Prod promotion playbook under the workaround.
- Store support case artifacts beside the convention in Git.
- Give every workaround an owner and a revisit date; removal is a tracked task.
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.
Named model: temporary control, not dogma
- Preferred intent: parameterized OneLake and Direct Lake configuration remains the design goal, documented as the desired state.
- Temporary control: literal URL patches labeled as temporary, paired with stage validators and an explicit promotion playbook.
- Path back: support case artifacts in Git, an owner, a revisit date, and a stage-by-stage removal plan when the case allows.
- Contract: a regression workaround is not an architecture principle until you decide it is, in writing, after the bug is gone or accepted.
Figure 1. Temporary control, not dogma. Keep parameterized intent in the docs. Literal patches unblock; they do not rewrite the standard.
Context and constraint
A common failure: promotion pipelines that were boring suddenly demand literal paths. The temptation is to rewrite every standard as "always use literals." The better move is validators, a staged promotion playbook, and a support case that keeps the long-term parameterized intent alive.
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.
Figure 2 is the Learn surface for connecting a Direct Lake model to storage. The intended pattern is OneLake-backed Direct Lake. Literal URL patches are controls when parameters regress, not the architecture story.
Figure 2. Direct Lake on OneLake is the intended pattern. Literal URL patches are controls when parameters regress. Source: Microsoft Learn: Direct Lake storage.
Design
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 and 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.
Figure 3 is the pair that stops the next stage inventing a private ritual.
Figure 3. Validators beside literal patches. Patch without a validator is how Preprod and Prod each invent the same fire drill.
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.
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 or 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.
Figure 4 is the coordination contract, and the reverse playbook when support confirms the fix.
Figure 4. One policy across portal and SemPy. When the case closes, re-enable parameters in Test first and remove literals stage by stage.
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.
Common mistakes
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 or script drift. One tool still parameters; another literals; chaos.
Use as-is or adapt
Use as-is
- Preferred pattern remains parameterized OneLake and 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, and Prod.
- Support case artifacts live beside the convention in Git.
- Workarounds have owners and revisit dates; removal is a tracked task when fixed.
Adapt before you use
Literal patches are ugly and environment-specific. Failed promotes are uglier. Maintaining dual docs (desired versus 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.
Primary references: Direct Lake overview and Direct Lake storage on Microsoft Learn, plus your internal support notes. Pair product docs with the workaround ADR so engineers know which reality they are operating in.
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.