Kusto CLIKusto CLI

Kusto.Cli 是一个命令行实用工具,用于将请求发送到 Kusto 并显示结果。Kusto.Cli is a command-line utility that is used to send requests to Kusto, and display the results. 它可以采用以下几种模式运行:It can run in one of several modes:

  • REPL 模式:用户输入查询和命令后,此工具将显示结果,然后等待下一个用户查询/命令。REPL mode: The user enters queries and commands, and the tool displays the results, then awaits the next user query/command. (“REPL”代表“read/eval/print/loop”,即读取/求值/打印/循环。)("REPL" stands for "read/eval/print/loop".)

  • 执行模式:用户输入一个或多个查询和命令以作为命令行参数运行。Execute mode: The user enters one or more queries and commands to run as command-line arguments. 参数会按顺序自动运行,结果将输出到控制台。The arguments are automatically run in sequence, and their results output to the console. (可选)在所有输入查询和命令运行后,此工具将进入 REPL 模式。Optionally, after all the input queries and commands have run, the tool goes into REPL mode.

  • 脚本模式:与执行模式类似,但使用的是通过“脚本”文件指定的查询和命令。Script mode: Similar to execute mode, but with the queries and commands specified through a "script" file.

Kusto.Cli 主要用于针对通常需要编写代码的 Kusto 服务自动执行任务。Kusto.Cli is primarily provided for automating tasks against a Kusto service that normally requires writing code. 例如,C# 程序或 PowerShell 脚本。For example, a C# program or a PowerShell script.

获取工具Get the tool

Kusto.Cli 是 NuGet 包 Microsoft.Azure.Kusto.Tools 的一部分,可以下载Kusto.Cli is part of the NuGet package Microsoft.Azure.Kusto.Tools that you can download. 下载后,将包的 tools 文件夹提取到目标文件夹。Once downloaded, extract the package's tools folder to the target folder. 不需要进行其他安装,因为它是 xcopy 可安装的。No additional installation is required since it's xcopy-installable.

运行工具Run the tool

Kusto.Cli 至少需要一个命令行参数才能运行。Kusto.Cli requires at least one command-line argument to run. 通常,该参数是该工具应连接到的 Kusto 服务的连接字符串。Usually, that argument is the connection string to the Kusto service that the tool should connect to. 有关详细信息,请参阅 Kusto 连接字符串For more information, see Kusto connection strings. 如果不使用命令行参数来运行工具,而是使用未知参数集或使用 /help 开关,控制台上将显示一条帮助消息。If you run the tool without command-line arguments, with an unknown set of arguments, or with the /help switch, a help message will display on the console.

例如,使用以下命令运行 Kusto.Cli。For example, use the following command to run Kusto.Cli. 命令将连接到 help Kusto 服务,并将数据库上下文设置为 Samples 数据库:The command will connect to the help Kusto service, and set the database context to the Samples database:

Kusto.Cli.exe "https://help.kusto.chinacloudapi.cn/Samples;Fed=true"

备注

使用双引号将连接字符串括起来,防止 shell 应用程序(例如 PowerShell)错误地解释分号 (;) 和类似的字符。Use double-quotes around the connection string to prevent shell applications such as PowerShell from mis-interpreting the semicolon (;) and similar characters.

命令行参数Command-line arguments

Kusto.Cli.exe ConnectionString [Switches] Kusto.Cli.exe ConnectionString [Switches]

ConnectionStringConnectionString

  • Kusto 连接字符串,可保存所有 Kusto 连接信息。The Kusto connection string that holds all the Kusto connection information. 默认为 net.tcp://localhost/NetDefaultDBDefaults to net.tcp://localhost/NetDefaultDB.

-execute:QueryOrCommand-execute:QueryOrCommand

  • 如果已指定,则在执行模式下运行 Kusto.Cli,并且会运行指定的查询或命令。If specified, runs Kusto.Cli in execute mode and the specified query or command is run. 此开关可以重复,查询/命令会按出现的顺序运行。This switch can repeat, and the queries/commands are run sequentially in order of appearance. 此开关不能与 -script-scriptml一起使用。This switch can't be used together with -script or -scriptml.

