> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 执行查询

> 对组织作用域内的遥测数据流运行 SQL 或 PromQL。

```http theme={null}
POST /api/v1/query
```

**请求体**

| 字段           | 类型      | 必填 | 说明                                                                                |
| ------------ | ------- | -- | --------------------------------------------------------------------------------- |
| `org_id`     | string  | ✅  | 为请求兼容保留；实际以认证上下文中的组织为准。                                                           |
| `language`   | string  | ✅  | `sql` 或 `promql`。                                                                 |
| `statement`  | string  | ✅  | 查询文本。                                                                             |
| `time_range` | object  | ✅  | `{ "start": <微秒>, "end": <微秒> }`。                                                 |
| `stream`     | object  | —  | `{ "name", "stream_type" }`；类型可为 `logs`、`metrics`、`traces`、`profiles` 或 `extend`。 |
| `limit`      | integer | —  | 行数上限。                                                                             |

执行需要 `streams.query`；系统遥测查询也可使用 `sys.telemetry.read`。发送
`Accept: application/x-ndjson` 会逐行返回对象，最后附一个 `__meta__` 记录。发送
`Prefer: respond-async` 会收到 `202` 搜索任务。Enterprise Edition 可加
`?clusters=local,remote-name` 发起联邦查询。

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST http://localhost:5080/api/v1/query \
    -H "authorization: Bearer $MS_JWT" \
    -H 'content-type: application/json' \
    -d "{\"org_id\":\"$MS_ORG\",\"language\":\"sql\",
         \"statement\":\"SELECT level, count(*) FROM app GROUP BY level\",
         \"time_range\":{\"start\":0,\"end\":2000000000000000},
         \"stream\":{\"name\":\"app\",\"stream_type\":\"logs\"}}"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "columns": ["level", "count"],
    "rows": [["error", 12]],
    "scanned_rows": 10432,
    "took_ms": 18
  }
  ```
</ResponseExample>