SQL查询

概述

SQL查询是Druid内置的SQL层，是基于json的查询语言的替代方式，SQL查询在查询节点上转换成本地的查询，然后传递给数据流程，除了在查询节点上翻译SQL的性能开销之外，与Druid提供的json查询没有其他的性能损失。

一、查询语法

[1] 书写使用说明

每个Druid数据源在操作模式中显示为一个表。这也是默认的模式，所以Druid数据源有两种引用方式：Druid.dataSourceName 或者 dataSourceName

如数据源和列名之类的标识符可以选择使用双引号引起来,要在标识符中转义双引号，请使用另一个双引号，例如"My ""very own"" identifier"。所有标识符都区分大小写，并且不执行任何隐式大小写转换。

文字字符串应使用单引号引起来。例如'foo'。带有Unicode转义U&'fo\00F6'符的文字字符串可以像一样编写，其中十六进制的字符代码以反斜杠作为前缀。可以以100（表示整数），100.0（表示浮点值）或1.0e5（科学计数法）的形式来写文字数。文字时间戳记可以这样写TIMESTAMP '2000-01-01 00:00:00'。文字间隔，用于时间算法，可以这样写INTERVAL '1' HOUR，INTERVAL '1 02:03' DAY TO MINUTE，INTERVAL '1-2' YEAR TO MONTH，等等。

[2] 支持查询

[ EXPLAIN PLAN FOR ]
[ WITH tableName [ ( column1, column2, ... ) ] AS ( query ) ]
SELECT [ ALL | DISTINCT ] { * | exprs }
FROM table
[ WHERE expr ]
[ GROUP BY exprs ]
[ HAVING expr ]
[ ORDER BY expr [ ASC | DESC ], expr [ ASC | DESC ], ... ]
[ LIMIT limit ]
[ UNION ALL <another query> ]

[3] 使用说明

FROM子句引用Druid数据源，例如Druid.foo，INFORMATION_SCHEMA表，子查询或WITH子句中提供的common-table-expression。如果FROM子句引用了子查询或common-table-expression，并且查询的两个级别都是聚合，并且不能将它们组合为单个聚合级别，则整个查询将作为嵌套GroupBy执行。

WHERE子句引用FROM表中的列，并将其转换为本机过滤器。WHERE子句还可以引用子查询，例如WHERE col1 IN (SELECT foo FROM ...)。这样的查询将作为半联接执行

GROUP BY子句引用FROM表中的列。使用GROUP BY，DISTINCT或任何聚合函数将使用Druid的三种本机聚合查询类型之一触发聚合查询。GROUP BY可以引用表达式或select子句的序数位置（例如GROUP BY 2按第二个select 列分组）。

HAVING子句引用执行GROUP BY后出现的列。它可用于过滤分组表达式或聚合值。它只能与GROUP BY一起使用。

ORDER BY子句引用执行GROUP BY后出现的列。它可用于根据分组表达式或汇总值对结果进行排序。ORDER BY可以引用表达式或select子句的序数位置（类似于ORDER BY 2第二个选定列的顺序）。对于非聚合查询，ORDER BY只能按__time列排序。对于聚合查询，ORDER BY可以按任何列排序。

LIMIT子句可用于限制返回的行数。它可以与任何查询类型一起使用。

" UNION ALL"运算符可用于将多个查询融合在一起。它们的结果将被串联起来，并且每个查询都连续单独运行（非并行）。如果没有" ALL"，则Druid当前不支持" UNION"。

在任何查询的开头添加" EXPLAIN PLAN FOR"，以查看SQL的查询计划。在这种情况下，查询将不会实际执行。

二、数据类型和类型转换(Data types and casts)

Druid支持五种基本列类型

• long(64位带符号的int)
• float(32位浮点)
• double(64位浮点)
• string(UTF-8编码的字符串和字符串数组)
• complex(全部捕获以获取更多特殊数据类型)

时间戳列被当做long,Druid中的时间戳不携带任何时区信息，而仅携带有关它们所代表的确切时间的信息

