0
# Scripts and Extensions
1

2
Management of KQL scripts for database automation and language extensions for custom query capabilities including Python, R, and other supported languages. This enables advanced analytics scenarios and automated database operations.
3

4
## Capabilities
5

6
### Script Management
7

8
Operations to manage KQL scripts that automate database operations and data processing tasks.
9

10
```python { .api }
11
def get(
12
    resource_group_name: str,
13
    cluster_name: str,
14
    database_name: str,
15
    script_name: str,
16
    **kwargs
17
) -> Script:
18
    """
19
    Get a KQL script in a database.
20
    
21
    Parameters:
22
    - resource_group_name: Name of the resource group
23
    - cluster_name: Name of the Kusto cluster
24
    - database_name: Name of the database
25
    - script_name: Name of the script
26
    
27
    Returns:
28
    Script object with script configuration and content
29
    """
30

31
def begin_create_or_update(
32
    resource_group_name: str,
33
    cluster_name: str,
34
    database_name: str,
35
    script_name: str,
36
    parameters: Script,
37
    **kwargs
38
) -> LROPoller[Script]:
39
    """
40
    Create or update a KQL script in a database.
41
    
42
    Parameters:
43
    - resource_group_name: Name of the resource group
44
    - cluster_name: Name of the Kusto cluster
45
    - database_name: Name of the database
46
    - script_name: Name of the script
47
    - parameters: Script object with configuration and content
48
    
49
    Returns:
50
    LROPoller for the long-running operation returning Script
51
    """
52

53
def begin_update(
54
    resource_group_name: str,
55
    cluster_name: str,
56
    database_name: str,
57
    script_name: str,
58
    parameters: Script,
59
    **kwargs
60
) -> LROPoller[Script]:
61
    """
62
    Update a KQL script in a database.
63
    
64
    Parameters:
65
    - resource_group_name: Name of the resource group
66
    - cluster_name: Name of the Kusto cluster
67
    - database_name: Name of the database
68
    - script_name: Name of the script
69
    - parameters: Script object with updates
70
    
71
    Returns:
72
    LROPoller for the long-running operation returning updated Script
73
    """
74

75
def begin_delete(
76
    resource_group_name: str,
77
    cluster_name: str,
78
    database_name: str,
79
    script_name: str,
80
    **kwargs
81
) -> LROPoller[None]:
82
    """
83
    Delete a KQL script from a database.
84
    
85
    Parameters:
86
    - resource_group_name: Name of the resource group
87
    - cluster_name: Name of the Kusto cluster
88
    - database_name: Name of the database
89
    - script_name: Name of the script
90
    
91
    Returns:
92
    LROPoller for the long-running delete operation
93
    """
94

95
def list_by_database(
96
    resource_group_name: str,
97
    cluster_name: str,
98
    database_name: str,
99
    **kwargs
100
) -> Iterable[Script]:
101
    """
102
    List KQL scripts in a database.
103
    
104
    Parameters:
105
    - resource_group_name: Name of the resource group
106
    - cluster_name: Name of the Kusto cluster
107
    - database_name: Name of the database
108
    
109
    Returns:
110
    Iterable of Script objects
111
    """
112

113
def check_name_availability(
114
    resource_group_name: str,
115
    cluster_name: str,
116
    database_name: str,
117
    script_name: ScriptCheckNameRequest,
118
    **kwargs
119
) -> CheckNameResult:
120
    """
121
    Check if a script name is available in the database.
122
    
123
    Parameters:
124
    - resource_group_name: Name of the resource group
125
    - cluster_name: Name of the Kusto cluster
126
    - database_name: Name of the database
127
    - script_name: ScriptCheckNameRequest with name to validate
128
    
129
    Returns:
130
    CheckNameResult indicating availability
131
    """
132
```
133

134
### Sandbox Custom Images
135

136
Management of custom sandbox images for specialized language extension environments.
137

