Items - Create KQL Database

  • Reference
Service:
KQLDatabase
API Version:
v1

Creates a KQL database in the specified workspace.
This API supports long running operations (LRO).

Permissions

The caller must have contributor or higher workspace role.

Required Delegated Scopes

KQLDatabase.ReadWrite.All or Item.ReadWrite.All

Limitations

Microsoft Entra supported identities

This API supports the Microsoft identities listed in this section.

Identity Support
User Yes
Service principal Yes
Managed identities Yes

Interface

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/kqlDatabases

URI Parameters

Name In Required Type Description
workspaceId
 path True

string

uuid

The workspace ID.

Request Body

Name Required Type Description
creationPayload True KQLDatabaseCreationPayload:

The KQL database creation payload.
displayName True

string

The KQL database display name. The database name can contain alphanumeric characters, underscores, periods, and hyphens. Special characters aren't supported.
description

string

The KQL database description. Maximum length is 256 characters.

Responses

Name Type Description
202 Accepted

Request accepted, KQL database provisioning in progress

Headers

  • Location: string
  • x-ms-operation-id: string
  • Retry-After: integer
Other Status Codes

ErrorResponse

Common error codes:

  • InvalidItemType - Item type is invalid

  • ItemDisplayNameAlreadyInUse - Item display name is already used

  • CorruptedPayload - The provided payload is corrupted.

Examples

Create a ReadWrite KQL database example
Create a Shortcut KQL database to source Azure Data Explorer cluster example
Create a Shortcut KQL database to source Azure Data Explorer cluster with invitation token example
Create a Shortcut KQL database to source KQL database example

Create a ReadWrite KQL database example

Sample request

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/kqlDatabases

{
  "displayName": "KQLDatabase_1",
  "description": "A KQL database description.",
  "creationPayload": {
    "databaseType": "ReadWrite",
    "parentEventhouseItemId": "5b218778-e7a5-4d73-8187-f10824047836"
  }
}

Sample response

Status code:
202 
Location: https://api.fabric.microsoft.com/v1/operations/0acd697c-1550-43cd-b998-91bfbfbd47c6
x-ms-operation-id: 0acd697c-1550-43cd-b998-91bfbfbd47c6
Retry-After: 30

Create a Shortcut KQL database to source Azure Data Explorer cluster example

Sample request

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/kqlDatabases

{
  "displayName": "KQLDatabase_1",
  "description": "A KQL database description.",
  "creationPayload": {
    "databaseType": "Shortcut",
    "parentEventhouseItemId": "5b218778-e7a5-4d73-8187-f10824047836",
    "sourceClusterUri": "https://adxcluster.westus.kusto.windows.net",
    "sourceDatabaseName": "MyDatabase"
  }
}

Sample response

Status code:
202 
Location: https://api.fabric.microsoft.com/v1/operations/0acd697c-1550-43cd-b998-91bfbfbd47c6
x-ms-operation-id: 0acd697c-1550-43cd-b998-91bfbfbd47c6
Retry-After: 30

Create a Shortcut KQL database to source Azure Data Explorer cluster with invitation token example

Sample request

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/kqlDatabases

{
  "displayName": "KQLDatabase_1",
  "description": "A KQL database description.",
  "creationPayload": {
    "databaseType": "Shortcut",
    "parentEventhouseItemId": "5b218778-e7a5-4d73-8187-f10824047836",
    "invitationToken": "eyJ0eXAiOiJKVInvitationToken"
  }
}

Sample response

Status code:
202 
Location: https://api.fabric.microsoft.com/v1/operations/0acd697c-1550-43cd-b998-91bfbfbd47c6
x-ms-operation-id: 0acd697c-1550-43cd-b998-91bfbfbd47c6
Retry-After: 30

Create a Shortcut KQL database to source KQL database example

Sample request

POST https://api.fabric.microsoft.com/v1/workspaces/cfafbeb1-8037-4d0c-896e-a46fb27ff229/kqlDatabases

{
  "displayName": "KQLDatabase_1",
  "description": "A KQL database description.",
  "creationPayload": {
    "databaseType": "Shortcut",
    "parentEventhouseItemId": "5b218778-e7a5-4d73-8187-f10824047836",
    "sourceDatabaseName": "ac542109-abd1-4ee3-aec5-86282c01ee24"
  }
}

Sample response

Status code:
202 
Location: https://api.fabric.microsoft.com/v1/operations/0acd697c-1550-43cd-b998-91bfbfbd47c6
x-ms-operation-id: 0acd697c-1550-43cd-b998-91bfbfbd47c6
Retry-After: 30

Definitions

Name Description
CreateKQLDatabaseRequest

Create KQL database request payload.
ErrorRelatedResource

The error related resource details object.
ErrorResponse

The error response.
ErrorResponseDetails

The error response details.
KqlDatabaseType

The type of the database.
ReadWriteDatabaseCreationPayload

ReadWrite KQL database item creation payload
ShortcutDatabaseCreationPayload

Shortcut KQL database item creation payload

CreateKQLDatabaseRequest

Create KQL database request payload.

Name Type Description
creationPayload KQLDatabaseCreationPayload:

The KQL database creation payload.
description

string

The KQL database description. Maximum length is 256 characters.
displayName

string

The KQL database display name. The database name can contain alphanumeric characters, underscores, periods, and hyphens. Special characters aren't supported.

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.
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

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.
relatedResource

ErrorRelatedResource

The error related resource details.

KqlDatabaseType

The type of the database.

Name Type Description
ReadWrite

string

Allows read and write operations on the database.
Shortcut

string

A shortcut is an embedded reference allowing read only operations on a source database. The source can be in the same or different tenants, either in an Azure Data Explorer cluster or a Fabric Eventhouse.

ReadWriteDatabaseCreationPayload

ReadWrite KQL database item creation payload

Name Type Description
databaseType string:

ReadWrite

The type of the KQL database
parentEventhouseItemId

string

Parent eventhouse item ID.

ShortcutDatabaseCreationPayload

Shortcut KQL database item creation payload

Name Type Description
databaseType string:

Shortcut

The type of the KQL database
invitationToken

string

Invitation token to follow the source database
parentEventhouseItemId

string

Parent eventhouse item ID.
sourceClusterUri

string

The URI of the source Eventhouse or Azure Data Explorer cluster
sourceDatabaseName

string

The name of the database to follow in the source Eventhouse or Azure Data Explorer cluster.