{"id":29481607,"url":"https://github.com/turtacn/starseek","last_synced_at":"2025-07-15T01:02:00.260Z","repository":{"id":302653593,"uuid":"1013145151","full_name":"turtacn/starseek","owner":"turtacn","description":"StarSeek：an open-source mid-platform designed to empower columnar analytical databases like StarRocks, Apache Doris, and ClickHouse with advanced full-text search capabilities typically found in dedicated search engines such as Elasticsearch powered by generative AI.","archived":false,"fork":false,"pushed_at":"2025-07-03T13:51:50.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-03T14:51:24.571Z","etag":null,"topics":["clickhouse","doris","elasticsearch","fulltext-search","starrocks"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/turtacn.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-03T12:32:18.000Z","updated_at":"2025-07-03T13:51:53.000Z","dependencies_parsed_at":"2025-07-03T18:32:08.198Z","dependency_job_id":null,"html_url":"https://github.com/turtacn/starseek","commit_stats":null,"previous_names":["turtacn/starseek"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/turtacn/starseek","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turtacn%2Fstarseek","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turtacn%2Fstarseek/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turtacn%2Fstarseek/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turtacn%2Fstarseek/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/turtacn","download_url":"https://codeload.github.com/turtacn/starseek/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turtacn%2Fstarseek/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265381873,"owners_count":23756269,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clickhouse","doris","elasticsearch","fulltext-search","starrocks"],"created_at":"2025-07-15T01:00:48.777Z","updated_at":"2025-07-15T01:02:00.200Z","avatar_url":"https://github.com/turtacn.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# StarSeek: 面向数仓与数据湖的统一全文检索中台服务\n\n## 🌟 项目简介\n\nStarSeek 是一个创新的开源中台服务，旨在为 StarRocks、Apache Doris 和 ClickHouse 等列式分析型数据库赋能，提供类似 Elasticsearch 的高级全文检索能力。通过充分利用这些 OLAP 数据库底层的倒排索引特性，StarSeek 构建了一个统一、智能且高度可扩展的搜索服务层，显著增强了它们在文档检索、内容搜索和复杂数据探索方面的效用。\n\n本项目旨在解决分析型数据库在处理复杂全文检索需求时的固有局限性，将其转变为强大的搜索后端，同时避免了维护一个独立搜索集群的额外开销。\n\n## 🎯 核心痛点与核心价值\n\n### 解决的痛点\n\n*   **原生全文检索能力有限**: 尽管 StarRocks、Doris 和 ClickHouse 提供了基础的倒排索引功能，但它们缺乏高级搜索特性，如跨表/跨列查询、相关度评分（TF-IDF/BM25）、同义词扩展、结果高亮显示以及统一的元数据管理。\n*   **开发与维护复杂**: 开发者常常需要手动构建复杂的 SQL 查询（例如 `MATCH_AGAINST`、`UNION ALL`），处理分词一致性，并在应用层实现排名逻辑，这导致了开发复杂性增加和效率降低。\n*   **用户体验不佳**: 最终用户常常面临搜索结果不够精确，且缺乏现代搜索应用中常见的先进交互式搜索功能。\n*   **数据源耦合**: 应用程序与底层分析型数据库的特定 SQL 方言和索引机制紧密耦合，阻碍了灵活性和未来的迁移。\n\n### 核心价值主张\n\n*   **统一搜索入口**: StarSeek 为您在分析型数据存储上的所有全文检索操作提供一个统一、标准化的 API 端点，简化了客户端集成。\n*   **功能增强**: 它弥补了底层数据库的功能空白，引入了类似 Elasticsearch 的丰富搜索能力，例如：\n    *   **统一索引元数据管理**: 集中注册和管理多表、多数据库中所有已索引列的元数据。\n    *   **高级查询处理**: 支持自然语言查询、多字段搜索（如 `title:关键词 AND content:另一个`）、同义词扩展，以及智能地将查询转换为优化的 SQL。\n    *   **模拟相关度排名**: 在服务端实现类似 TF-IDF/BM25 的评分机制，提供高度相关的搜索结果。\n    *   **高亮与分页**: 提供了丰富的用户搜索体验所必需的功能。\n    *   **跨表/跨列搜索**: 通过一个查询无缝地在多个表和列中进行搜索。\n*   **提升开发者效率**: 抽象了复杂的 SQL 生成、分词和排名逻辑，使开发者能够专注于应用业务逻辑。\n*   **数据源无关性**: 提供了一个适配器层，以支持 StarRocks、Apache Doris 和 ClickHouse 作为主要后端，并以 StarRocks 为核心焦点。\n*   **性能优化**: 集成了缓存机制（例如 Redis 用于热门关键词）和并发查询执行管理，以优化搜索性能。\n\n## ✨ 主要功能特性\n\n*   **索引注册服务 (Index Registry)**:\n    *   集中管理已索引列的元数据（表名、列名、索引类型、分词器、数据类型）。\n    *   支持多种索引类型：英文、中文、多语言、不分词。\n*   **查询处理引擎 (Query Processing Engine)**:\n    *   将自然语言查询转换为优化的 SQL。\n    *   集成多语言分词（与 StarRocks 索引分词保持一致）。\n    *   可选的同义词扩展。\n    *   支持字段筛选和布尔逻辑（`field:keyword`）。\n    *   模拟关键词打分机制用于排名。\n    *   自动生成跨表 SQL 查询。\n*   **查询优化模块 (Query Optimization Module)**:\n    *   对热门关键词的查询结果进行缓存（例如，使用 Redis）。\n    *   可能对结果集进行缓存以加速后续请求。\n    *   充分利用底层数据库的列式存储优化。\n*   **排名模块 (Elasticsearch 模拟)**:\n    *   在服务端计算伪 TF-IDF/BM25 分数。\n    *   根据文本内容计算词频（Term Frequency, TF）。\n    *   根据预计算的统计数据计算逆文档频率（Inverse Document Frequency, IDF）。\n*   **任务调度与并发控制**:\n    *   管理并发 SQL 执行任务，防止数据库过载。\n    *   可配置的并发度限制。\n*   **多数据库支持**:\n    *   采用可扩展的适配器模式，主要支持 StarRocks、Apache Doris 和 ClickHouse 作为后端，以 StarRocks 为核心。\n\n## 🏛️ 架构概览\n\nStarSeek 的详细架构，包括其分层设计、模块交互和部署考量，已在 `docs/architecture.md` 中详细阐述。\n\n[查看完整的架构设计文档](docs/architecture.md)\n\n## 🚀 构建与运行指南\n\n### 前置条件\n\n*   Go (版本 1.20.2 或更高)\n*   Git\n*   Docker (用于本地数据库设置，可选但推荐)\n*   StarRocks, Doris 或 ClickHouse 实例 (或 Docker 化设置)\n*   Redis 实例 (用于缓存)\n\n### 快速开始\n\n1.  **克隆仓库:**\n    ```bash\n    git clone https://github.com/turtacn/starseek.git\n    cd starseek\n    ```\n\n2.  **安装依赖:**\n    ```bash\n    go mod tidy\n    ```\n\n3.  **配置环境变量 (示例):**\n    创建 `.env` 文件或设置环境变量：\n    ```\n    STARSEEK_DB_TYPE=starrocks\n    STARSEEK_DB_HOST=localhost\n    STARSEEK_DB_PORT=9030\n    STARSEEK_DB_USER=root\n    STARSEEK_DB_PASSWORD=\n    STARSEEK_DB_NAME=your_database\n    STARSEEK_REDIS_ADDR=localhost:6379\n    STARSEEK_LISTEN_ADDR=:8080\n    STARSEEK_LOG_LEVEL=info\n    # 更多配置将在 docs/configuration.md 中详细说明\n    ```\n\n4.  **构建应用程序:**\n    ```bash\n    go build -o starseek ./cmd/starseek/main.go\n    ```\n\n5.  **运行应用程序:**\n    ```bash\n    ./starseek\n    ```\n    服务将在配置的地址（例如 `http://localhost:8080`）上监听。\n\n### Docker 设置 (StarRocks 示例)\n\n为了开发和测试，您可以使用 Docker Compose 启动一个 StarRocks 实例。\n```bash\n# 示例 docker-compose.yml (简化)\nversion: '3.8'\nservices:\n  starrocks-fe:\n    image: starrocks/starrocks:latest\n    ports:\n      - \"9030:9030\" # FE 查询端口\n      - \"8030:8030\" # HTTP 端口\n    environment:\n      - FE_SERVERS=\"127.0.0.1:9030\"\n    command: [\"/opt/starrocks/bin/start_fe.sh\"]\n  redis:\n    image: redis:6-alpine\n    ports:\n      - \"6379:6379\"\n````\n\n运行：`docker-compose up -d`\n\n## 🧪 代码片段与能力展示\n\n### 1. 索引注册 (API 端点)\n\n注册表的倒排索引列。这通常通过管理 API 完成。\n\n```go\n// 内部服务可能如何与索引注册中心交互的示例\n// (实际 API 可能是 HTTP POST 到 /api/v1/indexes/register)\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"github.com/turtacn/starseek/internal/application\"\n\t\"github.com/turtacn/starseek/internal/common/types/enum\"\n\t\"github.com/turtacn/starseek/internal/domain/index\"\n\t\"github.com/turtacn/starseek/internal/infrastructure/persistence/inmemory\"\n\t\"github.com/turtacn/starseek/internal/infrastructure/logger\"\n)\n\nfunc main() {\n\t// 初始化日志器\n\tl := logger.NewZapLogger()\n\t// 演示使用内存存储；实际持久化将使用数据库\n\trepo := inmemory.NewIndexMetadataRepository()\n\tservice := application.NewIndexService(repo, l)\n\n\tctx := context.Background()\n\n\t// 注册文档标题列\n\terr := service.RegisterIndex(ctx, index.RegisterIndexCommand{\n\t\tTableName:   \"documents\",\n\t\tColumnName:  \"title\",\n\t\tIndexType:   enum.IndexTypeChinese,\n\t\tTokenizer:   \"jieba\",\n\t\tDataType:    \"VARCHAR\",\n\t\tDescription: \"用于全文检索的文档标题\",\n\t})\n\tif err != nil {\n\t\tfmt.Printf(\"注册 documents.title 索引失败: %v\\n\", err)\n\t} else {\n\t\tfmt.Println(\"成功注册 documents.title 索引\")\n\t}\n\n\t// 注册产品描述列\n\terr = service.RegisterIndex(ctx, index.RegisterIndexCommand{\n\t\tTableName:   \"products\",\n\t\tColumnName:  \"description\",\n\t\tIndexType:   enum.IndexTypeEnglish,\n\t\tTokenizer:   \"standard\",\n\t\tDataType:    \"TEXT\",\n\t\tDescription: \"用于全文检索的产品描述\",\n\t})\n\tif err != nil {\n\t\tfmt.Printf(\"注册 products.description 索引失败: %v\\n\", err)\n\t} else {\n\t\tfmt.Println(\"成功注册 products.description 索引\")\n\t}\n\n\t// 列出所有已注册索引的示例\n\tallIndexes, err := service.ListIndexes(ctx, index.ListIndexesQuery{})\n\tif err != nil {\n\t\tfmt.Printf(\"列出索引失败: %v\\n\", err)\n\t} else {\n\t\tfmt.Println(\"\\n已注册索引:\")\n\t\tfor _, idx := range allIndexes {\n\t\t\tfmt.Printf(\"- 表: %s, 列: %s, 类型: %s, 分词器: %s\\n\",\n\t\t\t\tidx.TableName, idx.ColumnName, idx.IndexType.String(), idx.Tokenizer)\n\t\t}\n\t}\n}\n```\n\n### 2. 跨表全文检索 (HTTP API 示例)\n\n通过 `curl` 命令模拟搜索请求。StarSeek 服务将处理此请求。\n\n```bash\n# 在 'documents' 和 'articles' 表的 'title' 和 'content' 字段中搜索 \"人工智能\"\n# 请求可能类似于:\ncurl -X GET \"http://localhost:8080/api/v1/search?q=人工智能\u0026fields=title,content\u0026tables=documents,articles\u0026page=1\u0026pageSize=10\" \\\n     -H \"Content-Type: application/json\"\n\n# 示例响应 (简化):\n# {\n#   \"query\": \"人工智能\",\n#   \"results\": [\n#     {\n#       \"table\": \"documents\",\n#       \"rowId\": \"doc_123\",\n#       \"score\": 0.85,\n#       \"highlight\": {\n#         \"title\": \"关于\u003cB\u003e人工智能\u003c/B\u003e在教育领域的应用\",\n#         \"content\": \"近年来，\u003cB\u003e人工智能\u003c/B\u003e技术飞速发展...\"\n#       },\n#       \"data\": { /* 原始行数据 */ }\n#     },\n#     {\n#       \"table\": \"articles\",\n#       \"rowId\": \"art_456\",\n#       \"score\": 0.72,\n#       \"highlight\": {\n#         \"content\": \"深度学习是\u003cB\u003e人工智能\u003c/B\u003e的核心分支...\"\n#       },\n#       \"data\": { /* 原始行数据 */ }\n#     }\n#   ],\n#   \"totalHits\": 250,\n#   \"currentPage\": 1,\n#   \"pageSize\": 10\n# }\n```\n\n### 3. 特定字段搜索\n\n```bash\n# 在 'documents' 表中，在 'title' 字段搜索 \"starrocks\"，在 'content' 字段搜索 \"performance\"\ncurl -X GET \"http://localhost:8080/api/v1/search?q=title:starrocks AND content:performance\u0026tables=documents\u0026page=1\u0026pageSize=5\" \\\n     -H \"Content-Type: application/json\"\n```\n\n## 🤝 贡献指南\n\n我们欢迎社区贡献！如果您有兴趣改进 StarSeek，请查阅我们的：\n\n* [贡献指南](CONTRIBUTING.md)\n* [行为准则](CODE_OF_CONDUCT.md)\n\n---\n\n[English Version README.md](README.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturtacn%2Fstarseek","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fturtacn%2Fstarseek","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturtacn%2Fstarseek/lists"}