diff --git a/.vscode/settings.json b/.vscode/settings.json index 33f6af4..fac3859 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -33,6 +33,7 @@ "Entra", "Kusto", "multijson", + "norequesttimeout", "proga", "scsv", "singlejson", diff --git a/docs/en-US/Invoke-KustoQuery.md b/docs/en-US/Invoke-KustoQuery.md index 6fb2f9d..0b95b52 100644 --- a/docs/en-US/Invoke-KustoQuery.md +++ b/docs/en-US/Invoke-KustoQuery.md @@ -157,3 +157,5 @@ By default, this cmdlet outputs `PSObject`. [Kusto Query Language (KQL)](https://learn.microsoft.com/en-us/kusto/query/?view=microsoft-fabric) [T-SQL](https://learn.microsoft.com/en-us/kusto/query/t-sql?view=microsoft-fabric) + +[Send T-SQL queries via the REST API](https://learn.microsoft.com/en-us/kusto/api/rest/t-sql?view=microsoft-fabric) diff --git a/docs/en-US/New-KustoClientRequestProperties.md b/docs/en-US/New-KustoClientRequestProperties.md index c8285df..e64e4d3 100644 --- a/docs/en-US/New-KustoClientRequestProperties.md +++ b/docs/en-US/New-KustoClientRequestProperties.md @@ -9,7 +9,7 @@ schema: 2.0.0 ## SYNOPSIS -{{ Fill in the Synopsis }} +Creates a `ClientRequestProperties` object. ## SYNTAX @@ -27,23 +27,50 @@ New-KustoClientRequestProperties ## DESCRIPTION -{{ Fill in the Description }} +The `New-KustoClientRequestProperties` cmdlet can be used to create a new `ClientRequestProperties` object +to manage the interaction between client and service. This object can be later on passed as argument to the request cmdlets: [`Invoke-KustoControlCommand`](Invoke-KustoControlCommand.md) and [`Invoke-KustoQuery`](Invoke-KustoQuery.md). + +The object contains the following information: + +- [Request properties](https://learn.microsoft.com/en-us/kusto/api/netfx/client-request-properties?view=microsoft-fabric#request-properties): A mapping of specific options for customizing request behavior. +- [Query parameters](https://learn.microsoft.com/en-us/kusto/api/netfx/client-request-properties?view=microsoft-fabric#query-parameters): A mapping of user-declared parameters that allow for secure query customization. +- [Named properties](https://learn.microsoft.com/en-us/kusto/api/netfx/client-request-properties?view=microsoft-fabric#named-properties): Client request ID, application details, and user data, primarily used for debugging and tracing. ## EXAMPLES -### Example 1 +### Example 1: Run a KQL Query with specified request properties + +```powershell +$requestProps = New-KustoClientRequestProperties -NoTruncation -ServerTimeout '00:05:00' +Invoke-KustoQuery 'myTable | project fooProp, barProp' -RequestProperties $requestProps +``` + +This example demonstrates how you can specify request properties for your query. + +- In this case `-NoTruncation` is particularly useful to overcome the 500k row limit on your query. +- `-ServerTimeout '00:05:00'` allows the query to run for at least 5 minutes before timing out. + +### Example 2: Create a new `ClientRequestProperties` object with supported request properties ```powershell -PS C:\> {{ Add example code here }} +$requestProps = New-KustoClientRequestProperties -Options @{ + query_language = 'sql' + request_app_name = 'myApp' + norequesttimeout = $true +} ``` -{{ Add example description here }} +> [!TIP] +> +> Out of the supported request properties, this cmdlet only offers `-NoTruncation` (`notruncation`) and `-ServerTimeout` (`servertimeout`). +> The `-Options` parameters offers adding extra options to your request that aren't by default available as a Parameter. +> See [__Supported request properties__](https://learn.microsoft.com/en-us/kusto/api/rest/request-properties?view=microsoft-fabric#supported-request-properties) for the additional options. ## PARAMETERS ### -Application -{{ Fill Application Description }} +The name of the client application that makes the request. This value is used for tracing. ```yaml Type: String @@ -59,7 +86,7 @@ Accept wildcard characters: False ### -ClientRequestId -{{ Fill ClientRequestId Description }} +An ID used to identify the request. This specification is helpful for debugging and may be required for specific scenarios like query cancellation. ```yaml Type: String @@ -75,7 +102,7 @@ Accept wildcard characters: False ### -NoTruncation -{{ Fill NoTruncation Description }} +Disables truncation of query results returned to the caller. ```yaml Type: SwitchParameter @@ -91,7 +118,7 @@ Accept wildcard characters: False ### -Options -{{ Fill Options Description }} +Specifies a Hashtable of additional [Supported request properties](https://learn.microsoft.com/en-us/kusto/api/rest/request-properties?view=microsoft-fabric#supported-request-properties) that aren't by default available as a Parameter. ```yaml Type: Hashtable @@ -107,7 +134,7 @@ Accept wildcard characters: False ### -Parameters -{{ Fill Parameters Description }} +Specifies a Hashtable of [query parameters declaration statement](https://learn.microsoft.com/en-us/kusto/query/query-parameters-statement?view=microsoft-fabric) that are used to declare parameters for a Kusto Query Language (KQL) query. ```yaml Type: Hashtable @@ -123,7 +150,7 @@ Accept wildcard characters: False ### -ServerTimeout -{{ Fill ServerTimeout Description }} +Overrides the default request timeout. ```yaml Type: TimeSpan @@ -139,7 +166,7 @@ Accept wildcard characters: False ### -User -{{ Fill User Description }} +The identity of the user that makes the request. This value is used for tracing. ```yaml Type: String @@ -153,22 +180,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -ProgressAction - -{{ Fill ProgressAction Description }} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters This cmdlet supports the common parameters. @@ -185,3 +196,9 @@ For more information, see [about_CommonParameters](http://go.microsoft.com/fwlin ## NOTES ## RELATED LINKS + +[Kusto Data ClientRequestProperties class](https://learn.microsoft.com/en-us/kusto/api/netfx/client-request-properties?view=microsoft-fabric) + +[Query parameters declaration statement](https://learn.microsoft.com/en-us/kusto/query/query-parameters-statement?view=microsoft-fabric) + +[Request properties](https://learn.microsoft.com/en-us/kusto/api/rest/request-properties?view=microsoft-fabric) diff --git a/src/PowerShellKusto/Commands/NewKustoClientRequestPropertiesCommand.cs b/src/PowerShellKusto/Commands/NewKustoClientRequestPropertiesCommand.cs index a4c6fca..31bb967 100644 --- a/src/PowerShellKusto/Commands/NewKustoClientRequestPropertiesCommand.cs +++ b/src/PowerShellKusto/Commands/NewKustoClientRequestPropertiesCommand.cs @@ -34,7 +34,7 @@ public sealed class NewKustoClientRequestPropertiesCommand : PSCmdlet [Parameter] [ValidateTimespan] - public TimeSpan ServerTimeout { get; set; } = TimeSpan.FromSeconds(60); + public TimeSpan? ServerTimeout { get; set; } protected override void EndProcessing() { @@ -60,8 +60,16 @@ protected override void EndProcessing() } } - properties.SetOption(ClientRequestProperties.OptionNoTruncation, NoTruncation); - properties.SetOption(ClientRequestProperties.OptionServerTimeout, ServerTimeout); + if (ServerTimeout is not null) + { + properties.SetOption(ClientRequestProperties.OptionServerTimeout, ServerTimeout); + } + + if (NoTruncation) + { + properties.SetOption(ClientRequestProperties.OptionNoTruncation, NoTruncation); + } + WriteObject(properties); } }