Items - Refresh Sql Endpoint Metadata

Service:: SQLEndpoint

API Version:: v1

Refreshes tables within a SQL analytics endpoint.
This API supports long running operations (LRO).

When tables is provided in the request body, only the specified tables are refreshed. When omitted or empty, all tables are refreshed.

Permissions

The caller must have contributor or higher workspace role.

Required Delegated Scopes

Item.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/{sqlEndpointId}/refreshMetadata

URI Parameters

Name	In	Required	Type	Description
sqlEndpointId	path	True	string (uuid)	The SQL analytics endpoint ID.
workspaceId	path	True	string (uuid)	The workspace ID.

Request Body

Name	Type	Description
recreateTables	boolean	When set to true, this property instructs the system to drop and recreate all tables on the SQL analytics endpoint during the refresh process. Use this option if you need to fully rebuild tables from their source definitions, for example, to resolve inconsistencies or ensure a clean refresh. When combined with `tables`, the sync state reset is scoped only to the specified tables. The default value is false.
tables	TableDefinition[]	When provided, scopes the refresh to only the listed tables. When omitted or empty, all tables are refreshed. Each entry specifies a schema and one or more table names to refresh under that schema. The maximum number of tables that can be synchronized in a single request is 25. Table resolution depends on whether the SQL endpoint's parent item is schema-enabled. For schema-enabled items, tables are resolved using the caller-provided schema. For non-schema-enabled items, all tables resolve under the default schema regardless of the caller-provided schema value; tables under a non-default schema cannot be resolved and will be reported with a `DeltaTableNotFound` error.
timeout	Duration	The request duration before timing out. The default value is 15 minutes.

Responses

Name	Type	Description
200 OK	TableSyncStatuses	Request completed successfully.
202 Accepted		Request accepted, SQL analytics table refresh in progress. 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.

Examples

Refresh all tables for a specified SQL analytics endpoint in a workspace

Refresh selective tables for a specified SQL analytics endpoint in a workspace

Refresh selective tables with recreate tables for a specified SQL analytics endpoint in a workspace

Refresh selective tables with user defined schemas for a specified SQL analytics endpoint in a workspace

Refresh all tables for a specified SQL analytics endpoint in a workspace

Sample request

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/sqlEndpoints/5b218778-e7a5-4d73-8187-f10824047715/refreshMetadata

Sample response

Status code:: 200

{
  "value": [
    {
      "tableName": "Table 1",
      "startDateTime": "2025-08-08T10:31:22.2708973Z",
      "endDateTime": "2025-08-08T10:36:54.9651741Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2025-08-08T10:36:54.9651741Z"
    },
    {
      "tableName": "Table 2",
      "startDateTime": "2025-08-08T10:31:22.2708973Z",
      "endDateTime": "2025-08-08T10:43:02.5329616Z",
      "status": "Failure",
      "error": {
        "errorCode": "AdalRetryException",
        "message": "Couldn't run query. There is a problem with the Microsoft Entra ID token. Have the warehouse owner log in again. If they're unavailable, use the takeover feature."
      },
      "lastSuccessfulSyncDateTime": "2025-08-07T10:44:27.2632648Z"
    },
    {
      "tableName": "Table 3",
      "startDateTime": "2025-08-08T10:31:22.2708973Z",
      "endDateTime": "2025-08-08T10:36:59.9183509Z",
      "status": "NotRun",
      "lastSuccessfulSyncDateTime": "2025-08-06T08:32:53.3890146Z"
    }
  ]
}

Refresh selective tables for a specified SQL analytics endpoint in a workspace

Sample request

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/sqlEndpoints/5b218778-e7a5-4d73-8187-f10824047715/refreshMetadata

{
  "tables": [
    {
      "schema": "dbo",
      "tableNames": [
        "Orders",
        "OrderDetails"
      ]
    },
    {
      "schema": "dbo",
      "tableNames": [
        "DailySummary"
      ]
    }
  ]
}

Sample response

Status code:: 200

{
  "value": [
    {
      "tableName": "Orders",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:25.9651741Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:25.9651741Z"
    },
    {
      "tableName": "OrderDetails",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:26.5329616Z",
      "status": "Failure",
      "error": {
        "errorCode": "DeltaTableNotFound",
        "message": "Delta table 'Tables\\OrderDetails\\_delta_log' not found."
      },
      "lastSuccessfulSyncDateTime": "2026-06-08T10:31:26.5329616Z"
    },
    {
      "tableName": "DailySummary",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:24.9183509Z",
      "status": "NotRun",
      "lastSuccessfulSyncDateTime": "2026-06-08T08:32:53.3890146Z"
    }
  ]
}

Refresh selective tables with recreate tables for a specified SQL analytics endpoint in a workspace

Sample request

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/sqlEndpoints/5b218778-e7a5-4d73-8187-f10824047715/refreshMetadata

{
  "recreateTables": true,
  "tables": [
    {
      "schema": "dbo",
      "tableNames": [
        "Orders",
        "OrderDetails"
      ]
    }
  ]
}

