列出数据库里所有可访问的 schema（数据分区），带每个 schema 的表数量和总体积。探索一个陌生库时先调这个。

列出某个 schema 下的表，带表注释、估算行数和体积。可用 name_contains 按表名过滤。注意有的 schema 有 600 多张表，建议配合过滤条件使用，或者直接用 search_metadata。

按关键词搜索数据库的物理结构：表名、表注释、列名、列注释。适用于「我知道大概的表名或列名，帮我定位」这类需求，或者想看某张表的注释说明。 ★ 找变量请优先用 find_variables——它搜的是变量协调层（变量定义、问卷原文、值标签），带词干还原和相关性排序，对「有没有 xx 相关的变量」这类语义问题效果好得多。本工具搜的是物理结构，只做精确子串匹配，没有同义词和词干处理。

查看一张表的完整结构：所有列的名字、类型、是否可空、以及列注释；外加主键、外键、索引和估算行数。写 SQL 之前必须先调这个确认列名。

从一张表里抽几行真实数据看看。用来确认取值形态——特别是缺失值编码（96/97/98/99 之类）和字段的实际格式。

执行一条只读 SQL 查询并返回结果。只接受 SELECT / WITH / EXPLAIN 等只读语句，单次最多返回 500 行，超时 30 秒。表名列名含大写字母时记得加双引号。统计总体指标时请使用表里的抽样权重列加权。

列出数据库里有哪些调查项目（CSES / DHS / HSES / LFS 等），带调查数量、覆盖国家、年份范围、表数和体积。会明确区分三种状态：已入库可读 / 数据在库但当前角色无权限 / 根本没入库——被问到某个调查有没有时，按这个区分如实回答。

列出某个调查包含哪些 section（模块/章节）。返回两种：physical_sections 是数据的分表方式（CSES 的 EC/ED/HH/HO/VL，DHS 的 WM/CH/BR/PR 等，带含义说明）；questionnaire_sections 是问卷文档的章节。两者不是一一对应的。

【找变量的主要工具】按语义搜索整个数据库的变量元数据（变量定义、问卷原文、变量标签、值标签）。 ★ 调用前必须把概念展开成多个英文同义词——元数据是英文的，中文关键词搜不到任何东西，而且同一概念在不同调查里叫法不同。 例：使用者问「有没有教育年限相关的变量」，应传 keywords=["education","schooling","grade","attainment","years attended","diploma","degree"]，这样才能同时命中 years_attended_school 和 highest_education_level。 宁可多给同义词也不要少给。搜索自带词干还原，不必列单复数词形。第一次结果不理想就换一批同义词再搜，不要直接说没有。

统计一个变量：有多少非空回答、排除缺失值编码后的有效回答、取值分布（带码值含义）、数值型的描述统计（均值/中位数/标准差）、以及可用的抽样权重列。缺失值编码（98=不知道、99=缺失这类）会根据元数据自动识别并单独报告，不是靠猜 96-99；元数据里查不到值标签时会明确说明无法判断。

把一个变量画成图，图会直接显示在网页上。kind='auto' 时自动选择：类别型画条形图（用码值含义当标签），连续数值画直方图。缺失值编码默认排除。传 weight 参数可按抽样权重加权——调查数据展示总体分布时应该加权。

读出数据库自带的使用指南（public._guide）、表目录（public._catalog）和未解决的数据问题（public.data_issues）。 ★ 这是数据库维护者手写的权威文档，包含跨数据集比较的关键陷阱：哪些列是清洗过的（CP 前缀）、缺失值哨兵编码、不同年代数据集的编码差异、表之间的连接键和坑。 涉及 MICS 数据、或者要做跨数据集/跨国比较、或者要连接多张表时，先调这个工具读一遍。它和其他工具的推断性说明冲突时，以它为准。

重建本地元数据索引。数据库里新增了调查/变量之后，或者刚开通了新 schema 的权限之后，需要重建一次搜索才能找到新内容。耗时约 10 秒到 2 分钟，取决于数据量。

查看本地元数据索引的状态：建立时间、条目数、各调查的覆盖情况。