空处理模式，默认情况下，Druid会交替处理NULL和空字符串，而不是根据SQL标准。因此，在这种模式下，Druid SQL仅部分支持NULL。例如，表达式col IS NULL和col = ''是等效的，并且如果col包含空字符串，则两者都将得出true 。同样，如果为空字符串，则表达式COALESCE(col1, col2)将返回。当聚合器计算所有行时， 聚合器将计算expr既不为null也不为空字符串的行数。Druid中的字符串列可为NULL。数字列不为空；如果查询的Druid数据源的所有段中都不存在数字列，则这些段中的行将被视为零

对于数学运算，如果表达式中涉及的所有操作数均为整数，则Druid SQL将使用整数计算。否则，Druid将切换到浮点计算。您可以通过将其中一个操作数强制转换为FLOAT来强制执行此操作。在运行时，对于某些运算符，例如SUM聚合器，Druid可以将32位浮点数扩展到64位。

如果Druid.generic.useDefaultValueForNull将其设置为false,则在索引编制时，将以允许区分字符串列的空字符串和NULL值的方式存储数据，并允许为数字列存储NULL值。通常，Druid SQL将在此模式下更正常地运行，并且SQL优化器将在此模式下运行最佳。

Druid 多值字符串将按类型显示在表模式中，并且可以在表达式中与之交互。此外，可以ARRAY通过一些特殊的多值运算符将它们视为"类似"。针对多值字符串维的表达式会将表达式应用于行的所有值，但是需要注意的是，这些多值字符串列上的聚合将遵循本机Druid多值聚合行为，这等效UNNEST于许多方言。

下表描述了在查询运行期间SQL类型如何映射到Druid类型。具有相同Druid运行时类型的两种SQL,类型之间的强制转换将无效，除了表中指出的异常。具有不同Druid运行时类型的两种SQL类型之间的强制转换将在Druid中生成一个运行时强制转换。如果一个值不能正确地转换为另一个值，如中CAST('foo' AS BIGINT)所述，运行时将替换为默认值。强制转换为非空类型的NULL值也将替换为默认值（例如，强制转换为数字的null将转换为零）。

三、内置功能(Built-in functions)

[1] 聚合函数

聚合函数可以出现在任何查询的SELECT子句中。任何聚合器都可以使用语法进行过滤 AGG(expr) FILTER(WHERE whereExpr)。过滤的聚合器只会聚合与其过滤器匹配的行。同一SQL查询中的两个聚合器可能具有不同的过滤器。

[2] 数值函数

数值函数将返回64位整数或64位浮点数，具体取决于它们的输入。

[3] 字符串函数

字符串函数接受字符串，并返回适合该函数的类型

[4] 时间函数

时间函数可以与Druid的__time列一起使用，任何列都可以通过使用该MILLIS_TO_TIMESTAMP函数来存储毫秒时间戳，或者任何列都可以通过使用该TIME_PARSE 函数来存储字符串时间戳。默认情况下，时间操作使用UTC时区。您可以通过将连接上下文参数" sqlTimeZone"设置为另一个时区的名称（例如" America / Los_Angeles"）或偏移量（例如" -08：00"）来更改时区。如果您需要在同一查询中混合使用多个时区，或者需要使用连接时区以外的其他时区，则某些函数还接受时区作为参数。这些参数始终优先于连接时区。

可以使用TIMESTAMP '2000-01-01 00:00:00'语法编写连接时区中的文字时间戳记。在其他时区写文字时间戳的最简单方法是使用TIME_PARSE，例如 TIME_PARSE('2000-02-01 00:00:00', NULL, 'America/Los_Angeles')。

[5] IP地址函数

对于IPv4地址功能，自address变量可以是IPv4点分十进制字符串（例如'192.168.0.1'），也可以是表示为整数的IP地址（例如3232235521）。该subnet 参数应该是格式化为CIDR标记的IPv4地址子网中的字符串（如"192.168.0.0/16"）。

[6] 比较运算符

[7] 多值的字符串函数

多值字符串函数文档中的所有"数组"引用都可以引用多值字符串列或 ARRAY文字

[8] HLL草图运算符

需要添加DataSketches扩展才能使用

[9] Theta草图运算符