-keepRunning:EnableKeepRunning-keepRunning:EnableKeepRunning

  • 如果指定为 truefalse,在处理完所有 -script-execute 值后,它将启用或禁用 REPL 模式。If specified, as either true or false, it enables or disables REPL mode after all -script or -execute values have been processed.

-script:ScriptFile-script:ScriptFile

  • 如果已指定,则在脚本模式下运行 Kusto.Cli。If specified, runs Kusto.Cli in script mode. 将加载指定的脚本文件,并按顺序运行其中的查询或命令。The specified script file is loaded and the queries or commands in it are run sequentially. 当行以 &&& 组合结尾时除外,换行符用于分隔查询/命令,如下所述。Newlines are used to delimit queries/commands, except when lines end with a & or && combination, as explained below. 此开关不能与 -execute 一起使用。This switch can't be used together with -execute.

-scriptml:ScriptFile-scriptml:ScriptFile

  • 如果已指定,则在脚本模式下运行 Kusto.Cli。If specified, runs Kusto.Cli in script mode. 将加载指定的脚本文件,并按顺序运行其中的查询或命令。The specified script file is loaded and the queries or commands in it are run sequentially. 整个脚本文件会被视为单个查询或命令。The entire script file is considered a single query or command. 此开关不能与 -execute 一起使用。This switch can't be used together with -execute.

-echo:EnableEchoMode-echo:EnableEchoMode

  • 如果指定为 truefalse,它将启用或禁用回显模式。If specified, as either true or false, it enables or disables echo mode. 启用回显模式时,将在输出中重复每个查询或命令。When echo mode is enabled, every query or command is repeated in the output.

-transcript:TranscriptFile-transcript:TranscriptFile

  • 如果已指定,则将程序输出写入 TranscriptFile。If specified, writes program output to TranscriptFile.

-logToConsole:EnableLogToConsole-logToConsole:EnableLogToConsole

  • 如果指定为 truefalse,它将启用或禁用在控制台上显示程序输出。If specified, as either true or false, it enables or disables displaying the program output on the console.

-lineMode:EnableLineMode-lineMode:EnableLineMode

  • 如果已指定,则在设置为 true 时的默认行输入模式和设置为 false 时的块输入模式之间切换。If specified, switches between the default line input mode, when set to true, and the block input mode, when set to false. 有关这两种模式的说明,请参阅下文,这两种模式确定了处理换行符的方式。See below for an explanation of these two modes, which determine how newlines are treated.

示例Example

Kusto.Cli.exe "https://kustolab.kusto.chinacloudapi.cn/;Fed=true" -script:"c:\mycommands.txt"

备注

冒号和参数值之间不应有空格There should be no space between the colon and the argument value

指令Directives

Kusto.Cli 在工具中运行多个指令,而不是将其发送到服务进行处理。Kusto.Cli runs a number of directives in the tool instead of sending them to the service for processing.

指令Directive 描述Description
?
#h
#help
获取简短的帮助消息Get a short help message
q
#quit
#exit
退出工具Exit the tool
#a
#abort
退出工具失败Exit the tool abortively
#clip 下一个查询或命令的结果将复制到剪贴板The results of the next query or command will be copied to the clipboard
#cls 清除控制台屏幕Clear the console screen
#connect [ConnectionString]#connect [ConnectionString] 连接到不同的 Kusto 服务(如果省略 ConnectionString,将显示当前的服务)Connects to a different Kusto service (if ConnectionString is omitted, the current one will be displayed)
#crp [Name [= Value]] #crp [Name [= Value]] 设置客户端请求属性的值,或者仅显示此值,或显示所有值Sets the value of a client request property, or just displays it, or displays all values
#crp (-list | -doc) [Prefix]#crp (-list | -doc) [Prefix] 按前缀列出或全部列出客户端请求属性Lists client request properties, by prefix, or all
#dbcontext [DatabaseName]#dbcontext [DatabaseName] 将查询和命令使用的“上下文”数据库更改为 DatabaseName。Changes the "context" database used by queries and commands to DatabaseName. 如果省略,将显示当前上下文If omitted, the current context displays
ke Textke Text 将指定的文本发送到正在运行的 Kusto.Explorer 进程Sends the specified text to a running Kusto.Explorer process
#loop Count Text #loop Count Text 多次运行文本Runs the text a number of times
#qp [Name [= Value]] #qp [Name [= Value]] 设置查询参数的值,或仅显示此值,或显示所有值。Sets the value of a query parameter, or just displays it, or displays all values. 将剪裁掉开头/结尾的单/双引号Single/double quotes at beginning/end will be trimmed
#save Filename#save Filename 下一个查询或命令的结果将保存到指定的 CSV 文件The results of the next query or command will be saved to the indicated CSV file
#script Filename#script Filename 执行指定的脚本Executes the indicated script
#scriptml Filename#scriptml Filename 执行指定的多行脚本Executes the indicated multiline script

