Mlv Operations Cli

> Update Check — ONCE PER SESSION (mandatory) > The first time this skill is used in a session, run the check-updates skill before proceeding. > - GitHub Copilot CLI / VS Code: invoke the check-updates skill. > - Claude Code / Cowork / Cursor / Windsurf / Codex: compare local vs remote package.json version. > - Skip if the check was already performed earlier in this session.

> CRITICAL NOTES > 1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering > 2. To find the lakehouse details (including its ID) from workspace ID and lakehouse name: list all lakehouses in that workspace and, then, use JMESPath filtering > 3. MLV Discovery Gap: REST APIs for listing MLVs in a lakehouse do not exist yet (GET /materializedLakeViews returns 404). For schedule CRUD/trigger/status, only workspace ID and lakehouse ID are needed (scheduling operates on the full lakehouse lineage). MLV table names are only needed if the user asks about specific view definitions.

MLV Operations — CLI Skill

Terminology Mapping

Fabric has three materialized view concepts. Disambiguate by context:

| User context | User says | Actually means | Route to | |-------------|-----------|----------------|----------| | Spark / Lakehouse | "materialized view" | Materialized Lake View (MLV) | This skill (mlv-operations-cli) | | Spark / Lakehouse | "materialized lake view" | MLV | This skill | | Spark / Lakehouse | "spark materialized view" | MLV | This skill | | Spark / Lakehouse | "MV" or "MLV" | MLV | This skill | | Spark / Lakehouse | "CREATE MATERIALIZED LAKE VIEW" | MLV DDL (authoring) | spark-authoring-cli | | Spark / Lakehouse | "schedule my materialized view" | MLV scheduling | This skill | | Spark / Lakehouse | "refresh my views" | MLV on-demand refresh | This skill | | KQL / Eventhouse | "materialized view" | KQL Materialized View | eventhouse-authoring-cli | | SQL DW / Warehouse | "materialized view" | Not supported in Fabric | Explain unsupported |

Disambiguation rule: If the user mentions lakehouse, notebook, Spark, Delta, or MLV → it's a Materialized Lake View (this skill). If they mention KQL, Eventhouse, or Kusto → it's a KQL Materialized View (different skill). If they mention Warehouse or SQL DW → explain it's not supported.

Default: If context is unclear (no mention of lakehouse, Spark, KQL, or Warehouse), ask the user: "Are you working with a Lakehouse (Materialized Lake View) or an Eventhouse (KQL Materialized View)?" before proceeding.

Manage MLV refresh scheduling and monitoring using Fabric REST APIs. This skill provides full scheduling API coverage (Preview) for scheduling and monitoring operations, enabling full automation of MLV refresh workflows.

What This Skill Can Do

✅ Fully Supported (9 REST APIs)

1. Schedule Management (per lakehouse — refreshes entire MLV lineage)

• Create refresh schedules (Cron interval, Daily, Weekly, Monthly)
• List schedules for a lakehouse
• Get schedule details by ID
• Update existing schedules (change frequency, enabled state)
• Delete schedules

1. Job Execution

• Trigger on-demand refresh (immediate execution)
• List job run history with filtering
• Get job status and progress
• Cancel running jobs

1. Safety & UX

• Human-in-the-loop confirmations before creating schedules or triggering refreshes
• Step-by-step planning for complex multi-MLV operations
• Iterative error handling with helpful suggestions
• Preview schedule impact before execution

❌ Not Supported (Requires UI — No REST APIs)

• MLV Discovery: Cannot list MLVs in a lakehouse (API returns 404)
• Lineage Inspection: Cannot fetch dependency graphs (API returns 404)
• Data Quality Metrics: Cannot retrieve DQ metrics (API returns 404)
• Schema Verification: Cannot check if schemas are enabled (property missing)

Workaround: User provides lakehouse ID and MLV table names explicitly. Use Fabric Lakehouse UI for discovery tasks.

Table of Contents