需要添加DataSketches扩展才能使用

[10] 分位数草图运算符

需要添加DataSketches扩展才能使用

[11] 其他功能

[12] 不支持的功能

• OVER条款，和分析功能，如LAG和LEAD。
• JOIN子句，除了如上所述的半联接。
• OFFSET子句。
• DDL和DML。
• 多值维度。
• 在DataSketches聚合器上设置操作。
• 空间过滤器。
• 查询取消。

四、 查询的执行(Query execution)

[1] 没有聚合的查询将使用Druid的Scan本机查询类型。

聚合查询（使用GROUP BY，DISTINCT或任何聚合函数）将使用Druid的三种本机聚合查询类型之一。两种（时间序列和TopN）专用于特定类型的聚合，而另一种（GroupBy）则是通用的

• 时间序列

  用于查询GROUP BY FLOOR(__time TO <unit>)或TIME_FLOOR(__time, period)，没有其他分组表达式，没有HAVING或LIMIT子句，没有嵌套，也没有ORDER BY或按与GROUP BY中相同的表达式排序的ORDER BY的查询。它还将"时间序列"用于具有聚合功能但没有GROUP BY的"总计"查询。这种查询类型利用了Druid段按时间排序的事实

• TopN

  TopN用于由单个表达式分组，具有ORDER BY和LIMIT子句，不具有HAVING子句且未嵌套的查询。但是，在某些情况下，TopN查询类型将提供近似的排名和结果。如果要避免这种情况，请将" use近似TopN"设置为" false"。TopN结果始终在内存中计算。

• GroupBy

  GroupBy用于所有其他聚合，包括任何嵌套的聚合查询。Druid的GroupBy是传统的聚合引擎：它提供准确的结果和排名，并支持多种功能。GroupBy可以在内存中进行聚合，但是如果没有足够的内存来完成查询，则GroupBy可能会溢出到磁盘中。如果您在GROUP BY子句中使用相同的表达式进行ORDER BY，或者根本没有ORDER BY，结果将通过Broker从数据过程中流回。如果查询的ORDER BY引用表达式未出现在GROUP BY子句中（例如聚合函数），则Broker将在内存中具体化结果列表，最多为LIMIT（如果有）。

如果查询执行嵌套聚合（FROM子句中的聚合子查询），则Druid将其作为嵌套GroupBy执行 。在嵌套的GroupBy中，最内部的聚合是分布式的，但是除此以外的所有外部聚合都在查询代理上本地进行。

包含WHERE子句之类的半联接查询col IN (SELECT expr FROM ...)通过特殊过程执行。代理将首先将子查询转换为GroupBy，以查找的不同值expr。然后，代理会将子查询重写为文字过滤器，例如col IN (val1, val2, ...)运行外部查询。配置参数Druid.sql.planner.maxSemiJoinRowsInMemory控制将为此类计划实现的最大值数。

对于所有本机查询类型，该__time列上的过滤器将尽可能转换为顶级查询"间隔"，这使Druid可以使用其全局时间索引来快速修剪必须扫描的数据集。此外，Druid将使用每个数据过程本地的索引来进一步加快WHERE评估。通常，对于涉及单个列的引用和函数的布尔组合的过滤器（例如WHERE col1 = 'a' AND col2 = 'b'，但不），可以完成此操作 WHERE col1 = col2。

[2] 近似算法

在某些情况下，Druid SQL将使用近似算法：

COUNT(DISTINCT col)默认情况下，聚合函数使用HyperLogLog的变体， HyperLogLog是一种快速的近似非重复计数算法。如果通过查询上下文或通过Broker配置将" useroximateCountDistinct"设置为" false"，则Druid SQL将切换到完全不同的计数。

可以使用TopN引擎（使用近似算法）对使用ORDER BY和LIMIT的单列进行GROUP BY查询。如果您通过查询上下文或通过Broker配置将" use近似TopN"设置为" false"，则Druid SQL将切换到精确的分组算法。

无论配置如何，APPROX_COUNT_DISTINCT和APPROX_QUANTILE聚合函数始终使用近似算法。

五、客户端API(Client APIs)

