Items - Preflight Sql Endpoint Metadata Sync Upgrade
Assesses the specified SQL analytics endpoint for a metadata sync upgrade.
Note
Metadata sync migration is currently in Preview (learn more).
This API supports long running operations (LRO).
Runs a readiness assessment without converting any table and returns blocking issues and table eligibility counts.
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}/preflightMetadataSyncUpgrade
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 assessment 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
Preflight metadata sync upgrade example
Sample request
POST https://api.fabric.microsoft.com/v1/workspaces/41ce06d1-d81b-4ea0-bc6d-2ce3dd2f8e87/sqlEndpoints/9b1e77c2-6a4e-4f0b-bd3a-1f2c0d4e5a6b/preflightMetadataSyncUpgrade
Sample response
{
"evaluatedTableCount": 1250,
"eligibleTableCount": 1248,
"blockers": [
{
"schema": "dbo",
"tableName": "LegacyAudit",
"correctiveAction": "Remove the unsupported column type before upgrading, then rerun preflight."
},
{
"schema": "sales",
"tableName": "ArchivedOrders",
"correctiveAction": "Recreate the table with a supported Delta writer version, then rerun preflight."
}
]
}
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. |
|
Metadata |
An issue that prevents a table from migrating. |
|
Metadata |
The result of a metadata sync migration preflight assessment. |
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. |
MetadataSyncMigrationBlocker
An issue that prevents a table from migrating.
| Name | Type | Description |
|---|---|---|
| correctiveAction |
string |
The corrective action the caller can take to unblock the table. |
| schema |
string |
The schema name of the affected table. |
| tableName |
string |
The name of the affected table. |
MetadataSyncMigrationPreflightResult
The result of a metadata sync migration preflight assessment.
| Name | Type | Description |
|---|---|---|
| blockers |
The blocking issues found during the assessment. |
|
| eligibleTableCount |
integer (int32) |
The number of tables eligible to migrate. |
| evaluatedTableCount |
integer (int32) |
The number of tables evaluated. |