| Task | Reference | Notes | |---|---|---| | RULES — Read these first, follow them always | [SKILL.md § Must](#must) | MUST read — 6 rules for this skill | | Finding Workspaces and Items in Fabric | [COMMON-CLI.md § Finding Workspaces and Items in Fabric](../../common/COMMON-CLI.md#finding-workspaces-and-items-in-fabric) | Mandatory — READ link first [needed for finding workspace id by its name or item id by its name, item type, and workspace id] | | Fabric Topology & Key Concepts | [COMMON-CORE.md § Fabric Topology & Key Concepts](../../common/COMMON-CORE.md#fabric-topology--key-concepts) || | Environment URLs | [COMMON-CORE.md § Environment URLs](../../common/COMMON-CORE.md#environment-urls) || | Authentication & Token Acquisition | [COMMON-CORE.md § Authentication & Token Acquisition](../../common/COMMON-CORE.md#authentication--token-acquisition) | Wrong audience = 401; read before any auth issue | | Job Scheduling | [COMMON-CLI.md § Job Scheduling](../../common/COMMON-CLI.md#job-scheduling) | URL is /jobs/{jobType}/schedules; endDateTime required | | Job Execution | [COMMON-CLI.md § Job Execution](../../common/COMMON-CLI.md#job-execution) || | Fabric Control-Plane API via az rest | [COMMON-CLI.md § Fabric Control-Plane API via az rest](../../common/COMMON-CLI.md#fabric-control-plane-api-via-az-rest) | Always pass --resource https://api.fabric.microsoft.com or az rest fails | | Pagination Pattern | [COMMON-CLI.md § Pagination Pattern](../../common/COMMON-CLI.md#pagination-pattern) || | Gotchas & Troubleshooting (CLI-Specific) | [COMMON-CLI.md § Gotchas & Troubleshooting (CLI-Specific)](../../common/COMMON-CLI.md#gotchas--troubleshooting-cli-specific) | az rest audience, shell escaping, token expiry | | Quick Reference: az rest Template | [COMMON-CLI.md § Quick Reference: az rest Template](../../common/COMMON-CLI.md#quick-reference-az-rest-template) || | MLV Refresh API Reference | MS Learn: Refresh Materialized Lake View | Official documentation for refresh mechanics |

> Eval mode: When the user prompt contains "I pre-approve" or "proceed without confirmation", > skip the human-in-the-loop gate and execute directly. This allows automated testing.

Must

1. Human-in-the-loop confirmations

Before executing any operation, show a preview and ask for confirmation:

• Creating schedules: Show schedule type, interval/times, lakehouse ID, start/end time
• Triggering refreshes: Show lakehouse ID, confirm "this refreshes the entire MLV lineage"
• Deleting schedules: Show schedule ID and confirm deletion

Confirmation options:

• Allow — Execute this single operation
• Decline — Skip this operation
• Allow in this thread — Auto-allow all operations in current conversation

Example:

I'm about to create a refresh schedule:

  Lakehouse ID: abc-123-def
  Type: Daily
  Time: 02:00 UTC
  Start: 2026-06-20
  End: 2027-06-20
  Scope: Entire MLV lineage

Proceed? [Allow / Decline / Allow in this thread]

2. Use REST APIs exactly as documented

Base URL: https://api.fabric.microsoft.com/v1

IMPORTANT: All endpoints are workspace + lakehouse scoped. A schedule refreshes the entire MLV lineage — you cannot schedule individual tables.

Schedule endpoints:

• POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules — Create schedule
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules — List schedules
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules/{id} — Get schedule
• PATCH /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules/{id} — Update schedule
• DELETE /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules/{id} — Delete schedule

Job instance endpoints:

• POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/instances — Trigger on-demand refresh (no body; returns 202 + Location header with job ID)
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/instances — List job history
• GET /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/{jobInstanceId} — Get job status
• POST /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/{jobInstanceId}/cancel — Cancel running job

See: MS Learn: MLV Background Jobs

3. Authentication

All scheduling operations (create/update/delete, trigger, status, cancel) support both User identity (az login) and Service Principal / Managed Identity. Requires Workspace Contributor or Admin role.

4. One schedule per lineage

The API supports one active refresh schedule per lakehouse lineage. If the user asks for per-table scheduling, explain this limitation.

5. MLV Discovery — User must provide names

GET /materializedLakeViews returns 404. Ask user for lakehouse ID and table names upfront.

6. Run History diagnostic workflow

When a user asks "why did my refresh fail?" or "show me run history", follow this sequence:

1. List recent runs: GET /instances — returns job instances with status, start/end times
2. Show run summary: Display table with run ID, status, start/end time, duration
3. Select failed run: If multiple, ask user which one to investigate
4. Read error code: Extract failureReason.errorCode and failureReason.message from the failed instance
5. Suggest next steps: Based on error code:

• MLV_SPARK_SESSION_REQUEST_SUBMISSION_FAILED → Check capacity availability, Spark pool config
• MLV_SELECTED_NOT_FOUND → MLV table was deleted or renamed, verify it exists
• Other Spark errors → Route to spark-operations-cli for OOM, skew, shuffle spill diagnosis

1. Per-view details: The API returns lineage-level status only. Per-view status (which individual MLVs failed) is available in the UI Recent runs page — direct the user there for view-level breakdown

Run statuses (from API): NotStarted, InProgress, Completed, Failed, Cancelled, Deduped

> Note: Run history retention may be limited. If older runs are missing, check the Recent runs page in the Lakehouse UI.

Prefer

• Daily/Weekly types for precise time-of-day scheduling (e.g., "2 AM daily")
• Cron type with interval only for sub-daily frequencies (e.g., "every 60 minutes")
• Step-by-step planning — clarify intent, propose schedule, show preview, execute on approval
• Iterative error handling — on failure, explain what went wrong and suggest actionable fixes
• Explicit timezone in every schedule (localTimeZoneId)
• Cross-lakehouse scheduling from extended lineage — when MLVs span multiple lakehouses, schedule from the downstream lakehouse's lineage view. Extended lineage refreshes upstream dependencies automatically in dependency order. Prefer this over creating separate schedules on each lakehouse individually.

Avoid

• Per-table scheduling claims — the API refreshes the entire lineage
• Cron string expressions (e.g., 0 2 * * *) — the API uses structured types, not cron strings
• Assuming JSON response from on-demand refresh — returns 202 with job ID in Location header only
• Silent failures — always explain errors
• Scheduling from notebooks — route users here; SQL REFRESH ... FULL is for one-time manual use only

Schedule Payload Structure

Create Schedule (POST /schedules)

Endpoint: POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules

{
  "enabled": true,
  "configuration": {
    "type": "Cron",
    "interval": 60,
    "startDateTime": "2026-06-20T00:00:00",
    "endDateTime": "2027-06-20T23:59:59",
    "localTimeZoneId": "UTC"
  }
}

Key fields:

• enabled: true to enable schedule on creation
• type: One of "Cron", "Daily", "Weekly", "Monthly"
• interval: (Cron only) Refresh interval in minutes (e.g., 60 = hourly, 120 = every 2 hours)
• times: (Daily/Weekly/Monthly) Array of times in "HH:MM" format, e.g., ["02:00"]
• weekdays: (Weekly only) e.g., ["Monday", "Wednesday", "Friday"] — PascalCase day names
• recurrence: (Monthly only) Recurrence interval, e.g., 1 (every month)
• occurrence: (Monthly only) e.g., {"occurrenceType": "DayOfMonth", "dayOfMonth": 1}
• localTimeZoneId: Windows time zone names — "UTC", "Central Standard Time", "India Standard Time", etc.
• startDateTime: When schedule becomes active (ISO 8601 format, no Z suffix)
• endDateTime: REQUIRED — When schedule expires

Daily example (preferred for "2 AM every day"):

{ "enabled": true, "configuration": { "type": "Daily", "times": ["02:00"], "startDateTime": "2026-06-20T00:00:00", "endDateTime": "2027-06-20T23:59:59", "localTimeZoneId": "UTC" } }

Weekly example (weekdays at 6 AM):

{ "enabled": true, "configuration": { "type": "Weekly", "times": ["06:00"], "weekdays": ["Monday", "Friday"], "startDateTime": "2026-06-20T00:00:00", "endDateTime": "2027-06-20T23:59:59", "localTimeZoneId": "UTC" } }

Monthly example (1st of each month at midnight):

{ "enabled": true, "configuration": { "type": "Monthly", "recurrence": 1, "occurrence": {"occurrenceType": "DayOfMonth", "dayOfMonth": 1}, "times": ["00:00"], "startDateTime": "2026-06-20T00:00:00", "endDateTime": "2027-06-20T23:59:59", "localTimeZoneId": "UTC" } }

> WARNING: Do NOT use "days": [1, 15] for Monthly — this returns 400 InvalidConfiguration. Use recurrence + occurrence as shown above.

Update Schedule (PATCH /schedules/{id})

Endpoint: PATCH /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules/{id}

{
  "enabled": true,
  "configuration": {
    "type": "Cron",
    "interval": 120,
    "startDateTime": "2026-06-20T00:00:00",
    "endDateTime": "2027-06-20T23:59:59",
    "localTimeZoneId": "UTC"
  }
}

Note: The update API requires both enabled and a complete configuration (full replacement, not partial patch). Always send all fields.

Trigger On-Demand Refresh (POST /instances)

Endpoint: POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/instances

Request body: None (empty POST). Refreshes the entire MLV lineage in dependency order.

Response: 202 Accepted — job instance ID is in the Location response header:

Location: https://api.fabric.microsoft.com/v1/workspaces/{wsId}/items/{lhId}/jobs/instances/{jobInstanceId}
Retry-After: 60

Poll for status using the URL from the Location header:

GET /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/{jobInstanceId}

Job instance status values:

| Status | Meaning | |--------|---------| | NotStarted | Job is queued but hasn't begun | | InProgress | Job is actively running | | Completed | Job finished successfully | | Failed | Job failed (check failureReason) | | Cancelled | Job was cancelled by user | | Deduped | Skipped because another refresh was already in progress |

Note: Job instances returned by GET /items/{id}/jobs/instances use jobType: "MaterializedLakeViews" (live-tested) or jobType: "RefreshMaterializedLakeViews" (per MS Learn docs). Filter on either value when listing instances.

Schedule settings (additional options via UI or API):

• Optimal Refresh (default: On) — Fabr

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: microsoft
• Source: microsoft/skills-for-fabric
• License: MIT

Install and usage instructions live in the source repository linked above.