[1] 通过Http发送json

可以通过发送json文件的形式进行Druid SQL查询/Druid/v2/sql/。该请求应该是带有“query”字段的JSON对象

• 可以使用curl从命令行发送SQL查询

  $ cat query.json
  {"query":"SELECT COUNT(*) AS TheCount FROM data_source"}
  
  $ curl -XPOST -H'Content-Type: application/json' http://BROKER:8082/Druid/v2/sql/ -d @query.json
  [{"TheCount":24433}]
  

• 可以通过在查询文件中设置context映射进行查询

  {
    "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP '2000-01-01 00:00:00'",
    "context" : {
      "sqlTimeZone" : "America/Los_Angeles"
    }
  }
  

• 结果集

  {
    "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP '2000-01-01 00:00:00'",
    "resultFormat" : "object"
  }
  

  格式	描述	内容类型
  object	默认值是JSON对象的JSON数组。每个对象的字段名称都与SQL查询返回的列匹配，并且以与SQL查询相同的顺序提供。	应用程序/ json
  array	JSON数组。每个内部数组都具有按顺序匹配SQL查询返回的列的元素。	应用程序/ json
  objectLines	类似于“对象”，但是JSON对象用换行符分隔，而不是包装在JSON数组中。如果您没有现成的流JSON解析器访问权限，则可以更轻松地将整个响应集解析为流。为了能够检测到截断的响应，此格式包含一个空白行的尾部。	文字/纯文字
  arrayLines	类似于“数组”，但是JSON数组由换行符分隔，而不是包装在JSON数组中。如果您没有现成的流JSON解析器访问权限，则可以更轻松地将整个响应集解析为流。为了能够检测到截断的响应，此格式包含一个空白行的尾部。	文字/纯文字
  csv	逗号分隔的值，各个字段值可以用双引号引起来。如果双引号出现在字段值中，则可以通过将双引号替换为来对其进行转义""this""。为了能够检测到截断的响应，此格式包含一个空白行的尾部。	文字/ csv

• 还可以通过在请求中将“ header”设置为true来请求标头

  {
    "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP '2000-01-01 00:00:00'",
    "resultFormat" : "arrayLines",
    "header" : true
  }
  

  返回的第一个结果将是标题。对于csv，array和arrayLines格式，标题将是列名的列表。对于object和objectLines格式，标头将是一个对象，其中键是列名，值是null

  发送响应正文之前发生的错误将以JSON格式（带有HTTP 500状态代码）报告，格式与本机Druid查询错误相同。如果在发送响应正文时发生错误，则此时更改HTTP状态代码或报告JSON错误就已经晚了，因此响应只会在中途结束，而Druid将记录一个错误，处理您的请求。

  作为请求者，正确的处理响应很重要，对于“对象”和“数组”格式，这很容易，因为响应将是无效的JSON。对于面向行的格式，应该检查它们都包含的空白行：在结果集的末尾有一个空白行。如果通过JSON解析错误或缺少的尾随换行符检测到截断的响应，则应假定由于错误而未完正确响应。

[2] JDBC

可以使用Avatica JDBC驱动程序进行Druid SQL查询。下载Avatica客户端jar后，将其添加到类路径并使用connect string jdbc:avatica:remote:url=http://BROKER:8082/Druid/v2/sql/avatica/

// Connect to /Druid/v2/sql/avatica/ on your Broker.
String url = "jdbc:avatica:remote:url=http://localhost:8082/Druid/v2/sql/avatica/";

// Set any connection context parameters you need here (see "Connection context" below).
// Or leave empty for default behavior.
Properties connectionProperties = new Properties();

try (Connection connection = DriverManager.getConnection(url, connectionProperties)) {
try (
    final Statement statement = connection.createStatement();
    final ResultSet resultSet = statement.executeQuery(query)
) {
    while (resultSet.next()) {
    // Do something
    }
}
}

元数据可通过JDBC使用connection.getMetaData()或通过查询 “ INFORMATION_SCHEMA”表获得。参数化查询（使用?或其他占位符）无法正常工作，因此请避免使用这些查询。

