RLei.RedashUtils 1.0.2

RLei.RedashUtils

用于从 Redash 获取查询结果的 .NET 工具库。

功能

• 获取查询元数据（列信息、参数定义）
• 执行查询并获取数据（支持参数化查询）
• 获取单条查询详情
• 导出查询结果到 Excel（支持多查询多 Sheet）
• 自动处理分页参数（_pageIndex / _pageSize）
• 自动同步查询参数（补全缺失的默认值）
• 自动轮询异步查询任务状态
• 动态可见列配置（基于条件表达式过滤列）
• JSON 列自动解析
• # 前缀列自动过滤

安装

dotnet add package RLei.RedashUtils

配置

在 appsettings.json 中添加：

{
  "RedashSettings": {
    "BaseUrl": "https://your-redash-instance.com",
    "ApiKey": "your-api-key",
    "QueryDelayMs": 100,
    "TimeoutSeconds": 30
  }
}

配置项说明

使用

注册服务

从配置文件自动绑定（推荐）：

// Program.cs
builder.Services.AddRedashService(builder.Configuration);

手动配置（用于测试或特殊场景）：

services.AddRedashService(settings =>
{
    settings.BaseUrl = "https://your-redash-instance.com";
    settings.ApiKey = "your-api-key";
});

获取查询元数据

var metadata = await redashService.GetQueryMetadataAsync(queryId: 123);

// 带参数（用于可见列动态过滤）
var metadata = await redashService.GetQueryMetadataAsync(
    queryId: 123,
    parameters: new Dictionary<string, object> { ["status"] = "active" });

执行查询

// 无参数
var result = await redashService.ExecuteQueryAsync(queryId: 123);

// 带参数
var result = await redashService.ExecuteQueryAsync(
    queryId: 123,
    parameters: new Dictionary<string, object> { ["date"] = "2026-01-01" },
    maxAge: 300);

// 分页查询
var result = await redashService.ExecuteQueryAsync(
    queryId: 123,
    parameters: new Dictionary<string, object>
    {
        ["_pageIndex"] = 1,
        ["_pageSize"] = 20
    });

// 处理结果
if (result.Success)
{
    var total = result.Total;      // 总记录数
    var totalPage = result.TotalPage;  // 总页数
    foreach (var row in result.Data) { ... }
}

获取单条详情

var detail = await redashService.GetDetailAsync(
    queryId: 123,
    parameters: new Dictionary<string, object> { ["id"] = 456 });

if (detail.Success && detail.Data != null)
{
    // detail.Data 是 Dictionary<string, object>
    var name = detail.Data["name"]?.ToString();
}

导出 Excel

// 导出单个查询
var bytes = await excelExportService.ExportQueryToExcelAsync(queryId: 123);

// 导出多个查询（每个查询一个 Sheet）
var bytes = await excelExportService.ExportQueriesToExcelAsync(
    queryIds: new List<int> { 123, 456, 789 },
    parameters: new Dictionary<string, object> { ["date"] = "2026-01-01" });

响应模型

QueryResponse（列表数据）

public class QueryResponse
{
    public bool Success { get; set; }
    public List<Dictionary<string, object>>? Data { get; set; }
    public string? Error { get; set; }
    public int? Total { get; set; }      // 总记录数
    public int? TotalPage { get; set; }  // 总页数
}

QueryDetailResponse（单条数据）

public class QueryDetailResponse
{
    public bool Success { get; set; }
    public Dictionary<string, object>? Data { get; set; }
    public string? Error { get; set; }
}

QueryMetadata（元数据）

public class QueryMetadata
{
    public string? Name { get; set; }
    public List<ColumnInfo>? Columns { get; set; }
    public List<QueryParameter>? Parameters { get; set; }
}

高级功能

分页查询

传入 _pageIndex（从 1 开始）和 _pageSize 参数，库自动转换为 Redash 需要的 _pageSkip + _pageSize 组合：

var result = await redashService.ExecuteQueryAsync(
    queryId: 123,
    parameters: new Dictionary<string, object>
    {
        ["_pageIndex"] = 2,   // 第 2 页
        ["_pageSize"] = 20    // 每页 20 条
    });

// result.Total = 总记录数
// result.TotalPage = 总页数

动态可见列

在 Redash 查询的 options 中配置 visible_columns，根据参数动态显示/隐藏列：

{
  "visible_columns": [
    { "name": "status", "condition": "status == \"active\"" },
    { "name": "amount", "condition": "showAmount == true" },
    { "name": "date", "condition": "startDate != null" }
  ]
}

条件表达式使用 C# 语法（基于 RulesEngine），求值为 true 时显示列，为 false 时隐藏。

常用表达式示例：

参数自动同步

执行查询时，库会自动与 Redash 定义的参数做同步：

• 多传的参数会被移除
• 缺少的参数会根据类型自动填充默认值

JSON 列自动解析

当列的 type 或 displayAs 为 "json" 时，自动将字符串值解析为 ExpandoObject。

Excel 导出限制

• 单次最多导出 20 个查询
• 总行数不超过 50 万行
• 超出时抛出 InvalidOperationException

目标框架

• .NET 10.0+

依赖

• Newtonsoft.Json
• Microsoft.Extensions.Http
• Microsoft.Extensions.Options
• MiniExcel
• RulesEngine

License

MIT