管理(控制命令)概述Management (control commands) overview

本部分介绍用于管理 Kusto 的控制命令。This section describes the control commands used to manage Kusto. 控制命令是发送给服务的请求,用于检索数据库表中不一定是数据的信息,或者用于修改服务状态,等等。Control commands are requests to the service to retrieve information that is not necessarily data in the database tables, or to modify the service state, etc.

区分控制命令和查询Differentiating control commands from queries

Kusto 使用三种机制来区分查询和控制命令:语言级别机制、协议级别机制,以及 API 级别机制。Kusto uses three mechanisms to differentiate queries and control commands: at the language level, at the protocol level, and at the API level. 这样做是为了安全。This is done for security purposes.

在语言级别,可以通过请求文本的第一个字符来确定该请求是控制命令还是查询。At the language level, the first character of the text of a request determines if the request is a control command or a query. 控制命令必须以点 (.) 字符开头,而查询则不能以该字符开头。Control commands must start with the dot (.) character, and no query may start by that character.

在协议级别,可以将不同的 HTTP/HTTPS 终结点用于控制命令而不是查询。At the protocol level, different HTTP/HTTPS endpoints are used for control commands as opposed to queries.

在 API 级别,可以将不同的函数用于发送控制命令而不是查询。At the API level, different functions are used to send control commands as opposed to queries.

组合使用查询和控制命令Combining queries and control commands

控制命令可以引用查询(反之则不行)或其他控制命令。Control commands can reference queries (but no vice-versa) or other control commands. 有几个支持的方案:There are several supported scenarios:

  1. AdminThenQuery:执行某个控制命令,将其结果(以临时数据表的形式呈现)充当某个查询的输入。AdminThenQuery: A control command is executed, and its result (represented as a temporary data table) serves as the input to a query.
  2. AdminFromQuery:执行某个查询或 .show 管理命令,将其结果(以临时数据表的形式呈现)充当某个控制命令的输入。AdminFromQuery: Either a query or a .show admin command is executed, and its result (represented as a temporary data table) serves as the input to a control command.

请注意,不管什么情况,整个组合从技术上来说是一个控制命令,而不是一个查询,因此请求的文本必须以点 (.) 字符开头,而且请求必须发送到服务的管理终结点。Note that in all cases, the entire combination is technically a control command, not a query, so the text of the request must start with a dot (.) character, and the request must be sent to the management endpoint of the service.

另请注意,查询语句出现在文本的查询部分(不能将它们置于命令本身之前)。Also note that query statements appear within the query part of the text (they can't precede the command itself).

备注

不要太频繁地运行 [command-then-query] 操作。Don't run [command-then-query] operations too frequently. command-then-query 将通过管道传输控制命令的结果集并对其应用筛选器/聚合。command-then-query pipes the result set of the control command and applies filters/aggregations on it.

  • 例如: .show ... | where ... | summarize ...For example: .show ... | where ... | summarize ...
  • 运行 .show cluster extents | count(强调 | count)之类的内容时,Kusto 会先准备一个数据表,它包含群集中所有盘区的所有详细信息。When running something like: .show cluster extents | count (emphasis on the | count), Kusto first prepares a data table that holds all details of all extents in the cluster. 然后,系统将这个仅限内存中的表发送到引擎来进行计数。The system then sends that in-memory-only table to the Kusto engine to do the count. 实际上,为了向你提供这样简单的答案,系统也要在非优化的路径中费力操作。The system actually works hard in an unoptimized path to give you such a trivial answer.

AdminThenQuery 以下述两种方式之一进行指示:AdminThenQuery is indicated in one of two ways:

  1. 如果使用竖线 (|) 字符,则查询可以将控制命令的结果视为与任何其他的数据生成查询运算符的结果一样。By using a pipe (|) character, the query therefore treats the results of the control command as if it were any other data-producing query operator.
  2. 如果使用分号 (;) 字符,则会将控制命令的结果引入名为 $command_results 的特殊符号中,该符号随即可以用在查询中,不限次数。By using a semicolon (;) character, which then introduces the results of the control command into a special symbol called $command_results, that one may then use in the query any number of times.

例如:For example:

// 1. Using pipe: Count how many tables are in the database-in-scope:
.show tables
| count

// 2. Using semicolon: Count how many tables are in the database-in-scope:
.show tables;
$command_results
| count

// 3. Using semicolon, and including a let statement:
.show tables;
let useless=(n:string){strcat(n,'-','useless')};
$command_results | extend LastColumn=useless(TableName)

AdminFromQuery 通过 <| 字符组合进行指示。AdminFromQuery is indicated by the <| character combination. 例如,在下面的代码中,我们先执行一个查询,生成一个包含单个列(名称为 str,类型为 string)和单个行的表,并将其以表名 MyTable 写入数据库的上下文中:For example, in the following we first execute a query that produces a table with a single column (named str of type string) and a single row, and write it as the table name MyTable in the database in context:

.set MyTable <|
let text="Hello, World!";
print str=Text