Edit

Items - Upgrade Sql Endpoint Metadata Sync

Upgrades metadata sync for the specified SQL analytics endpoint.

Note

Metadata sync migration is currently in Preview (learn more).

This API supports long running operations (LRO).

Migrates the endpoint's tables from the v1 regular-table architecture to the v2 external-table architecture. Repeated invocations reattempt only tables that have not reached v2.

Permissions

The caller must have write permission on the SQL analytics endpoint item.

Required Delegated Scopes

Item.ReadWrite.All or SQLEndpoint.ReadWrite.All

Microsoft Entra supported identities

This API supports the Microsoft identities listed in this section.

Identity Support
User Yes
Service principal and Managed identities Yes

Interface

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/sqlEndpoints/{itemId}/upgradeMetadataSync

URI Parameters

Name In Required Type Description
itemId
path True

string (uuid)

The SQL analytics endpoint ID.

workspaceId
path True

string (uuid)

The workspace ID.

Responses

Name Type Description
200 OK

MetadataSyncMigrationResult

Request completed successfully.

202 Accepted

Request accepted, metadata sync upgrade in progress.


Headers:

Location string - The URL of the operation status, which can be used to track the operation state.

x-ms-operation-id string (uuid) - The operation ID which can be used with long running operations (LRO) APIs to track the operation state and get the result.

Retry-After integer - The number of seconds to wait before retrying the request.

Headers

  • Location: string
  • x-ms-operation-id: string
  • Retry-After: integer
429 Too Many Requests

ErrorResponse

The service rate limit was exceeded. The server returns a Retry-After header indicating, in seconds, how long the client must wait before sending additional requests.

Headers

Retry-After: integer

Other Status Codes

ErrorResponse

Common error codes:

  • ItemNotFound - The requested item was not found.

  • LockConflict - The SQL analytics endpoint is busy with another lock-holding operation.

Examples

Upgrade metadata sync example

Sample request

POST https://api.fabric.microsoft.com/v1/workspaces/41ce06d1-d81b-4ea0-bc6d-2ce3dd2f8e87/sqlEndpoints/9b1e77c2-6a4e-4f0b-bd3a-1f2c0d4e5a6b/upgradeMetadataSync

Sample response

{
  "syncArchitectureVersion": "V2",
  "itemMigrationStatus": "PartiallySucceeded",
  "tableStatuses": [
    {
      "schema": "dbo",
      "tableName": "Orders",
      "syncArchitectureVersion": "V2",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:25Z"
    },
    {
      "schema": "dbo",
      "tableName": "OrderDetails",
      "syncArchitectureVersion": "V1",
      "lastSuccessfulSyncDateTime": "2026-06-08T10:15:02Z",
      "error": {
        "errorCode": "DeltaTableNotFound",
        "message": "Delta table 'Tables\\OrderDetails\\_delta_log' was not found."
      }
    }
  ]
}

Definitions

Name Description
ErrorParameter

A structured parameter providing additional machine-readable context about an error.

ErrorRelatedResource

The error related resource details object.

ErrorResponse

The error response.

ErrorResponseDetails

The error response details.

ItemMigrationStatus

The overall outcome of a metadata sync migration. Additional ItemMigrationStatus types may be added over time.

MetadataSyncMigrationResult

The result of a completed metadata sync migration.

MetadataSyncTableMigrationStatus

The metadata sync migration status of a table.

SyncArchitectureVersion

The synchronization architecture version. Additional SyncArchitectureVersion types may be added over time.

ErrorParameter

A structured parameter providing additional machine-readable context about an error.

Name Type Description
message

string

A human-readable description of the parameter's meaning.

name

string

The parameter identifier.

value

string

The parameter value.

ErrorRelatedResource

The error related resource details object.

Name Type Description
resourceId

string

The resource ID that's involved in the error.

resourceType

string

The type of the resource that's involved in the error.

ErrorResponse

The error response.

Name Type Description
errorCode

string

A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.

isRetriable

boolean

When true, the request can be retried. Use the Retry-After response header to determine the delay, if available.

message

string

A human readable representation of the error.

moreDetails

ErrorResponseDetails[]

List of additional error details.

parameters

ErrorParameter[]

Structured parameters providing additional machine-readable context about the error.

relatedResource

ErrorRelatedResource

The error related resource details.

requestId

string (uuid)

ID of the request associated with the error.

ErrorResponseDetails

The error response details.

Name Type Description
errorCode

string

A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.

message

string

A human readable representation of the error.

parameters

ErrorParameter[]

Structured parameters providing additional machine-readable context about the error.

relatedResource

ErrorRelatedResource

The error related resource details.

ItemMigrationStatus

The overall outcome of a metadata sync migration. Additional ItemMigrationStatus types may be added over time.

Value Description
Succeeded

The migration completed with no table failing to convert.

PartiallySucceeded

At least one table reached the target architecture and at least one table failed to convert.

Failed

Every table that needed conversion failed, and the endpoint remains on its prior architecture.

MetadataSyncMigrationResult

The result of a completed metadata sync migration.

Name Type Description
itemMigrationStatus

ItemMigrationStatus

The overall outcome of the migration.

syncArchitectureVersion

SyncArchitectureVersion

The synchronization architecture version of the endpoint after the migration.

tableStatuses

MetadataSyncTableMigrationStatus[]

The migration status of every table on the endpoint.

MetadataSyncTableMigrationStatus

The metadata sync migration status of a table.

Name Type Description
error

ErrorResponseDetails

The error details for a stalled or failed table. This property is omitted when the table has no error.

lastSuccessfulSyncDateTime

string (date-time)

This property is omitted if the table has never synchronized successfully. The date and time when the table last synchronized successfully in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.

schema

string

The schema name of the table.

syncArchitectureVersion

SyncArchitectureVersion

The synchronization architecture version that the table is currently using.

tableName

string

The unqualified name of the table.

SyncArchitectureVersion

The synchronization architecture version. Additional SyncArchitectureVersion types may be added over time.

Value Description
V1

The v1 regular-table synchronization architecture.

V2

The v2 external-table synchronization architecture.