Druid的JDBC服务器在Broker之间不共享连接状态。这意味着，如果您使用的是JDBC并且有多个Druid Broker，则应该连接到特定的Broker，或者使用启用了共享会话的负载平衡器。Druid Router进程在平衡JDBC请求时提供连接共享性

Druid SQL支持在客户端上设置连接参数。下表中的参数影响SQL规划。您提供的所有其他上下文参数将附加到Druid查询中，并可能影响它们的运行方式。

要为SQL查询指定唯一标识符，请使用sqlQueryId代替queryId。设置queryIdSQL请求无效，所有基于SQL的本机查询都将使用自动生成的queryId

六、元数据表(Metadata tables)

Druid Brokers从集群中加载的段中推断出每个数据源的表和列元数据，并以此计划SQL查询。该元数据在Broker启动时被缓存，并通过SegmentMetadata查询在后台定期更新 。后台元数据刷新由进入和退出集群的段触发，也可以通过配置来限制。

Druid通过特殊的系统表公开系统信息。有两种可用的模式：信息模式和系统模式。信息模式提供有关表和列类型的详细信息。系统模式提供有关Druid内部的信息，例如段/任务/服务器。

[1] 信息模式

您可以使用connection.getMetaData()或通过下面介绍的INFORMATION_SCHEMA表通过JDBC访问表和列元数据。例如，要检索Druid数据源“ foo”的元数据，请使用查询

SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = 'Druid' AND TABLE_NAME = 'foo'

• Schemata表

  列	备注
  CATALOG_NAME	没用过
  SCHEMA_NAME
  SCHEMA_OWNER	没用过
  DEFAULT_CHARACTER_SET_CATALOG	没用过
  DEFAULT_CHARACTER_SET_SCHEMA	没用过
  DEFAULT_CHARACTER_SET_NAME	没用过
  SQL_PATH	没用过

• Tables表

  列	备注
  TABLE_CATALOG	没用过
  TABLE_SCHEMA
  TABLE_NAME
  TABLE_TYPE	“ TABLE”或“ SYSTEM_TABLE”

• Columns表

  列	备注
  TABLE_CATALOG	没用过
  TABLE_SCHEMA
  TABLE_NAME
  COLUMN_NAME
  ORDINAL_POSITION
  COLUMN_DEFAULT	没用过
  IS_NULLABLE
  DATA_TYPE
  CHARACTER_MAXIMUM_LENGTH	没用过
  CHARACTER_OCTET_LENGTH	没用过
  NUMERIC_PRECISION
  NUMERIC_PRECISION_RADIX
  NUMERIC_SCALE
  DATETIME_PRECISION
  CHARACTER_SET_NAME
  COLLATION_NAME
  JDBC_TYPE	来自java.sql.Types的类型代码（Druid扩展）

[2] 系统模式

系统模式提供了对Druid 的segments, servers and tasks可见性

• segments表

  列	类型	备注
  segment_id	STRING	ID
  datasource	STRING	数据源名称
  start	STRING	间隔开始时间
  end	STRING	间隔结束时间
  size	LONG	段的大小
  version	STRING	版本
  partition_num	LONG	分区号
  num_replicas	LONG	副本数
  num_rows	LONG	当前段中的行数
  is_published	LONG	是否已经发布存储到元数据中
  is_available	LONG	是否可用找到能提供服务的
  is_realtime	LONG	是否是实时任务提供服务
  is_overshadowed	LONG	是否此段已发布且被其他已发布段完全覆盖
  payload	STRING	JSON序列化的数据段有效负载

  要检索数据源“ Wikipedia”的所有段，请使用查询

  SELECT * FROM sys.segments WHERE datasource = 'wikipedia'
  

  检索每个数据源检索段total_size，avg_size，avg_num_rows和num_segments

  SELECT
      datasource,
      SUM("size") AS total_size,
      CASE WHEN SUM("size") = 0 THEN 0 ELSE SUM("size") / (COUNT(*) FILTER(WHERE "size" > 0)) END AS avg_size,
      CASE WHEN SUM(num_rows) = 0 THEN 0 ELSE SUM("num_rows") / (COUNT(*) FILTER(WHERE num_rows > 0)) END AS avg_num_rows,
      COUNT(*) AS num_segments
  FROM sys.segments
  GROUP BY 1
  ORDER BY 2 DESC
  

  一个段可以由多个流摄取任务或历史进程提供服务，在这种情况下，该段将具有多个副本。这些副本在由多个提取任务提供服务时，彼此之间几乎没有一致性，直到某个段最终由历史记录提供服务为止，此时该段是不可变的。查询节点更喜欢从历史任务中查询一个分段，而不是流摄取任务。但是，如果一个段具有多个实时副本，例如。Kafka索引任务，并且一个任务比其他任务慢，则sys.segments查询结果在任务持续时间内可能会有所不同，因为Broker仅查询一个摄取任务，并且不能保证选择同一任务每次。的num_rows在此期间，细分表的“列”值可能会不一致。