138
```python { .api }
139
def get(
140
    resource_group_name: str,
141
    cluster_name: str,
142
    sandbox_custom_image_name: str,
143
    **kwargs
144
) -> SandboxCustomImage:
145
    """
146
    Get a sandbox custom image.
147
    
148
    Parameters:
149
    - resource_group_name: Name of the resource group
150
    - cluster_name: Name of the Kusto cluster
151
    - sandbox_custom_image_name: Name of the sandbox custom image
152
    
153
    Returns:
154
    SandboxCustomImage object
155
    """
156

157
def begin_create_or_update(
158
    resource_group_name: str,
159
    cluster_name: str,
160
    sandbox_custom_image_name: str,
161
    parameters: SandboxCustomImage,
162
    **kwargs
163
) -> LROPoller[SandboxCustomImage]:
164
    """
165
    Create or update a sandbox custom image.
166
    
167
    Parameters:
168
    - resource_group_name: Name of the resource group
169
    - cluster_name: Name of the Kusto cluster
170
    - sandbox_custom_image_name: Name of the sandbox custom image
171
    - parameters: SandboxCustomImage with configuration
172
    
173
    Returns:
174
    LROPoller for the long-running operation returning SandboxCustomImage
175
    """
176

177
def begin_update(
178
    resource_group_name: str,
179
    cluster_name: str,
180
    sandbox_custom_image_name: str,
181
    parameters: SandboxCustomImage,
182
    **kwargs
183
) -> LROPoller[SandboxCustomImage]:
184
    """
185
    Update a sandbox custom image.
186
    
187
    Parameters:
188
    - resource_group_name: Name of the resource group
189
    - cluster_name: Name of the Kusto cluster
190
    - sandbox_custom_image_name: Name of the sandbox custom image
191
    - parameters: SandboxCustomImage with updates
192
    
193
    Returns:
194
    LROPoller for the long-running operation returning updated SandboxCustomImage
195
    """
196

197
def begin_delete(
198
    resource_group_name: str,
199
    cluster_name: str,
200
    sandbox_custom_image_name: str,
201
    **kwargs
202
) -> LROPoller[None]:
203
    """
204
    Delete a sandbox custom image.
205
    
206
    Parameters:
207
    - resource_group_name: Name of the resource group
208
    - cluster_name: Name of the Kusto cluster
209
    - sandbox_custom_image_name: Name of the sandbox custom image
210
    
211
    Returns:
212
    LROPoller for the long-running delete operation
213
    """
214

215
def list_by_cluster(
216
    resource_group_name: str,
217
    cluster_name: str,
218
    **kwargs
219
) -> Iterable[SandboxCustomImage]:
220
    """
221
    List sandbox custom images for a cluster.
222
    
223
    Parameters:
224
    - resource_group_name: Name of the resource group
225
    - cluster_name: Name of the Kusto cluster
226
    
227
    Returns:
228
    Iterable of SandboxCustomImage objects
229
    """
230

231
def check_name_availability(
232
    resource_group_name: str,
233
    cluster_name: str,
234
    sandbox_custom_image_name: SandboxCustomImagesCheckNameRequest,
235
    **kwargs
236
) -> CheckNameResult:
237
    """
238
    Check if a sandbox custom image name is available.
239
    
240
    Parameters:
241
    - resource_group_name: Name of the resource group
242
    - cluster_name: Name of the Kusto cluster
243
    - sandbox_custom_image_name: CheckNameRequest with name to validate
244
    
245
    Returns:
246
    CheckNameResult indicating availability
247
    """
248
```
249

250
## Usage Examples
251

252
### Creating a Database Setup Script
253

254
```python
255
from azure.mgmt.kusto.models import Script, ScriptLevel
256

257
# Create KQL script for database setup
258
setup_script = Script(
259
    script_url="https://mystorageaccount.blob.core.windows.net/scripts/setup.kql",
260
    script_url_sas_token="?sv=2020-08-04&ss=b&srt=sco&sp=r&se=2024-12-31T23:59:59Z&sig=...",
261
    force_update_tag="v1.0",
262
    continue_on_errors=False
263
)
264

265
# Create the script
266
poller = client.scripts.begin_create_or_update(
267
    resource_group_name="my-resource-group",
268
    cluster_name="my-cluster",
269
    database_name="my-database",
270
    script_name="database-setup",
271
    parameters=setup_script
272
)
273

274
script = poller.result()
275
print(f"Script created: {script.name}")
276
```
277

278
### Creating a Data Processing Script
279

