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 |
|---|---|---|---|---|
|
item
|
path | True |
string (uuid) |
The SQL analytics endpoint ID. |
|
workspace
|
path | True |
string (uuid) |
The workspace ID. |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK |
Request completed successfully. |
|
| 202 Accepted |
Request accepted, metadata sync upgrade in progress. Headers: Location x-ms-operation-id Retry-After Headers
|
|
| 429 Too Many Requests |
The service rate limit was exceeded. The server returns a Headers Retry-After: integer |
|
| Other Status Codes |
Common error codes:
|
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 |
|---|---|
|
Error |
A structured parameter providing additional machine-readable context about an error. |
|
Error |
The error related resource details object. |
|
Error |
The error response. |
|
Error |
The error response details. |
|
Item |
The overall outcome of a metadata sync migration. Additional ItemMigrationStatus types may be added over time. |
|
Metadata |
The result of a completed metadata sync migration. |
|
Metadata |
The metadata sync migration status of a table. |
|
Sync |
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 |
| message |
string |
A human readable representation of the error. |
| moreDetails |
List of additional error details. |
|
| parameters |
Structured parameters providing additional machine-readable context about the error. |
|
| relatedResource |
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 |
Structured parameters providing additional machine-readable context about the error. |
|
| relatedResource |
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 |
The overall outcome of the migration. |
|
| syncArchitectureVersion |
The synchronization architecture version of the endpoint after the migration. |
|
| tableStatuses |
The migration status of every table on the endpoint. |
MetadataSyncTableMigrationStatus
The metadata sync migration status of a table.
| Name | Type | Description |
|---|---|---|
| error |
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 |
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. |