尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
SQL 接口
SQL 接口是一组只读的 ClickHouse 视图,覆盖租户的记忆、记忆历史、对话和请求账本。组织自己的 SQL 客户端、BI 工具或数据仓库作业,使用由 loom sql-access 创建的 ClickHouse 用户来读取这些视图。该用户只能读取这些视图,不能访问其他内容,并且每个视图只显示该用户被授予权限的组织和命名空间。
版本与兼容性
每个视图的名称都带有版本号:sql_v1_memories 是版本 1。列名、类型和含义是公开的约定:
v1视图可以新增列,但不会删除或重命名列,列的类型和含义也不会改变。- 会破坏这条规则的变更,会以
sql_v2_*视图的形式与v1并存发布。两者至少会同时提供一个版本,发布说明会指明即将移除的v1视图。 - 请按名称选择列:
SELECT *会包含新增的列。
视图
每个视图都在 Loom 的数据库中(默认为 loom,除非 LOOM_CH_DATABASE 指定了其他数据库),并带有标识列 org 和 namespace。sql_v1_memories、sql_v1_memory_history 和 sql_v1_agent_events 还带有 agent、user_id 和 session_id;sql_v1_conversations 带有 agent 和 user_id;sql_v1_usage_daily 带有 agent。联接可以匹配双方都带有的标识元组中的任意部分。
sql_v1_memories
每条记忆(标识加键)一行:即它的当前版本。已删除或已擦除的记忆不会出现,被拒绝的记忆也不会出现。其他状态会连同其 status 一起列出:除非特别要求,memory.list 会隐藏 duplicate、superseded 和 proposed 行,因此若要得到默认列表所显示的内容,请按 status = 'active' 过滤。超过 expires_at 的记忆在过期清理处理它之前,仍会带着其值列出,与 memory.list 的列出方式相同;若要得到 memory.search 所返回的内容,请加上 (expires_at IS NULL OR expires_at > now())。
| 列 | 含义 |
|---|---|
org, namespace, agent, user_id, session_id, run_id |
该记忆所属的对象以及写入它的运行(无则为 -) |
memory_key, memory_id, memory_type |
键、记忆的 id(与 version 合起来对应一个版本)、类型(fact、decision 等) |
value |
memory.get 所返回的值,被隐去时为 NULL |
value_withheld |
返回 value 时为 '',high 行为 sensitive,已脱敏的版本为 redacted |
content_sha256 |
值的 SHA-256,只要 value 为 NULL 它也为 NULL:较短密钥的哈希可以被猜出 |
version, status, confidence, pinned, tags |
与 memory.get 相同 |
sensitivity, source_class, actor |
标签、来源类别、写入它的令牌主体 |
created_at, updated_at, expires_at, valid_at, invalid_at |
写入时间和最近更改时间、过期时间、该事实开始成立和不再成立的时间 |
sql_v1_memory_history
每条记忆的每个版本一行,包括删除所产生的版本(status =
'tombstoned',并设置了 tombstoned_at)。被拒绝的版本不会出现。列与 sql_v1_memories 相同,但去掉了 expires_at、valid_at 和 invalid_at,并增加了 tombstoned_at。已脱敏的版本,以及曾被标为 high 的键的每个版本,其 value 和 content_sha256 都为 NULL:在敏感度清理给某行打标签之前的版本,保存的是同一个未加标签的值。
sql_v1_conversations
每个用户已存储的每个对话轮次一行:org、namespace、agent、user_id、thread_id、msg_id、role、content、tokens、run_id 和 ts(该轮次最近一次写入)。已删除或已被压缩掉的轮次(设置了 tombstoned_at)不会出现,已擦除的轮次连同其行一起消失。轮次不带敏感度标签,因此 content 按写入时的原样返回,与 conversation.get 返回某个线程的轮次的方式相同;跨线程列表对读起来属于 high 的文本所做的检查,是在 Loom 中运行的,而不是在 SQL 中。
sql_v1_agent_events
请求账本:每次 op 调用或 worker 一次处理一行,请求的 kind 为 ''。
列有 ts、org、namespace、agent、user_id、session_id、run_id、operation、kind、request_id、trace_id、latency_ms、success、error_code、status_class、memory_key、input_tokens、output_tokens、embedding_tokens、llm_calls、upstream_cost_usd(模型花费,单位为美元)、bytes_written、model、consumer、subject(发起调用的令牌主体)和 transport。其中不含请求参数。已擦除的终端用户的行,其 user_id 显示为 <erased>。
它保存今天之前完整的 31 个 UTC 日以及今天至今的数据;每条语句读取自己的 now()。窗口长度及其与 UTC 日的对齐方式是 v1 契约的一部分。
sql_v1_usage_daily
在同一窗口内,把 sql_v1_agent_events 按 UTC 的 day、org、namespace、agent、operation 和 kind 汇总:ops、errors、input_tokens、output_tokens、embedding_tokens、llm_calls、upstream_cost_usd、bytes_written、latency_sum_ms(与 ops 配合可求跨行的均值),以及 latency_p50_ms 和 latency_p95_ms,二者都是近似值且按行计算:它们不能跨行合并。除今天之外,每个 day 都是完整的一天。
读取的开销
视图会对其返回的行应用调用方的过滤条件,因此对 ts、day、thread_id 或 memory_key 的过滤只会缩小结果,而不会减少读取量。对 sql_v1_memories、sql_v1_memory_history 和 sql_v1_conversations 的每次读取,都会读取授权的整个范围:历史视图要对其中每个版本排序,对话视图要对其中每个轮次(包括内容)分组。这些开销随范围内存储的数据增长,范围过宽时可能超出下面的读取上限。对账本视图的每次读取,都会读取授权的整个范围在窗口内的数据:最早从窗口开始的那个月的月初算起,通常与窗口本身相差不大。更宽的授权(* 命名空间、--all)会读取更多。SQL 用户的读取上限(LOOM_CH_ANALYSIS_MAX_ROWS_TO_READ、_MAX_EXECUTION_S、_MAX_MEMORY_BYTES、_MAX_THREADS)适用于这次读取,因此繁忙的范围可能超出这些上限:请缩小授权,或调高这些设置(insights.query 共用它们),然后再次运行 loom sql-access grant,它会把这些设置写入 SQL 用户的配置档。早于窗口的事件不在该接口上;分析导出会把每日用量合计以哈希后的名称写入运维方的存储桶。除非 LOOM_RETENTION_AGENT_EVENTS_DAYS 设置了保留期,否则 loom.agent_events 本身没有 TTL。
视图从不显示的内容
记忆视图沿用 Loom 自身列表的规则(敏感度);对话视图按上文 conversation.get 的方式提供一个轮次。以下内容它们都不会显示:
high行的值及其哈希,无论在当前视图中,还是在历史记录里该键的每个版本中;- 已脱敏版本的值及其哈希;
- 被拒绝的记忆、已删除或已擦除的记忆,以及已删除的对话轮次;
- 在
loom.namespaces或loom.code_repos中被归类为restricted的命名空间的任何行,无论授予何种权限,自归类之时起即生效:Loom 会审计对受限命名空间的每次读取,而视图无法做到这一点; - 镜像(名称为
acl-加 24 位十六进制数字的命名空间)的任何行,无论授予何种权限:其中每个文档只会显示给其存储的权限列表所允许的读取者(文档来源),而视图无法检查这一点; - 这五个视图之外的表:令牌、授权、密钥、审计日志、文档、嵌入和请求参数;
- 会显示其他用户语句的
system表,例如system.query_log、system.mutations和system.processes。只有开启access_control_improvements.select_from_system_db_requires_grant(默认开启)时,ClickHouse 才会对没有授权的用户拒绝访问这些表,因此loom sql-access grant会以它设置了密码的每个用户登录,并在system.processes有响应时删除该用户。在 Loom 的数据库中,system.tables只列出这五个视图。
记忆视图和对话视图读取的表,正是擦除 saga 要从中删除数据、其残留普查要统计的表,因此被擦除的用户或命名空间的行会随这些表一起消失。账本视图保留其行,这些行不含内容:用户擦除会把该用户的 user_id 改写为 <erased>,与 loom.agent_events 中的做法相同。
数据新鲜度
这些视图在查询时读取 ClickHouse,不复制任何数据。Postgres 保存实时记忆(存储权威),loom.memory 和 loom.memory_versions 是每次提交之后发布的投影,每隔 LOOM_PG_PUBLISH_INTERVAL_MS(默认 250 ms)刷新一次。已提交的记忆写入在其刷新完成后会出现在 sql_v1_memories 和 sql_v1_memory_history 中,通常在大约一个间隔之内;如果某次投递因写入方停止而被遗留,则由投递 worker 负责发布,这可能需要更长时间。这些视图不会等待任何内容:memory.search 在超过 LOOM_PG_PROJECTION_WAIT_MS 后会返回 PROJECTION_BEHIND,而视图则直接返回 ClickHouse 中已有的数据。对话和请求账本则直接写入 ClickHouse。
访问
该接口的 SQL 用户是一个 ClickHouse 用户,仅对这五个视图拥有 SELECT 权限,没有其他授权,并使用设置配置文件 loom_sql_surface:
readonly = 1:语句只能修改final、join_use_nulls、group_by_use_nulls和transform_null_in这几项设置,它们不会改变任何视图返回的行,客户端也会自行发送它们(pg_clickhouse即是其一)。任何其他设置都可能绕过视图的过滤:溢出模式、additional_table_filters、FINAL下的 PREWHERE。- 无论服务器的默认值如何,配置文件都固定以下值:
apply_deleted_mask = 1和apply_patch_parts = 1(已删除的行保持隐藏),use_query_cache = 0和use_query_condition_cache = 0(二者都以语句文本为键,而所有用户共用同一文本),use_skip_indexes_if_final_exact_mode = 1、do_not_merge_across_partitions_select_final = 0和optimize_move_to_prewhere_if_final = 0(FINAL读取每个键的最新版本),所有溢出模式均为'throw'(read 和 timeout 及其_leaf形式,以及 set、transfer、join、sort、distinct、group by 和 result),send_logs_level = 'none',不提供内省函数,并且query_plan_filter_push_down = 0和enable_optimize_predicate_expression = 0,因此调用方的过滤条件只作用于视图返回的结果,绝不会作用于其他租户的行(对某个值报错的过滤条件会把该值引用出来); - 沿用
insights.query的上限,但不包括其结果上限,因为 SQL 客户端会读取完整的结果集:LOOM_CH_ANALYSIS_MAX_EXECUTION_S、_MAX_ROWS_TO_READ、_MAX_MEMORY_BYTES和_MAX_THREADS,以及同时执行的语句数_MAX_CONCURRENT。
每个视图以其定义者的权限运行(SQL SECURITY DEFINER,即执行迁移的用户),并且只放行 (org, namespace) 已由表 loom.sql_access 授予 currentUser()(即发送该语句的用户)的行。没有被授予任何行的用户什么也读不到,其他所有 ClickHouse 用户也一样,包括 Loom 自己的用户。
loom sql-access grant --user acme_bi --org acme --namespaces support,research
loom sql-access grant --user acme_bi --org acme --namespaces '*' # every namespace of acme
loom sql-access grant --user ops_bi --all # the whole deployment
loom sql-access grant --user acme_bi --org acme --namespaces support --rotate
loom sql-access list
loom sql-access revoke --user acme_bi
grant在用户不存在时创建该用户,并只打印一次密码;Loom 不保留副本。--org与--all互斥,--all不接受--namespaces。再次运行时,会把该用户的范围设置为恰好是命令中指定的内容:不再指定的命名空间,会在新的行到达提供读取的副本后停止显示;revoke会立即终止登录。--rotate会打印新密码。当密码之后的某一步失败时,grant会给出提示;请加上--rotate再运行一次。--all适用于数据只属于一个 org 的部署。在共享部署上,应为每个租户分别授予各自的 org。grant会拒绝包含受限命名空间的范围,也会拒绝可能涵盖受限命名空间的通配符,而该命名空间仅由代码仓库配置标记为受限:视图读不到该配置,因此请使用服务器的配置运行该命令。若某个命名空间在授权之后才被设为受限,而该授权涵盖它,则它仍在该授权的视图中:list会列出每个这样的授权,请改为按名称指定其他命名空间,并以退出码 2 退出。revoke先删除范围行,再删除用户。授权中指定的命名空间在revoke删除该行之前视为在用:其名称不会交给新的所有者,对它的首次写入会将其注册为无所有者。*授权不指定任何命名空间:它读取该 org 的所有命名空间,包括之后创建的,因此绝不要对注册用户共享的 org(LOOM_SELF_SIGNUP_ORG)授予这种权限。- 该命令以
LOOM_CH_USER身份运行,它需要访问管理权限:CREATE USER、ALTER USER、DROP USER、CREATE SETTINGS PROFILE和ALTER SETTINGS PROFILE,对五个视图的SELECT ... WITH GRANT OPTION,以及SHOW USERS和对system.users与system.settings_profile_elements的读取权限。它会拒绝已被某个不使用loom_sql_surface配置文件的 ClickHouse 用户占用的名称,也会拒绝 Loom 自己的用户(LOOM_CH_USER、读取用户、loom_analyst、default)。 - 请使用
revoke删除用户,不要用DROP USER:在revoke重写之前,其范围行仍保持授权状态,之后若有同名且对这些视图拥有SELECT权限的用户,就能读到这些行。
查询
在组织自己的 Postgres 中查询,请参阅从 Postgres 查询 Loom。
SELECT memory_key, value, updated_at
FROM loom.sql_v1_memories
WHERE namespace = 'support' AND status = 'active'
ORDER BY updated_at DESC
LIMIT 20;
SELECT day, sum(upstream_cost_usd) AS spend
FROM loom.sql_v1_usage_daily
WHERE day >= toDate(now(), 'UTC') - 30
GROUP BY day ORDER BY day;