LaminDB 数据管理实战查询、过滤、搜索与流式访问指南scientific-agent-skills【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本文基于 LaminDB 数据管理参考文档并结合 lamindb 技能包 及其 核心概念、注释与校验、部署配置 等配套文档系统讲解 LaminDB 这一系谱原生lineage-native生物数据湖仓中最为高频的一类操作如何查看注册表、检索单条记录、按元数据与特征过滤、跨表遍历、组合逻辑查询、全文搜索以及对超大文件进行流式读取与缓存管理。读完本文你将能够像操作数据库一样精确地查找任意实验数据、按细胞类型/基因/处理条件等特征快速圈定数据集并安全地处理远超内存容量的组学数据文件。本文配图展示了 LaminDB 的核心工作闭环左侧 CURATION 阶段完成存储初始化lamin init、运行跟踪ln.track()与数据校验AnnDataCurator、Bionty 细胞类型右侧 QUERY LINEAGE 阶段通过view_lineage()与各 transform 步骤追溯数据血缘底部 OUTPUTS 输出版本化 Artifact 与按批次组织的 Collection——这正是本文将要展开的查询与数据组织能力的全景。注册表概览一眼看清仓库里有什么LaminDB 把数据集Artifact、代码Transform、运行记录Run、用户User、特征Feature、模式Schema等实体分别登记在独立的注册表Registry中。管理数据的第一步就是掌握查看这些注册表的方法import lamindb as ln # 查看跨模块的所有注册表 ln.view() # 查看最新 100 条 Artifact 记录以 pandas DataFrame 形式返回 ln.Artifact.to_dataframe() # 查看其他注册表 ln.Transform.to_dataframe() ln.Run.to_dataframe() ln.User.to_dataframe()这里需要说明to_dataframe()的作用它把注册表内容物化为 pandas DataFrame既方便在 Notebook 中直接浏览也便于后续交给 pandas 做二次统计。ln.view()则返回一个包含所有注册表及其记录数的总览视图适合在一开始快速评估实例里积累了哪些类型的数据。与数据管理能力对应lamindb 技能包 中把 LaminDB 的能力划分为六大部分其中Data Management and Querying正是本文的核心注册表浏览与 lookup 自动补全、单记录检索get/one/one_or_none、比较运算符过滤__gt、__lte、__contains、__startswith、特征查询、双下划线跨表遍历、全文搜索、ln.Q逻辑组合以及不落内存的大数据流式读取。Lookup小注册表的快速自动补全访问对于记录数少于 10 万条的注册表LaminDB 提供lookup()方法生成一个 Lookup 对象把记录的 name/标识符映射为可自动补全的属性IDE 中直接输入records.即可看到候选# 创建 lookup records ln.Record.lookup() # 按名称访问IDE 中启用自动补全 experiment_1 records.experiment_1 sample_a records.sample_aLookup 同样适用于生物本体ontology注册表——这是 LaminDB 与 Bionty 集成后的独特优势例如按细胞类型名称直接取到规范化记录import bionty as bt cell_types bt.CellType.lookup() t_cell cell_types.t_celllookup()适合记录量可控、名称固定且频繁引用的场景当注册表规模超过 10 万条时LaminDB 不建议继续使用自动补全方式而应改用下面的filter/get精确查询。更多关于 Bionty 本体注册表基因、细胞类型、组织、疾病等的 lookup 与层级关系操作可参考 本体管理文档。单记录检索get / one / one_or_none / first精确取一条记录是日常最常用的操作。LaminDB 提供了四种语义不同的方法按结果唯一性要求从严格到宽松排列使用 get()必须恰好命中一条# 按 UID 获取 artifact ln.Artifact.get(aRt1Fact0uid000) # 按字段获取 artifact ln.Artifact.get(keydata/experiment.h5ad) user ln.User.get(handleresearcher123) # 按本体 ID 获取Bionty 注册表 cell_type bt.CellType.get(ontology_idCL:0000084)get()的语义是恰好一条零条或多条匹配都会直接抛错因此它适合用在对唯一性有信心的字段UID、唯一 key、handle、ontology_id上。使用 one() 和 one_or_none()从 QuerySet 收口当查询经由filter()产生一个 QuerySet 时需要显式收口成单条记录# 恰好一条0 条或多于 1 条都会报错 artifact ln.Artifact.filter(keydata.csv).one() # 至多一条0 条返回 None多于 1 条报错 artifact ln.Artifact.filter(keymaybe_data.csv).one_or_none() # 取第一条匹配即使有多条也不报错 artifact ln.Artifact.filter(suffix.h5ad).first()三者适用场景各不相同one()用于强校验场景比如流水线上游确认 key 唯一one_or_none()常用于存在性判断——配合is not None即可安全分支first()则用于随便取一条最新/最早的宽松需求。在 核心概念文档 的 Artifact 检索小节中可以看到get(key...)、get(UID)、filter(suffix...).first()是官方推荐的三条标准取数路径与本文完全一致。过滤数据filter() 与比较运算符filter()返回惰性 QuerySet支持传入多个关键字参数默认为 AND 逻辑以及 Django 风格的双下划线比较运算符# 基础过滤 artifacts ln.Artifact.filter(suffix.h5ad) artifacts.to_dataframe() # 多条件AND 逻辑 artifacts ln.Artifact.filter( suffix.h5ad, created_byuser ) # 比较运算符 ln.Artifact.filter(size__gt1e6).to_dataframe() # 大于 ln.Artifact.filter(size__gte1e6).to_dataframe() # 大于等于 ln.Artifact.filter(size__lt1e9).to_dataframe() # 小于 ln.Artifact.filter(size__lte1e9).to_dataframe() # 小于等于 # 范围查询 ln.Artifact.filter(size__gte1e6, size__lte1e9).to_dataframe()size是 Artifact 的内置元数据字段文件字节数created_by可以传 User 记录对象本身做等值过滤。比较运算符是 LaminDB 查询语法的基石后面的跨表遍历、特征查询全部复用同一套双下划线约定。文本与字符串查询LaminDB 为字符串字段提供了丰富的匹配语义覆盖精确、包含、忽略大小写、前缀、后缀与列表成员判断# 精确匹配 ln.Artifact.filter(descriptionExperiment 1).to_dataframe() # 包含区分大小写 ln.Artifact.filter(description__containsRNA).to_dataframe() # 忽略大小写的包含 ln.Artifact.filter(description__icontainsrna).to_dataframe() # 前缀匹配 ln.Artifact.filter(key__startswithexperiments/).to_dataframe() # 后缀匹配 ln.Artifact.filter(key__endswith.csv).to_dataframe() # IN 列表 ln.Artifact.filter(suffix__in[.h5ad, .csv, .parquet]).to_dataframe()实际项目中key__startswithscrna/2025/oct/这类前缀查询配合层级化 key见后文用 Key 组织数据使用频率极高可以低成本实现目录浏览效果。特征查询按注释元数据圈定数据集这是 LaminDB 最具价值的查询能力之一。除了内置字段Artifact 还可以通过Feature注册表获得类型化注释字段如 cell_type、treatment、tissue随后这些字段可以直接出现在filter()中# 按特征值过滤 ln.Artifact.filter(cell_typeT cell).to_dataframe() ln.Artifact.filter(treatmentDMSO).to_dataframe() # 把特征列合并进输出 ln.Artifact.filter(treatmentDMSO).to_dataframe(includefeatures) # 嵌套字典字段访问 ln.Artifact.filter(study_metadata__assayRNA-seq).to_dataframe() ln.Artifact.filter(study_metadata__detail1123).to_dataframe() # 注释状态判断 ln.Artifact.filter(cell_type__isnullFalse).to_dataframe() # 已注释 ln.Artifact.filter(treatment__isnullTrue).to_dataframe() # 缺失注释几个要点includefeatures会把命中的特征键值对一并展平到 DataFrame便于直接查看注释详情study_metadata__detail1这类写法支持对字典型元数据的深层取值.T、多级嵌套如study_metadata__assay__type均可继续叠加在 核心概念文档 的嵌套字典特征一节给出了study_metadata__assay__typeRNA-seq的对应示例特征查询的前提是特征已定义并完成注释。特征的定义方式为ln.Feature(namecell_type, dtypestr).save()dtype 支持int、float、bool、date、str乃至 Bionty 注册表类型如dtypebt.CellType详见 注释与校验文档。跨注册表遍历双下划线语法Django 的双下划线__语法允许在一条查询里穿过外键关系直达关联注册表的字段——这是 LaminDB 基于 Django ORM 实现的核心能力# 按创建者 handle 找 Artifact ln.Artifact.filter(created_by__handleresearcher123).to_dataframe() ln.Artifact.filter(created_by__handle__startswithtest).to_dataframe() # 按 transform产生数据的代码名称找 Artifact ln.Artifact.filter(transform__namepreprocess.py).to_dataframe() # 通过 Schema 找包含特定基因的数据集 cd8a bt.Gene.get(symbolCD8A) schemas_with_cd8a ln.Schema.filter(genescd8a) ln.Artifact.filter(schemas__inschemas_with_cd8a).to_dataframe() # 按运行参数找 Run ln.Run.filter(params__learning_rate0.01).to_dataframe() ln.Run.filter(params__downsampleTrue).to_dataframe() # 按所属项目找 Artifact project ln.Project.get(nameCancer Study) ln.Artifact.filter(projectsproject).to_dataframe()可以看出双下划线可以无限叠加created_by__handle__startswith并且把filter的两个用法统一了起来传记录对象等值/成员判断如projectsproject、schemas__in...与传字段路径如transform__name。结合 核心概念文档 中的系谱查询示例这套语法还支持ln.Run.filter(inputsinput_artifact)与ln.Artifact.filter(run__inruns)这样的由输入找输出溯源查询是数据血缘追溯的主力工具。排序order_byQuerySet 通过order_by()指定排序字段字段名前加负号表示降序# 升序 ln.Artifact.filter(suffix.h5ad).order_by(created_at).to_dataframe() # 降序 ln.Artifact.filter(suffix.h5ad).order_by(-created_at).to_dataframe() # 多字段排序 ln.Artifact.order_by(-created_at, size).to_dataframe()多字段排序中排在前面的字段优先级更高order_by(-created_at)是最近产生的数据类需求的标准写法配合[:10]切片即可实现最近 10 条。高级逻辑查询ln.Q 组合 AND / OR / NOT当单一字段条件无法表达需求时使用ln.Q()构造条件对象再通过|OR、AND、~NOT自由组合# OR 条件 artifacts ln.Artifact.filter( ln.Q(suffix.jpg) | ln.Q(suffix.png) ).to_dataframe() # 复杂 OR每个 Q 内部可含多个条件AND artifacts ln.Artifact.filter( ln.Q(suffix.h5ad, size__gt1e6) | ln.Q(suffix.csv, size__lt1e3) ).to_dataframe() # NOT 排除 artifacts ln.Artifact.filter( ~ln.Q(suffix.tmp) ).to_dataframe() # 排除特定创建者 artifacts ln.Artifact.filter( ~ln.Q(created_by__handletestuser) ).to_dataframe() # 综合组合((suffixh5ad OR csv) AND size1e6 AND 非 test* 用户) artifacts ln.Artifact.filter( (ln.Q(suffix.h5ad) | ln.Q(suffix.csv)) ln.Q(size__gt1e6) ~ln.Q(created_by__handle__startswithtest) ).to_dataframe()注意单个filter()内多个关键字参数天然是 AND因此只有出现 OR 或 NOT 时才需要显式使用ln.Q。组合表达式务必用括号明确优先级避免语义歧义。全文搜索search()search()对注册表字段执行全文搜索适合不知道精确字段值、只知道关键词的发现式场景# 基础搜索 ln.Artifact.search(iris).to_dataframe() ln.User.search(smith).to_dataframe() # 在特定本体注册表中搜索 bt.CellType.search(T cell).to_dataframe() bt.Gene.search(CD8).to_dataframe()与filter的精确语义不同search返回按相关度排序的匹配结果天然适合交互式浏览。在 本体管理文档 中可以看到bt.Gene.search(CD8, organismhuman)还支持 organism 参数实现物种限定搜索。QuerySet惰性求值与多种物化方式QuerySet 是惰性的——构建查询时不会触碰数据库只有求值动作才真正执行 SQL# 创建查询不触发数据库访问 qs ln.Artifact.filter(suffix.h5ad) # 多种求值方式 df qs.to_dataframe() # 物化为 pandas DataFrame list_records list(qs) # 物化为 Python 列表 count qs.count() # 仅计数 exists qs.exists() # 布尔判断 # 迭代 for artifact in qs: print(artifact.key, artifact.size) # 切片 first_10 qs[:10] next_10 qs[10:20]掌握惰性特性有实际收益可以先拼装复杂条件而不产生任何数据库开销最后再一次性求值exists()与count()则是轻量检查比物化整表高效得多。链式过滤增量构建查询QuerySet 支持在原有基础上继续调用filter、order_by逐层收紧条件# 增量构建 qs ln.Artifact.filter(suffix.h5ad) qs qs.filter(size__gt1e6) qs qs.filter(created_at__year2025) qs qs.order_by(-created_at) # 执行 results qs.to_dataframe()这与先建宽查询、按需逐层加条件的调试习惯天然契合——任何一步都可以先count()看看当前命中量再决定是否继续收紧。流式处理大型数据集对于无法整体载入内存的大文件LaminDB 提供三条渐进式的访问路径文件流open()# 打开文件流 artifact ln.Artifact.get(keylarge_file.csv) with artifact.open() as f: # 分块读取 chunk f.read(10000) # 读取 10KB # 处理该块open()返回底层文件句柄按字节流分块消费几乎不占用内存。数组切片backed()对 Zarr、HDF5、AnnData 等数组格式backed()返回磁盘映射memory-mapped视图只加载被切片的区块# 获取 backed 视图而不加载全量数据 artifact ln.Artifact.get(keylarge_data.h5ad) adata artifact.backed() # 返回 backed AnnData # 按需切片 subset adata[:1000, :] # 前 1000 个细胞 genes_of_interest adata[:, [CD4, CD8A, CD8B]] # 分批流式处理 for i in range(0, adata.n_obs, 1000): batch adata[i:i1000, :] # 处理批次迭代器iterator()对大批量小文件如 FASTQiterator()按批次取回记录并配合cache()落盘# 增量处理大集合 artifacts ln.Artifact.filter(suffix.fastq.gz) for artifact in artifacts.iterator(chunk_size10): # 每次处理 10 条 path artifact.cache() # 分析文件流式策略与 部署配置文档 中Use backed mode for large arrays的性能建议一致能用 backed 就不load()能用 iterator 就不一次性遍历。聚合与统计Django ORM 的聚合能力在 QuerySet 上同样可用# 计数 ln.Artifact.filter(suffix.h5ad).count() # 去重取值 ln.Artifact.values_list(suffix, flatTrue).distinct() # 聚合需要 Django ORM 知识 from django.db.models import Sum, Avg, Max, Min # 所有 Artifact 的总大小 ln.Artifact.aggregate(Sum(size)) # 按后缀分组的平均大小 ln.Artifact.values(suffix).annotate(avg_sizeAvg(size))values_list(..., flatTrue).distinct()适合快速枚举仓库里都有哪些格式annotate分组统计则适合生成存储用量报表。缓存与性能管理云端存储的数据在本地有缓存层合理管理缓存能显著提升反复访问的性能# 查看缓存目录 ln.settings.cache_dir# 设置缓存目录 lamin cache set /path/to/cache # 查看当前缓存配置 lamin cache get# 清除单个 Artifact 的缓存 artifact.delete_cache() # 获取缓存路径未缓存则自动下载 path artifact.cache() # 判断是否已缓存 if artifact.is_cached(): path artifact.cache()缓存策略要点与 部署配置文档 的Cache Configuration章节对应ln.settings.cache_dir是 Python 侧查看缓存路径的方式lamin cache set/get是 CLI 侧的配置方式artifact.cache()是幂等的已缓存直接返回本地路径未缓存则下载后再返回适合在分析前预热常用参考数据多用户共享机器可通过系统级 settings 文件lamindb_cache_path统一指定共享缓存目录并注意目录权限设置缓存写满时可用shutil.rmtree(ln.settings.cache_dir)整体清空该操作会删除全部本地缓存需谨慎。用 Key 组织数据层级化命名规范Artifact 的key是它在存储中的逻辑路径采用层级化命名是 LaminDB 官方强烈推荐的组织方式# 层级化组织 ln.Artifact(data.h5ad, keyproject/experiment/batch1/data.h5ad).save() ln.Artifact(data.h5ad, keyscrna/2025/oct/sample_001.h5ad).save() # 按前缀浏览 ln.Artifact.filter(key__startswithscrna/2025/oct/).to_dataframe() # 在 key 中内置版本号内置版本机制之外的备选方案 ln.Artifact(data.h5ad, keydata/processed/v1/final.h5ad).save() ln.Artifact(data.h5ad, keydata/processed/v2/final.h5ad).save()层级 key 的价值在于key__startswith前缀过滤天然实现目录树浏览无需额外建索引而project/experiment/batch三段式命名与 lamindb 技能包 中Organize with keys: Structure artifact keys hierarchically的关键原则一致。需要提醒的是官方原则是用内置版本机制而非在 key 里塞版本号key 内版本化仅作为兼容旧工作流的备选。Collections把相关 Artifact 打包成群Collection 是版本化、不可变immutable的 Artifact 集合适合表达跨三个批次组成的完整数据集这类整体概念# 创建 collection collection ln.Collection( [artifact1, artifact2, artifact3], keyscrna/batch_1_3, descriptionComplete dataset across three batches ).save() # 访问成员 for artifact in collection.artifacts: print(artifact.key) # 查询 collections ln.Collection.filter(key__containsbatch).to_dataframe()Collection 的不可变性保证了数据集版本可复现——一旦发布成员集合不可再被改动这与版本化、不可变的数据集打包定位完全吻合。常见查询模式速查把上述能力组合起来即可覆盖绝大多数日常需求# 最近产生的 10 条数据 ln.Artifact.order_by(-created_at)[:10].to_dataframe() # 我创建的数据 me ln.setup.settings.user ln.Artifact.filter(created_byme).to_dataframe() # 大文件1GB按大小降序 ln.Artifact.filter(size__gt1e9).order_by(-size).to_dataframe() # 某年某月的数据 from datetime import datetime ln.Artifact.filter( created_at__year2025, created_at__month10 ).to_dataframe() # 已通过校验且带细胞类型注释的数据集 ln.Artifact.filter( is_validTrue, cell_type__isnullFalse ).to_dataframe(includefeatures)最佳实践清单综合 数据管理参考文档、核心概念文档 与 lamindb 技能包 的关键原则沉淀出以下实操准则先过滤后加载先查询元数据确认命中范围后再访问文件内容避免无谓下载善用惰性 QuerySet复杂条件分步filter()拼接每一步先用count()/exists()验证命中量大文件必须流式open()按块读、backed()按需切片、iterator()分批处理不要整体load()进内存层级化 key统一采用project/experiment/batch/file三段式命名配合key__startswith实现目录式浏览发现式场景用 search不知道确切字段值时用search()做全文相关度检索缓存策略化按工作集大小设置缓存目录常用参考数据提前cache()预热提前定义特征在注释之前把 Feature 注册表建好特征查询才有数据可查用 Collection 聚合相关 Artifact 打包成 Collection享受版本化、不可变的数据集语义显式排序用order_by(created_at)/order_by(-created_at)保证检索结果稳定可复现存在性预检用exists()或one_or_none()先判断再取值避免get()/one()因零条或多条匹配抛错。以上查询模式在 lamindb 技能包 的Use Case 2: Building a Queryable Data Lakehouse中得到了端到端印证先批量注册多个实验的 AnnData 与特征注释再通过key__startswithscrna/叠加tissuePBMC、conditiontreated一次圈定全部目标数据集最后逐条load()分析——这正是本文全部查询能力的综合应用场景。配合 本体管理、注释与校验 与 部署配置 文档即可在真实科研流水线中落地一套可查询、可追溯、可复现的数据管理基础设施。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考