Lakebase DX: a native-search helper, grants bootstrap, and graduating proven cookbook patterns

未关闭
  • 哪里不对？
#557 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 3 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
35/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
活跃
技术栈
fastapi, postgresql, python, typescript
领域
backend-api-design, databases, developer-experience

调研方向

首先在内部确认 Lakebase Search 的 GA/接口，然后将提议的形态与 AppKit 现有的 ai-search helper 进行比较。在将请求拆分为范围明确的贡献之前，检查 cookbook 中的 migrations_runner.py 和 apps/lakebase-fastapi 模式，以及提议的入口点 lakebase({ branch })。完成标准是：为 search、grants、migrations、可复用的 scaffolding 和 branch 选择确定一个经 maintainer 批准的范围。

由索引模型根据 Issue 内容生成。

描述

Field feedback from building an app on @databricks/appkit 0.66.1 + Lakebase. First, credit where it's due — these saved real work: the Lakebase plugin's auto OAuth refresh, asUser(req) OBO per-user pools, and exposeAsAgentTool (read-only SQL classifier). And ai-search is great for Databricks Vector Search.

The gaps below are all Lakebase-specific. Each is verified against 0.66.1; happy to contribute PRs.

1. A lakebaseSearch() helper (Lakebase-native BM25 + vector ANN)

ai-search targets Vector Search (managed indexes), not Lakebase's native lakebase_bm25 + lakebase_ann (halfvec) indexes. There's no helper for those, so devs write raw SQL and hit avoidable traps:

  • the bm25 regclass resolves against search_path, so from an app you must schema-qualify it (to_bm25query(..., 'app.providers_bm25')) or get relation "providers_bm25" does not exist;
  • plainto_tsquery, not to_tsquery (the latter crashes on multi-word input);
  • halfvec(1024) cosine + ai_query('databricks-gte-large-en', text) embeddings.

Proposed API, mirroring ai-search's shape but pointing at Lakebase indexes:

lakebaseSearch({
  indexes: { providers: { table: "app.providers", bm25Index: "app.providers_bm25",
    annIndex: "app.providers_ann", textColumn: "search_tsv",
    embeddingColumn: "embedding", mode: "hybrid" } }
})
// appkit.lakebaseSearch.query("providers", { text: "home health", numResults: 5 })

(Worth confirming Lakebase Search GA/interface internally before building.)

2. Service-principal grants bootstrap + a clear grant error

The app SP needs databricks_create_role(...) + explicit GRANTs; today that's manual copy-paste, and a missing grant surfaces as a generic permission denied. Proposal: a ensureServicePrincipalGrants(spClientId, { schema, tables }) helper (+ an optional apps init grants.sql scaffold), and map Postgres permission denied → "the app SP lacks GRANT X on Y".

3. Graduate proven Lakebase patterns from the cookbook into AppKit

databricks-solutions/lakebase-cookbook already has battle-tested code for these — the ask is to bring them into the toolkit:

  • Migrations: an appkit migrate wrapping the cookbook's checksum/drift migrations_runner.py, made multi-SP-ownership aware (CREATE INDEX IF NOT EXISTS still fails if another SP owns the table).
  • Synced-read + writable-ops scaffold: the apps/lakebase-fastapi pattern (read-only synced mirror + writable ops table + derive-state-by-join) as a reusable helper/template.
  • Dev-branch selection: a lakebase({ branch }) config so an app targets a dev branch vs production without hand-editing endpoint paths.
主要语言
TypeScript
星标
119
派生
36
平均合并
4 天 16 小时
30 天内合并 PR
37

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

databricks/appkit 的其他 Issue

查看 databricks/appkit 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。