行输入模式和块输入模式Line input mode and block input mode

默认情况下,Kusto.Cli 在行输入模式下运行。By default, Kusto.Cli runs in line input mode. 每个换行符被解释为查询/命令之间的分隔符,并且该行会立即被发送执行。Each newline character is interpreted as a delimiter between queries/commands, and the line is immediately sent for execution.

在此模式下,你可以将较长的查询或命令分解为多行。In this mode, you can break a long query or command into multiple lines. & 字符作为换行符之前行的最后一个字符,使 Kusto.Cli 继续读取下一行。The & character as the last character of a line, before the newline, causes Kusto.Cli to continue reading the next line. && 字符作为换行符之前行的最后一个字符,使 Kusto.Cli 忽略该换行符并继续读取下一行。The && character as the last character of a line, before the newline, causes Kusto.Cli to ignore the newline and continue reading the next line.

Kusto.Cli 还支持在块输入模式下运行。Kusto.Cli also supports running in block input mode. 通过使用命令行开关 -lineMode:false 或使用指令 #blockmode,你可以指示 Kusto.Cli 假定每一行都是前一行的延续,使查询和命令仅由空输入行分隔。By using either the command-line switch -lineMode:false, or by using the directive #blockmode, you can instruct Kusto.Cli to assume every line is a continuation of the previous line, so that queries and commands are delimited by an empty input line only.

注释Comments

Kusto.Cli 将开始新行的 // 字符串解释为注释行。Kusto.Cli interprets a // string that begins new line as a comment line. 它将忽略该行的其余部分并继续读取下一行。It ignores the rest of the line and continues reading the next line.

仅限工具的选项Tool-only options

