# table-query-service

**Repository Path**: makarovd/table-query-service

## Basic Information

- **Project Name**: table-query-service
- **Description**: 查询Hudi、Hive表，采样返回数据值结果
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Table Query Service

高性能表数据采样查询服务，支持从 Presto 查询引擎中对表字段进行随机采样，并提供本地缓存和定时预热功能。

## 功能特性

- **单字段采样** - 支持对指定表的单个字段进行数据采样
- **批量字段采样** - 支持一次性查询同一张表的多个字段，减少网络交互
- **双层查询策略** - 先使用 TABLESAMPLE 快速采样，数据不足时自动兜底全表查询
- **本地缓存** - 基于 Caffeine 的高性能本地缓存，支持缓存数据截取
- **定时预热** - 支持配置 Cron 表达式定时预热指定库的表数据
- **增量预热** - 自动记录已处理表，支持增量预热模式
- **超时控制** - 单表和批次级别的异步超时控制（Java 8 CompletableFuture）
- **字段过滤** - 支持配置排除特定模式的字段（如 Hudi 元数据字段）
- **并发控制** - 支持配置并发数和限流速率

## 技术栈

- **Java 8** - 编程语言
- **Spring Boot 2.7.x** - 应用框架
- **Presto SQL** - 查询引擎
- **Caffeine** - 本地缓存
- **HikariCP** - 数据库连接池
- **Lombok** - 代码简化

## 快速开始

### 环境要求

- JDK 8+
- Maven 3.6+
- Presto 服务器

### 构建运行

```bash
# 克隆项目
git clone <repository-url>
cd table-query-service

# 编译打包（生成瘦 jar + lib 目录）
mvn clean package -DskipTests

# 运行
java -jar target/table-query-service-1.0.0.jar
```

### 基础配置

在 `application.yml` 中配置 Presto 连接：

```yaml
presto:
  jdbc-url: jdbc:presto://localhost:8080/hive/default
  user: presto
  password:
```

## API 文档

### 1. 单字段采样（POST）

```http
POST /api/v1/sample
Content-Type: application/json

{
  "tableName": "db.table",
  "columnName": "column_name",
  "sampleSize": 50
}
```

**响应示例：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "tableName": "db.table",
    "columnName": "column_name",
    "sampleSize": 50,
    "values": ["value1", "value2", ...],
    "durationMs": 120,
    "engine": "PRESTO"
  },
  "timestamp": 1704067200000
}
```

### 2. 单字段采样（GET）

```http
GET /api/v1/sample?tableName=db.table&columnName=column_name&sampleSize=50
```

### 3. 批量字段采样

```http
POST /api/v1/batch-sample
Content-Type: application/json

{
  "tableName": "db.table",
  "columnNames": ["col1", "col2", "col3"],
  "sampleSize": 50
}
```

### 4. 表结构查询（DDL）

```http
POST /api/v1/ddl
Content-Type: application/json

{
  "tableName": "db.table"
}
```

**响应示例：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "tableName": "db.table",
    "ddl": "CREATE TABLE db.table (...)",
    "durationMs": 150
  },
  "timestamp": 1704067200000
}
```

## 配置说明

### Presto 配置

```yaml
presto:
  jdbc-url: jdbc:presto://host:port/catalog/schema  # JDBC 连接地址
  user: presto                                      # 用户名
  password:                                         # 密码
  pool:
    max-size: 10                                    # 连接池最大连接数
    min-idle: 2                                     # 连接池最小空闲连接数
  query:
    timeout-seconds: 30                             # 查询超时时间（秒）
    max-sample-size: 100                            # 最大采样数量
    tablesample-enabled: true                       # 是否启用 TABLESAMPLE
    tablesample-percentage: 1                       # TABLESAMPLE 百分比 (1-100)
```

### 缓存配置

```yaml
cache:
  max-size: 10000                                   # 缓存最大条目数
  expire-hours: 168                                 # 缓存过期时间（小时）
```

### 预热配置

```yaml
prewarm:
  enabled: true                                     # 是否启用预热
  cron: "0 0 2 * * ?"                              # 定时执行 Cron 表达式（每天凌晨2点）
  databases:                                        # 需要预热的数据库列表
    - db1
    - db2
  catalog: hive                                     # 目标 Catalog
  max-columns-per-table: 100                        # 每表最大处理字段数
  batch-size: 10                                    # 批处理大小（并发处理表数量）
  concurrency: 5                                    # 并发线程数
  rate-limit: 10                                    # 限流速率（每秒查询数）
  single-table-timeout-seconds: 300                 # 单表处理超时（秒）
  batch-timeout-seconds: 600                        # 批次处理超时（秒）
  processed-tables-file: data/processed-tables.json # 已处理表记录文件
  excluded-column-patterns:                         # 排除字段模式
    - "_hoodie_"
    - "hoodie_"
    - "_ts"
    - "_commit_"
```

### 安全配置

```yaml
security:
  whitelist:
    ips: 10.0.0.0/24,192.168.1.1                   # IP 白名单（支持 CIDR）
  user:
    name: admin                                     # 认证用户名
    password: admin123                              # 认证密码
```

## 架构设计

### 核心组件