Sample response

Status code:: 200

{
  "value": [
    {
      "tableName": "Orders",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:25.9651741Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:25.9651741Z"
    },
    {
      "tableName": "OrderDetails",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:26.5329616Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:26.5329616Z"
    }
  ]
}

Refresh selective tables with user defined schemas for a specified SQL analytics endpoint in a workspace

Sample request

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/sqlEndpoints/5b218778-e7a5-4d73-8187-f10824047715/refreshMetadata

{
  "tables": [
    {
      "schema": "sales",
      "tableNames": [
        "Orders",
        "OrderDetails"
      ]
    },
    {
      "schema": "analytics",
      "tableNames": [
        "DailySummary"
      ]
    }
  ]
}

Sample response

Status code:: 200

{
  "value": [
    {
      "tableName": "sales.Orders",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:25.9651741Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:25.9651741Z"
    },
    {
      "tableName": "sales.OrderDetails",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:26.5329616Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:26.5329616Z"
    },
    {
      "tableName": "analytics.DailySummary",
      "startDateTime": "2026-06-09T14:31:22.2708973Z",
      "endDateTime": "2026-06-09T14:31:24.9183509Z",
      "status": "Success",
      "lastSuccessfulSyncDateTime": "2026-06-09T14:31:24.9183509Z"
    }
  ]
}

Definitions

Name	Description
Duration	A duration.
ErrorRelatedResource	The error related resource details object.
ErrorResponse	The error response.
ErrorResponseDetails	The error response details.
SqlEndpointRefreshMetadataRequest	The request payload for refreshing a SQL analytics endpoint.
SyncStatus	The status of the synchronization operation. Additional SyncStatus types may be added over time.
TableDefinition	A pair of schema and table names for scoping a selective refresh.
TableSyncStatus	A table synchronization status object.
TableSyncStatuses	A list of table synchronization statuses.
TimeUnit	The unit of time for the duration. Additional duration types may be added over time.

Duration

Object

A duration.

Name	Type	Description
timeUnit	TimeUnit	The unit of time for the duration. Additional duration types may be added over time.
value	number	The number of timeUnits in the duration.

ErrorRelatedResource

Object

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

Object

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.
relatedResource	ErrorRelatedResource	The error related resource details.
requestId	string (uuid)	ID of the request associated with the error.

ErrorResponseDetails

Object

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.
relatedResource	ErrorRelatedResource	The error related resource details.

SqlEndpointRefreshMetadataRequest

Object

The request payload for refreshing a SQL analytics endpoint.

Name	Type	Description
recreateTables	boolean	When set to true, this property instructs the system to drop and recreate all tables on the SQL analytics endpoint during the refresh process. Use this option if you need to fully rebuild tables from their source definitions, for example, to resolve inconsistencies or ensure a clean refresh. When combined with `tables`, the sync state reset is scoped only to the specified tables. The default value is false.
tables	TableDefinition[]	When provided, scopes the refresh to only the listed tables. When omitted or empty, all tables are refreshed. Each entry specifies a schema and one or more table names to refresh under that schema. The maximum number of tables that can be synchronized in a single request is 25. Table resolution depends on whether the SQL endpoint's parent item is schema-enabled. For schema-enabled items, tables are resolved using the caller-provided schema. For non-schema-enabled items, all tables resolve under the default schema regardless of the caller-provided schema value; tables under a non-default schema cannot be resolved and will be reported with a `DeltaTableNotFound` error.
timeout	Duration	The request duration before timing out. The default value is 15 minutes.

SyncStatus

Enumeration

The status of the synchronization operation. Additional SyncStatus types may be added over time.

Value	Description
Success	Indicates a success.
Failure	Indicates a failure.
NotRun	Indicates that the operation did not run.

TableDefinition

Object

A pair of schema and table names for scoping a selective refresh.

Name	Type	Description
schema	string minLength: 1 maxLength: 128	The schema name for table resolution. Must not be a reserved system schema.
tableNames	string[] minLength: 1 maxLength: 128	One or more table names to refresh under the specified schema.

TableSyncStatus

Object

A table synchronization status object.

Name	Type	Description
endDateTime	string (date-time)	The date and time when the table synchronization completed in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
error	ErrorResponseDetails	The error response details
lastSuccessfulSyncDateTime	string (date-time)	The date and time when the table synchronization was successful in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
startDateTime	string (date-time)	The date and time when the table synchronization started in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
status	SyncStatus	Whether the table synchronized without errors.
tableName	string	The name of the table that synchronized. For schema-enabled items, the table name is prefixed with the schema name (e.g., "schema.tableName").

TableSyncStatuses

Object

A list of table synchronization statuses.

Name	Type	Description
value	TableSyncStatus[]	A list of table synchronization statuses.

TimeUnit

Enumeration

The unit of time for the duration. Additional duration types may be added over time.

Value	Description
Seconds	Duration in seconds.
Minutes	Duration in minutes.
Hours	Duration in hours.
Days	Duration in days.