• Servers表

  列	类型	备注
  server	STRING	服务名称
  host	STRING	服务的主机名
  plaintext_port	LONG	服务的不安全端口；如果禁用了纯文本流量，则为-1
  tls_port	LONG	服务的TLS端口，如果禁用了TLS，则为-1
  server_type	STRING	服务类型，取值为：COORDINATOR，OVERLORD，BROKER，ROUTER，HISTORICAL，MIDDLE_MANAGER或PEON
  tier	STRING	分发层，仅对HISTORICAL类型有效，对于其他类型则为null
  current_size	LONG	当前服务器上段的当前大小
  max_size	LONG	当前服务器建议配置的段的最大的设置

  要检索有关所有服务器的信息，请使用查询

  SELECT * FROM sys.servers;
  

• Server_segments表

  列	类型	备注
  server	STRING	服务名称
  segment_id	STRING	段标识符（段表的主键）

  “服务器”和“段”之间的JOIN可用于查询特定数据源的段数（按服务器分组）

  SELECT count(segments.segment_id) as num_segments from sys.segments as segments
  INNER JOIN sys.server_segments as server_segments
  ON segments.segment_id  = server_segments.segment_id
  INNER JOIN sys.servers as servers
  ON servers.server = server_segments.server
  WHERE segments.datasource = 'wikipedia'
  GROUP BY servers.server;
  

• Task表

  任务表提供有关活动的和最近完成的索引编制任务的信息

  列	类型	备注
  task_id	STRING	ID
  group_id	STRING	任务组ID
  type	STRING	任务类型
  datasource	STRING	数据源名称
  created_time	STRING	创建时间
  queue_insertion_time	STRING	进入Overlord队列的时间
  status	STRING	任务运行状态 RUNNING, FAILED, SUCCESS
  runner_status	STRING	当前运行的状态，已完成的则为无 正在运行的则为 正在运行 正在等待
  duration	LONG	任务运行的时间
  location	STRING	运行所在的机器 主机：端口
  host	STRING	主机名称
  plaintext_port	服务器的不安全端口；如果禁用了纯文本流量，则为-1
  tls_port	LONG	服务器的TLS端口，如果禁用了TLS，则为-1
  error_msg	STRING	失败任务时的详细错误消息

  要检索按状态过滤的任务信息，请使用查询

  SELECT * FROM sys.tasks WHERE status='FAILED';
  

• Supervisor表

  列	类型	备注
  supervisor_id	STRING	ID
  state	STRING	状态: UNHEALTHY_SUPERVISOR, UNHEALTHY_TASKS, PENDING, RUNNING, SUSPENDED, STOPPING
  detailed_state	STRING	特定状态
  healthy	LONG	是否是正常的状态
  type	STRING	类型
  source	STRING	数据来源
  suspended	LONG	暂停状态
  spec	STRING	JSON序列化的主管规范

  要检索按运行状况过滤的主管任务信息，请使用查询

  SELECT * FROM sys.supervisors WHERE healthy=0;
  

  sys表不支持所有Druid SQL函数

七、服务器配置(erver configuration)

Druid的SQL服务的配置是通过查询节点Broker配置的

八、SQL指标(SQL Metrics)

Broker将针对SQL发出以下指标