Request classification policy
Applies to: ✅ Microsoft Fabric ✅ Azure Data Explorer
The classification process assigns incoming requests to a workload group, based on the characteristics of the requests. Tailor the classification logic by writing a user-defined function, as part of a cluster-level request classification policy.
The classification process assigns incoming requests to a workload group, based on the characteristics of the requests. Tailor the classification logic by writing a user-defined function, as part of a eventhouse-level request classification policy.
In the absence of an enabled request classification policy, all requests are classified into the default
workload group.
Policy object
The policy has the following properties:
IsEnabled
:bool
- Indicates if the policy is enabled or not.ClassificationFunction
:string
- The body of the function to use for classifying requests.
Classification function
The classification of incoming requests is based on a user-defined function. The results of the function are used to classify requests into existing workload groups.
The user-defined function has the following characteristics and behaviors:
- If
IsEnabled
is set totrue
in the policy, the user-defined function is evaluated for every new request. - The user-defined function gives workload group context for the request for the full lifetime of the request.
- The request is given the
default
workload group context in the following situations:- The user-defined function returns an empty string,
default
, or the name of non-existent workload group. - The function fails for any reason.
- The user-defined function returns an empty string,
- Only one user-defined function can be designated at any given time.
Important
The request classification function will be evaluated for each request that runs on the cluster. It is recommended to keep it as lightweight as possible, and not include heavy computations in it. For example, avoid having to evaluate many regular expressions as part of its execution.
Important
The request classification function will be evaluated for each request that runs on the eventhouse. It is recommended to keep it as lightweight as possible, and not include heavy computations in it. For example, avoid having to evaluate many regular expressions as part of its execution.
Requirements and limitations
A classification function:
Must return a single scalar value of type
string
, that is the name of the workload group to assign the request to.Must not reference any other entity (database, table, or function).
- Specifically - it may not use the following functions and operators:
cluster()
database()
table()
external_table()
externaldata
- Specifically - it may not use the following functions and operators:
Has access to a special
dynamic
symbol, a property-bag namedrequest_properties
, with the following properties:Name Type Description Examples current_database
string
The name of the request database. "MyDatabase"
current_application
string
The name of the application that sent the request. "Kusto.Explorer"
,"KusWeb"
current_principal
string
The fully qualified name of the principal identity that sent the request. "aaduser=1793eb1f-4a18-418c-be4c-728e310c86d3;83af1c0e-8c6d-4f09-b249-c67a2e8fda65"
query_consistency
string
For queries: the consistency of the query - strongconsistency
orweakconsistency
. This property can be set by the caller as part of the request's request properties: The client request property to set is:queryconsistency
."strongconsistency"
,"weakconsistency"
request_description
string
Custom text that the author of the request can include. The text can be set by the caller as part of the request's Client request properties: The client request property to set is: request_description
."Some custom description"
; automatically populated for dashboards:"dashboard:{dashboard_id};version:{version};sourceId:{source_id};sourceType:{tile/parameter}"
request_text
string
The obfuscated text of the request. Obfuscated string literals included in the query text are replaced by multiple of star ( *
) characters. Note: only the leading 65,536 characters of the request text are evaluated.".show version"
request_type
string
The type of the request - Command
orQuery
."Command"
,"Query"
Note
Setting the aforementioned request options using set
statements does not allow classification by them. The options need to be set in the client request properties object.
Examples
A single workload group
iff(request_properties.current_application == "Kusto.Explorer" and request_properties.request_type == "Query",
"Ad-hoc queries",
"default")
Multiple workload groups
case(current_principal_is_member_of('aadgroup=somesecuritygroup@contoso.com'), "First workload group",
request_properties.current_database == "MyDatabase" and request_properties.current_principal has 'aadapp=', "Second workload group",
request_properties.current_application == "Kusto.Explorer" and request_properties.request_type == "Query", "Third workload group",
request_properties.current_application == "Kusto.Explorer", "Third workload group",
request_properties.current_application == "KustoQueryRunner", "Fourth workload group",
request_properties.request_description == "this is a test", "Fifth workload group",
hourofday(now()) between (17 .. 23), "Sixth workload group",
"default")
Management commands
Use the following management commands to manage a cluster's request classification policy.
Command | Description |
---|---|
.alter cluster request classification policy |
Alters cluster's request classification policy |
.alter-merge cluster request classification policy |
Enables or disables a cluster's request classification policy |
.delete cluster request classification policy |
Deletes the cluster's request classification policy |
.show cluster request classification policy |
Shows the cluster's request classification policy |
Use the following management commands to manage an eventhouse's request classification policy.
Command | Description |
---|---|
.alter cluster request classification policy |
Alters eventhouse's request classification policy |
.alter-merge cluster request classification policy |
Enables or disables a eventhouse's request classification policy |
.delete cluster request classification policy |
Deletes the eventhouse's request classification policy |
.show cluster request classification policy |
Shows the cluster's request classification policy |