```
┌─────────────────────────────────────────────────────────────┐
│                        Controller 层                         │
│  ┌──────────────┐  ┌────────────────┐  ┌──────────────┐    │
│  │QueryController│  │HealthController│  │ExceptionHandler│  │
│  └──────────────┘  └────────────────┘  └──────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                         Service 层                           │
│  ┌──────────────────┐  ┌──────────────────┐                │
│  │ PrestoQueryService│  │  TableMetaService │                │
│  │ (查询+缓存)       │  │  (元数据获取)      │                │
│  └──────────────────┘  └──────────────────┘                │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                        Scheduler 层                          │
│  ┌──────────────────────────────────────────────┐          │
│  │       CachePrewarmScheduler (缓存预热)        │          │
│  │  ┌──────────────┐  ┌──────────────────────┐  │          │
│  │  │ 定时任务调度  │  │ 异步超时控制(Java 8) │  │          │
│  │  └──────────────┘  └──────────────────────┘  │          │
│  └──────────────────────────────────────────────┘          │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                         Data 层                              │
│  ┌──────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │ Presto DB    │  │ Caffeine Cache    │  │ Processed File│  │
│  │ (查询数据源)  │  │ (本地缓存)        │  │ (已处理记录)  │  │
│  └──────────────┘  └──────────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

### 查询流程

1. **缓存检查** - 检查本地缓存是否存在且数据量充足
2. **TABLESAMPLE 查询** - 使用 TABLESAMPLE SYSTEM(1) 快速采样
3. **兜底查询** - 如果 TABLESAMPLE 数据不足，执行全表查询兜底
4. **缓存更新** - 将查询结果写入本地缓存
5. **结果返回** - 返回采样数据

### 预热流程

1. **加载已处理表** - 从文件加载历史已处理表记录
2. **获取新增表** - 对比当前库表与已处理表，找出新增表
3. **分批次处理** - 将新增表分批并发处理
4. **字段采样** - 对每个表的每个字段执行采样查询
5. **更新记录** - 将处理完成的表标记为已处理并持久化到文件

## 部署说明

### Docker 部署

项目提供精简的 Dockerfile，支持健康检查：

```dockerfile
# 运行阶段：使用精简的JRE镜像
FROM openjdk:8u342

USER root

# 安装必要的工具
RUN apt-get update && apt-get install -y curl iputils-ping telnet && rm -rf /var/lib/apt/lists/*

# 创建应用目录
WORKDIR /app

# 从本地target目录复制预构建的jar
COPY target/table-query-service-*.jar app.jar

# 暴露端口
EXPOSE 33000

# 健康检查
HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:33000/health || exit 1

# 启动命令
ENTRYPOINT ["java", "-XX:+UseG1GC", "-Xmx1g", "-jar", "app.jar"]
```

```bash
# 构建镜像
docker build -t table-query-service:1.0.0 .

# 运行容器
docker run -d \
  -p 33000:33000 \
  -e PRESTO_JDBC_URL=jdbc:presto://presto-server:8085/hive/default \
  table-query-service:1.0.0
```

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `PRESTO_JDBC_URL` | Presto JDBC 连接地址 | jdbc:presto://localhost:8085/hive/default |
| `PRESTO_USER` | Presto 用户名 | presto |
| `PRESTO_PASSWORD` | Presto 密码 | 空 |
| `PRESTO_POOL_MAX_SIZE` | 连接池最大连接数 | 10 |
| `PRESTO_POOL_MIN_IDLE` | 连接池最小空闲连接 | 2 |
| `PRESTO_QUERY_TIMEOUT_SECONDS` | 查询超时时间（秒） | 30 |
| `PRESTO_QUERY_DEFAULT_SAMPLE_SIZE` | 默认采样数量 | 50 |
| `PRESTO_QUERY_MIN_SAMPLE_SIZE` | 最小采样数量 | 1 |
| `PRESTO_QUERY_MAX_SAMPLE_SIZE` | 最大采样数量 | 100 |
| `PRESTO_QUERY_TABLESAMPLE_ENABLED` | 是否启用 TABLESAMPLE | true |
| `PRESTO_QUERY_TABLESAMPLE_PERCENTAGE` | TABLESAMPLE 百分比 | 1 |
| `CACHE_MAX_SIZE` | 缓存最大条目数 | 10000 |
| `CACHE_EXPIRE_HOURS` | 缓存过期时间（小时） | 168 |
| `PREWARM_ENABLED` | 是否启用定时预热 | true |
| `PREWARM_CRON` | 预热 Cron 表达式 | 0 0 2 * * ? |
| `PREWARM_DATABASES` | 预热数据库列表 | default |
| `PREWARM_CATALOG` | 目标 Catalog | hive |
| `PREWARM_CONCURRENCY` | 预热并发数 | 5 |
| `PREWARM_RATE_LIMIT` | 预热限流速率 | 10 |
| `SECURITY_WHITELIST_IPS` | IP 白名单 | 0.0.0.0/0 |
| `SECURITY_USER_NAME` | 认证用户名 | admin |
| `SECURITY_USER_PASSWORD` | 认证密码 | admin123 |

## 性能优化建议

1. **缓存配置** - 根据数据量和内存大小调整 `cache.max-size` 和 `cache.expire-hours`
2. **连接池** - 根据并发量调整 `presto.pool.max-size`
3. **预热策略** - 大数据量表建议调整 `prewarm.max-columns-per-table` 限制字段数
4. **超时设置** - 根据表数据量调整单表和批次超时时间
5. **并发控制** - 根据 Presto 集群能力调整 `prewarm.concurrency` 和 `prewarm.rate-limit`
6. **TABLESAMPLE 调优** - 通过 `tablesample-percentage` 调整采样比例，数据量大时可适当降低

## 监控指标

服务暴露以下监控端点（基于 Spring Boot Actuator）：

- `GET /actuator/health` - 健康检查
- `GET /actuator/metrics` - 指标数据
- `GET /actuator/info` - 应用信息

## 许可证

[MIT License](LICENSE)

## 贡献指南

欢迎提交 Issue 和 Pull Request。

## 联系方式

如有问题，请联系项目维护者。