> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 使用 TimeSeries 表中的数据，在一段评估时间范围内对 prometheus 查询求值。

# prometheusQueryRange

使用 TimeSeries 表中的数据，在一段评估时间范围内对 prometheus 查询求值。

## 语法

```sql theme={null}
prometheusQueryRange('db_name', 'time_series_table', 'promql_query', start_time, end_time, step)
prometheusQueryRange(db_name.time_series_table, 'promql_query', start_time, end_time, step)
prometheusQueryRange('time_series_table', 'promql_query', start_time, end_time, step)
```

## 参数

* `db_name` - TimeSeries 表所在的数据库名称。
* `time_series_table` - TimeSeries 表的名称。
* `promql_query` - 按 [PromQL 语法](https://prometheus.io/docs/prometheus/latest/querying/basics/) 编写的查询。
* `start_time` - 评估范围的起始时间。
* `end_time` - 评估范围的结束时间。
* `step` - 用于将评估时间从 `start_time` 逐步推进到 `end_time` (含两端) 的步长。

## 返回值

该函数会根据传递给参数 `promql_query` 的查询结果类型，返回不同的列：

| 结果类型 | 结果列 | 示例 |
| - | - | - |
| vector | tags Array(Tuple(String, String)), timestamp TimestampType, value ValueType | prometheusQuery(mytable, 'up') |
| matrix | tags Array(Tuple(String, String)), samples Array(Tuple(TimestampType, ValueType)) | prometheusQuery(mytable, 'up\[1m]') |
| scalar | scalar ValueType | prometheusQuery(mytable, '1h30m') |
| string | string String | prometheusQuery(mytable, '"abc"') |

如果 `TimeSeries` 表的 [version](/zh/reference/engines/table-engines/integrations/time-series#schema-versioning) 为 2 或更早，则 `samples` 列名为 `time_series`。

## 支持的 PromQL 特性

### 选择器

即时选择器、范围选择器、标签匹配器 (`=`、`!=`、`=~`、`!~`) 、偏移修饰符、`@` 时间戳修饰符，以及子查询。

### 函数

| 类别 | 函数 |
| - | - |
| 范围 | `rate`, `irate`, `delta`, `idelta`, `increase`, `last_over_time`, `sum_over_time`, `avg_over_time`, `count_over_time`, `max_over_time`, `min_over_time`, `ts_of_max_over_time`, `ts_of_min_over_time`, `deriv`, `changes`, `resets`, `present_over_time`, `absent_over_time`, `quantile_over_time`, `predict_linear` |
| 数学 | `abs`, `sgn`, `floor`, `ceil`, `sqrt`, `exp`, `ln`, `log2`, `log10`, `rad`, `deg`, `round`, `clamp`, `clamp_min`, `clamp_max` |
| 三角函数 | `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `sinh`, `cosh`, `tanh`, `asinh`, `acosh`, `atanh` |
| 日期时间 | `day_of_week`, `day_of_month`, `days_in_month`, `day_of_year`, `minute`, `hour`, `month`, `year` |
| 标签 | `label_replace`, `label_join` |
| 类型 | `scalar`, `vector` |
| 直方图 | `histogram_quantile` |
| 其他 | `time`, `pi`, `absent` |

**注意**：`histogram_quantile` 在经典直方图桶 (由 `le` 标签标识) 上使用线性插值。不支持原生直方图。`phi` (分位数级别) 参数必须是常量标量。像 `histogram_quantile(time() / 1000, ...)` 这样在每个步长上都会变化的表达式，会因 `NOT_IMPLEMENTED` 异常而被拒绝。

**注意**：`ts_of_min_over_time` 和 `ts_of_max_over_time` 是 Prometheus 中的 Experimental 函数 (在该系统中通过 `--enable-feature=promql-experimental-functions` 启用)；ClickHouse 无需该标志即可对其进行计算。

### 运算符

算术 (`+`、`-`、`*`、`/`、`%`、`^`、`atan2`) 和比较 (`==`、`!=`、`<`、`>`、`<=`、`>=`，可选 `bool`) 二元运算符，以及 `on()`/`ignoring()` 和 `group_left()`/`group_right()` 修饰符。

逻辑集合运算符 `and`、`or` 和 `unless`，以及 `on()`/`ignoring()` 修饰符。

一元运算符 `+` 和 `-`。

### 聚合运算符

`sum`, `avg`, `min`, `max`, `count`, `count_values`, `stddev`, `stdvar`, `group`, `quantile`, `topk`, `bottomk`, `limitk` —— 可选搭配 `by()` 或 `without()` 修饰符。

### 尚不支持

* 范围函数 `stddev_over_time`、`stdvar_over_time`、`mad_over_time`、`first_over_time`、`ts_of_last_over_time`、`ts_of_first_over_time`

## 示例

```sql theme={null}
SELECT * FROM prometheusQueryRange(mytable, 'rate(http_requests{job="prometheus"}[10m])[1h:10m]', now() - INTERVAL 10 MINUTES, now(), INTERVAL 1 MINUTE)
```