280
```python
281
from azure.mgmt.kusto.models import Script
282

283
# Create KQL script for data processing
284
processing_script = Script(
285
    script_content=""".create table ProcessedData (
286
        Timestamp: datetime,
287
        UserId: string,
288
        EventType: string,
289
        Value: real
290
    )
291

292
    .create table ProcessedData ingestion json mapping "ProcessedDataMapping" @'[
293
        {"column":"Timestamp","path":"$.timestamp","datatype":"datetime"},
294
        {"column":"UserId","path":"$.userId","datatype":"string"},
295
        {"column":"EventType","path":"$.eventType","datatype":"string"},
296
        {"column":"Value","path":"$.value","datatype":"real"}
297
    ]'
298

299
    .create function ProcessEvents() {
300
        RawEvents
301
        | where Timestamp > ago(1d)
302
        | extend ProcessedValue = Value * 1.1
303
        | project Timestamp, UserId, EventType, ProcessedValue
304
    }""",
305
    force_update_tag="v2.0",
306
    continue_on_errors=True
307
)
308

309
# Create the script
310
poller = client.scripts.begin_create_or_update(
311
    resource_group_name="my-resource-group",
312
    cluster_name="my-cluster",
313
    database_name="my-database",
314
    script_name="data-processing",
315
    parameters=processing_script
316
)
317

318
script = poller.result()
319
print(f"Data processing script created: {script.name}")
320
```
321

322
### Creating a Custom Sandbox Image
323

324
```python
325
from azure.mgmt.kusto.models import SandboxCustomImage, Language
326

327
# Create custom sandbox image for Python environment
328
custom_image = SandboxCustomImage(
329
    language=Language.PYTHON,
330
    language_version="3.9",
331
    package_requirements="""\
332
numpy==1.21.0
333
pandas==1.3.0
334
scikit-learn==0.24.2
335
matplotlib==3.4.2
336
seaborn==0.11.1
337
""",
338
    requirements_file_content="""\
339
# Additional Python packages for data science
340
numpy>=1.21.0
341
pandas>=1.3.0
342
scikit-learn>=0.24.2
343
matplotlib>=3.4.2
344
seaborn>=0.11.1
345
plotly>=5.0.0
346
""",
347
    dependencies_file_content="""\
348
# System dependencies
349
libgomp1
350
libatlas-base-dev
351
"""
352
)
353

354
# Create the custom image
355
poller = client.sandbox_custom_images.begin_create_or_update(
356
    resource_group_name="my-resource-group",
357
    cluster_name="my-cluster",
358
    sandbox_custom_image_name="python-datascience",
359
    parameters=custom_image
360
)
361

362
image = poller.result()
363
print(f"Custom sandbox image created: {image.name}")
364
```
365

366
### Managing Language Extensions at Cluster Level
367

368
```python
369
from azure.mgmt.kusto.models import (
370
    LanguageExtensionsList,
371
    LanguageExtension,
372
    LanguageExtensionName,
373
    LanguageExtensionImageName
374
)
375

376
# Add Python language extension
377
python_extension = LanguageExtension(
378
    language_extension_name=LanguageExtensionName.PYTHON,
379
    language_extension_image_name=LanguageExtensionImageName.PYTHON3_6_5,
380
    language_extension_custom_image_name="python-datascience"  # Use custom image
381
)
382

383
extensions_to_add = LanguageExtensionsList(
384
    value=[python_extension]
385
)
386

387
# Add language extension to cluster
388
poller = client.clusters.begin_add_language_extensions(
389
    resource_group_name="my-resource-group",
390
    cluster_name="my-cluster",
391
    language_extensions_to_add=extensions_to_add
392
)
393

394
poller.result()
395
print("Python language extension added to cluster")
396

397
# List current language extensions
398
extensions = list(client.clusters.list_language_extensions(
399
    resource_group_name="my-resource-group",
400
    cluster_name="my-cluster"
401
))
402

403
for ext in extensions:
404
    print(f"Extension: {ext.language_extension_name} - Image: {ext.language_extension_image_name}")
405
```
406

407
## Key Types
408