命令Commands 效果Effect 当前Currently
#timeon#timeon #timeoff#timeoff 启用/禁用选项 timing:显示请求花费的时间enable/disable option timing: Display the time requests took TRUETRUE
#tableon#tableon #tableoff#tableoff 启用/禁用选项 tableView:将结果集的格式设置为表enable/disable option tableView: Format results sets as tables TRUETRUE
#marson#marson #marsoff#marsoff 启用/禁用选项 marsView:显示倒数第二个结果集enable/disable option marsView: Display the second-to-last result sets FALSEFALSE
#resultson#resultson #resultsoff#resultsoff 启用/禁用选项 outputResultsSet:显示结果集enable/disable option outputResultsSet: Display the result sets TRUETRUE
#prettyon#prettyon #prettyoff#prettyoff 启用/禁用选项 prettyErrors:清理错误enable/disable option prettyErrors: Clean up errors TRUETRUE
#markdownon#markdownon #markdownoff#markdownoff 启用/禁用选项 markdownView:将表的格式设置为 MarkDownenable/disable option markdownView: Format tables as MarkDown FALSEFALSE
#progressiveon#progressiveon #progressiveoff#progressiveoff 启用/禁用选项 progressiveView:询问并显示渐进式结果enable/disable option progressiveView: Ask for and display progressive results FALSEFALSE
#linemode#linemode #blockmode#blockmode 启用/禁用选项 lineMode:单行输入模式enable/disable option lineMode: Single-line input mode TRUETRUE
命令Commands 效果Effect 默认Default
#cridon#cridon #cridoff#cridoff (启用(enable 禁用选项 crid:发送请求之前显示 ClientRequestId)disable option crid: Display the ClientRequestId before sending the request) FALSEFALSE
#csvheaderson#csvheaderson #csvheadersoff#csvheadersoff (启用(enable 禁用选项 csvHeaders:在 CSV 输出中包含标头)disable option csvHeaders: Include headers in CSV output) TRUETRUE
#focuson#focuson #focusoff#focusoff (启用(enable 禁用选项 focus:删除所有多余的内容并专注于正确的内容)disable option focus: Remove all the extra fluff and focus on the right stuff) FALSEFALSE
#linemode#linemode #blockmode#blockmode (启用(enable 禁用选项 lineMode:单行输入模式)disable option lineMode: Single-line input mode) TRUETRUE
#markdownon#markdownon #markdownoff#markdownoff (启用(enable 禁用选项 markdownView:将表的格式设置为 MarkDown)disable option markdownView: Format tables as MarkDown) FALSEFALSE
#marson#marson #marsoff#marsoff (启用(enable 禁用选项 marsView:显示倒数第二个结果集)disable option marsView: Display the second-to-last result sets) FALSEFALSE
#prettyon#prettyon #prettyoff#prettyoff (启用(enable 禁用选项 prettyErrors:清理错误)disable option prettyErrors: Clean up errors) TRUETRUE
#querystreamingon#querystreamingon #querystreamingoff#querystreamingoff (启用(enable 禁用选项 queryStreaming:使用 queryStreaming 终结点(仅限 Kusto 团队))disable option queryStreaming: Use the queryStreaming endpoint (Kusto team only)) FALSEFALSE
#resultson#resultson #resultsoff#resultsoff (启用(enable 禁用选项 outputResultsSet:显示结果集)disable option outputResultsSet: Display the result sets) TRUETRUE
#tableon#tableon #tableoff#tableoff (启用(enable 禁用选项 tableView:将结果集的格式设置为表)disable option tableView: Format results sets as tables) TRUETRUE
#timeon#timeon #timeoff#timeoff (启用(enable 禁用选项 timing:显示请求花费的时间)disable option timing: Display the amount of time that the requests took) TRUETRUE
#typeon#typeon #typeoff#typeoff (启用(enable 禁用选项 typeView:在表视图中显示每个列的类型。disable option typeView: Display the type of each column in table view. 强制 Streaming=true)Forces Streaming=true) TRUETRUE
#v2protocolon#v2protocolon #v2protocoloff#v2protocoloff (启用(enable 禁用选项 v2protocol:使用 v2 查询协议,而不是 v1)disable option v2protocol: Use the v2 query protocol, not v1) TRUETRUE

使用 Kusto.Cli 将结果导出为 CSVUse Kusto.Cli to export results as CSV

Kusto.Cli 有一个特殊的客户端命令 #save,该命令将下一个查询结果导出到 CSV 格式的本地文件。Kusto.Cli has a special client-side command, #save that exports the next query results to a local file in CSV format. 例如,以下行会将 StormEvents 表中的 10 条记录导出到 help.kusto.chinacloudapi.cn 群集,Samples 数据库:For example, the following line will export 10 records out of the StormEvents table into the help.kusto.chinacloudapi.cn cluster, Samples database:

Kusto.Cli.exe @help/Samples -execute:"#save c:\temp\test.log" -execute:"StormEvents | take 10"

使用 Kusto.Cli 控制 Kusto.Explorer 的运行实例Use Kusto.Cli to control a running instance of Kusto.Explorer

你可以指示 Kusto.Cli 与在计算机上运行的 Kusto.Explorer 的“主”实例通信,并向其发送查询。You can instruct Kusto.Cli to communicate with the "primary" instance of Kusto.Explorer running on the machine, and send it queries. 对于想运行多个查询但不想重复启动 Kusto.Explorer 进程的程序,此机制很有用。This mechanism can be useful for programs that want to run a number of queries, but don't want to start the Kusto.Explorer process repeatedly. 在下面的示例中,Kusto.Cli 用于对 help 群集运行查询:In the following example, Kusto.Cli is used to run a query against the help cluster:

#connect cluster('help').database('Samples')

#ke StormEvents | count

语法非常简单:#ke,后跟空格和要运行的查询。The syntax is simple: #ke, followed by whitespace, and the query to run. 查询随后会发送到 Kusto.Explorer 的主实例(如果存在),并会在 Kusto.Cli 中设置当前的群集/数据库集。The query is then sent to the primary instance of Kusto.Explorer, if one exists, with the current cluster/database set in Kusto.Cli.