409
```python { .api }
410
class Script:
411
    """Represents a KQL script resource."""
412
    # Read-only properties
413
    id: str  # Resource ID
414
    name: str  # Script name
415
    type: str  # Resource type
416
    provisioning_state: ProvisioningState  # Provisioning state
417
    
418
    # Script configuration
419
    script_url: str  # URL to script file
420
    script_url_sas_token: str  # SAS token for script URL access
421
    script_content: str  # Inline script content (alternative to URL)
422
    force_update_tag: str  # Tag to force script update
423
    continue_on_errors: bool  # Whether to continue execution on errors
424

425
class SandboxCustomImage:
426
    """Represents a custom sandbox image for language extensions."""
427
    # Read-only properties
428
    id: str  # Resource ID
429
    name: str  # Image name
430
    type: str  # Resource type
431
    provisioning_state: ProvisioningState  # Provisioning state
432
    
433
    # Image configuration
434
    language: Language  # Programming language
435
    language_version: str  # Language version
436
    package_requirements: str  # Package requirements file content
437
    requirements_file_content: str  # Requirements file content
438
    dependencies_file_content: str  # System dependencies content
439

440
class LanguageExtension:
441
    """Represents a language extension configuration."""
442
    language_extension_name: LanguageExtensionName  # Extension name
443
    language_extension_image_name: LanguageExtensionImageName  # Image name
444
    language_extension_custom_image_name: str  # Custom image name
445

446
class LanguageExtensionsList:
447
    """List of language extensions."""
448
    value: List[LanguageExtension]  # Language extensions
449

450
class ScriptCheckNameRequest:
451
    """Request to check script name availability."""
452
    name: str  # Name to check
453
    type: str  # Resource type
454

455
class SandboxCustomImagesCheckNameRequest:
456
    """Request to check sandbox custom image name availability."""
457
    name: str  # Name to check
458
    type: str  # Resource type
459

460
from enum import Enum
461

462
class ScriptLevel(str, Enum):
463
    """Script level values."""
464
    DATABASE = "Database"
465
    CLUSTER = "Cluster"
466

467
class Language(str, Enum):
468
    """Programming language values."""
469
    PYTHON = "Python"
470
    R = "R"
471

472
class LanguageExtensionName(str, Enum):
473
    """Language extension name values."""
474
    PYTHON = "PYTHON"
475
    R = "R"
476

477
class LanguageExtensionImageName(str, Enum):
478
    """Language extension image name values."""
479
    PYTHON3_6_5 = "Python3_6_5"
480
    PYTHON3_9_7 = "Python3_9_7"
481
    PYTHON3_10_8 = "Python3_10_8"
482
    R3_4_4 = "R3_4_4"
483
    R4_0_5 = "R4_0_5"
484
    R4_2_5 = "R4_2_5"
485
```
486

487
## Script Content Examples
488

489
### Table Creation Script
490

491
```kql
492
// Create tables for event processing
493
.create table Events (
494
    Timestamp: datetime,
495
    UserId: string,
496
    EventType: string,
497
    Properties: dynamic
498
)
499

500
.create table EventsSummary (
501
    Date: datetime,
502
    EventType: string,
503
    Count: long,
504
    UniqueUsers: long
505
)
506

507
// Create ingestion mapping
508
.create table Events ingestion json mapping "EventsMapping" @'[
509
    {"column":"Timestamp","path":"$.timestamp","datatype":"datetime"},
510
    {"column":"UserId","path":"$.userId","datatype":"string"},
511
    {"column":"EventType","path":"$.eventType","datatype":"string"},
512
    {"column":"Properties","path":"$.properties","datatype":"dynamic"}
513
]'
514
```
515

516
### Function Creation Script
517

518
```kql
519
// Create function for event aggregation
520
.create function EventsDailySummary() {
521
    Events
522
    | where Timestamp >= startofday(now(-1d)) and Timestamp < startofday(now())
523
    | summarize 
524
        Count = count(),
525
        UniqueUsers = dcount(UserId)
526
        by EventType, Date = bin(Timestamp, 1d)
527
    | order by Date desc, EventType asc
528
}
529

530
// Create materialized view for real-time aggregation
531
.create materialized-view EventsHourlySummary on table Events {
532
    Events
533
    | summarize 
534
        Count = count(),
535
        UniqueUsers = dcount(UserId),
536
        LastEventTime = max(Timestamp)
537
        by EventType, Hour = bin(Timestamp, 1h)
538
}
539
```
540

541
### Data Retention Policy Script
542

543
```kql
544
// Set retention policies
545
.alter table Events policy retention softdelete = 30d recoverability = disabled
546

547
.alter table EventsSummary policy retention softdelete = 365d
548

549
// Set ingestion batching policy
550
.alter table Events policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:01:00", "MaximumNumberOfItems": 1000}'
551

552
// Enable streaming ingestion
553
.alter table Events policy streamingingestion enable
554
```