As páginas sem tradução abrem em inglês e são identificadas como inglês.
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Superfície SQL
A superfície SQL é um conjunto de views do ClickHouse somente leitura sobre as memórias de um tenant, o histórico de memórias, as conversas e o registro de requisições. O cliente SQL, a ferramenta de BI ou o job de warehouse de uma organização lê essas views com um usuário do ClickHouse criado por loom sql-access. Esse usuário lê as views e nada além delas, e cada view mostra apenas as organizações e os namespaces aos quais o usuário recebeu acesso.
Versão e compatibilidade
O nome de cada view carrega a sua versão: sql_v1_memories é a versão 1. Os nomes, os tipos e os significados das colunas são um contrato público:
- Uma view
v1pode ganhar colunas. Ela nunca perde nem renomeia uma coluna, e uma coluna nunca muda de tipo nem de significado. - Uma mudança que quebraria essa regra é publicada como uma view
sql_v2_*ao lado dav1. As duas permanecem disponíveis por pelo menos uma versão, e as notas de versão indicam qual viewv1será removida. - Selecione as colunas pelo nome:
SELECT *inclui as colunas adicionadas.
Visões
Toda visão fica no banco de dados do Loom (loom, a menos que LOOM_CH_DATABASE indique outro) e traz as colunas de identidade org e namespace. sql_v1_memories, sql_v1_memory_history e sql_v1_agent_events também trazem agent, user_id e session_id; sql_v1_conversations traz agent e user_id; sql_v1_usage_daily traz agent.
Um join pode casar qualquer parte da tupla de identidade
que os dois lados tenham.
sql_v1_memories
Uma linha por memória (identidade e chave): a versão atual dela. Uma memória excluída ou apagada não aparece, e uma rejeitada também não. Os demais status aparecem com o respectivo status:
memory.list oculta as linhas duplicate, superseded e proposed a menos que sejam pedidas, então filtre
por status = 'active' para obter o que uma listagem padrão mostra. Uma memória que passou do expires_at aparece
com o seu valor até a varredura de expiração agir sobre ela, como memory.list a lista; acrescente
(expires_at IS NULL OR expires_at > now()) para obter o que memory.search serve.
| Coluna | Significado |
|---|---|
org, namespace, agent, user_id, session_id, run_id |
a quem a memória pertence e a execução que a escreveu (- quando não há) |
memory_key, memory_id, memory_type |
a chave, o id da memória (junto com version, identifica uma versão) e o tipo (fact, decision, ...) |
value |
o valor como memory.get o serve, ou NULL quando retido |
value_withheld |
'' quando value é servido, sensitive para uma linha high, redacted para uma versão redigida |
content_sha256 |
o SHA-256 do valor, NULL sempre que value for NULL: o hash de um segredo curto pode ser adivinhado |
version, status, confidence, pinned, tags |
como em memory.get |
sensitivity, source_class, actor |
o rótulo, a classe de procedência e o subject do token que a escreveu |
created_at, updated_at, expires_at, valid_at, invalid_at |
quando foi escrita e alterada pela última vez, quando expira, quando o fato passou a ser verdadeiro e deixou de ser |
sql_v1_memory_history
Uma linha por versão de cada memória, incluindo a versão de uma exclusão (status =
'tombstoned', com tombstoned_at preenchido). Uma versão rejeitada não aparece. As colunas são as de
sql_v1_memories, sem expires_at, valid_at e invalid_at, mais tombstoned_at.
value e content_sha256 são NULL para uma versão redigida e para toda versão de uma chave
que algum dia recebeu o rótulo high: a versão anterior à varredura de sensibilidade que rotulou uma linha
contém o mesmo valor sem rótulo.
sql_v1_conversations
Uma linha por turno de conversa armazenado de cada usuário: org, namespace, agent, user_id,
thread_id, msg_id, role, content, tokens, run_id e ts (a escrita mais recente do turno). Um turno excluído ou compactado (tombstoned_at preenchido) não aparece, e um apagado
some junto com a sua linha. Um turno não tem rótulo de sensibilidade, então content é servido como foi escrito,
como conversation.get serve os turnos de uma thread; a verificação das listagens entre threads, que detecta texto
que parece high, roda no Loom, não no SQL.
sql_v1_agent_events
O registro de requisições: uma linha por chamada de op ou passagem de worker, com kind '' para uma requisição.
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 (gasto com modelos em USD), bytes_written, model, consumer, subject
(o subject do token que fez a chamada) e transport. Os argumentos da requisição não estão nele. As linhas de um
usuário final apagado trazem user_id como <erased>.
Ele contém os 31 dias UTC completos anteriores a hoje e o dia de hoje até agora; cada instrução lê o seu próprio
now(). A duração da janela e o seu alinhamento aos dias UTC fazem parte do contrato v1.
sql_v1_usage_daily
sql_v1_agent_events somado por day UTC, org, namespace, agent, operation e
kind, sobre a mesma janela: ops, errors, input_tokens, output_tokens,
embedding_tokens, llm_calls, upstream_cost_usd, bytes_written, latency_sum_ms (com
ops, uma média entre linhas), e latency_p50_ms e latency_p95_ms, aproximados e por
linha: não se combinam entre linhas. Todo day, exceto o de hoje, é um dia completo.
Quanto custa uma leitura
Uma visão aplica o filtro do chamador às linhas que ela retorna, então um filtro em ts, day,
thread_id ou memory_key restringe a resposta, não o que é lido. Toda leitura de
sql_v1_memories, sql_v1_memory_history e sql_v1_conversations lê o escopo inteiro da concessão:
o histórico ordena todas as versões dele, e a visão de conversas agrupa todos os turnos
dele, conteúdo incluído. Esses volumes crescem com o que o escopo armazena, e um escopo amplo pode ultrapassar
os limites de leitura abaixo. Cada leitura de uma visão do registro lê o escopo inteiro da concessão sobre a
janela: no máximo desde o início do mês em que a janela abre, em geral perto da própria
janela. Uma concessão mais ampla (* namespaces, --all) lê mais. Os limites de leitura do usuário SQL
valem para essa leitura (LOOM_CH_ANALYSIS_MAX_ROWS_TO_READ, _MAX_EXECUTION_S,
_MAX_MEMORY_BYTES, _MAX_THREADS), então um escopo movimentado pode ultrapassá-los: restrinja a concessão ou
aumente essas configurações, que insights.query compartilha, e execute loom sql-access grant de novo,
o que as grava no perfil dos usuários SQL. Eventos mais antigos que a janela não estão na superfície; a
exportação de analytics grava totais diários de uso,
com nomes em hash, no bucket do operador. loom.agent_events em si não tem TTL, a menos que
LOOM_RETENTION_AGENT_EVENTS_DAYS defina um.
O que as views nunca mostram
As views de memória aplicam as regras das próprias listagens do Loom
(sensibilidade); a view de conversa serve um
turno como conversation.get, acima. Nenhuma delas mostra:
- o valor de uma linha
highe seu hash, na view atual e em todas as versões da sua chave no histórico; - o valor de uma versão redigida e seu hash;
- uma memória rejeitada, uma memória excluída ou apagada, e um turno de conversa excluído;
- qualquer linha de um namespace classificado como
restrictedemloom.namespacesouloom.code_repos, independentemente da concessão, a partir do momento em que é classificado: o Loom audita cada leitura de um namespace restrito, o que uma view não consegue fazer; - qualquer linha de um espelho (um namespace chamado
acl-seguido de 24 dígitos hexadecimais), independentemente da concessão: cada um dos seus documentos só é mostrado a um leitor que a lista de permissões do seu repositório admita (fontes de documentos), o que uma view não consegue verificar; - tabelas fora das cinco views: tokens, concessões, segredos, o log de auditoria, documentos, embeddings e argumentos de requisições;
- as tabelas
systemque mostram instruções de outros usuários, comosystem.query_log,system.mutationsesystem.processes. O ClickHouse as nega a um usuário sem concessão somente comaccess_control_improvements.select_from_system_db_requires_grantativado (o padrão), entãoloom sql-access grantfaz login como cada usuário para o qual define uma senha e o remove quandosystem.processesresponde. No banco de dados do Loom,system.tableslista apenas as cinco views.
As views de memória e de conversa leem as tabelas das quais a
saga de apagamento exclui dados e que seu censo de resíduos
conta, de modo que as linhas de um usuário ou namespace apagado saem delas junto com as tabelas.
As views do ledger mantêm suas linhas, que não contêm conteúdo: o apagamento de um usuário reescreve o
user_id do usuário para <erased>, como faz em loom.agent_events.
Atualidade dos dados
As views leem o ClickHouse no momento da consulta; nada é copiado. O Postgres guarda a memória ativa (autoridade de armazenamento), e loom.memory e loom.memory_versions são projeções publicadas após cada commit, em um flush a cada LOOM_PG_PUBLISH_INTERVAL_MS (250 ms por padrão). Uma escrita de memória confirmada aparece em sql_v1_memories e sql_v1_memory_history assim que o flush é concluído, normalmente em cerca de um intervalo; uma entrega que um escritor interrompido deixou pendente é publicada pelo worker de entrega, o que pode levar mais tempo. As views não esperam por nada: diferentemente de memory.search, que responde PROJECTION_BEHIND após LOOM_PG_PROJECTION_WAIT_MS, uma view entrega o que o ClickHouse contém. As conversas e o registro de requisições são gravados diretamente no ClickHouse.
Acesso
Um usuário SQL da superfície é um usuário do ClickHouse com SELECT nas cinco views e nenhuma outra
permissão, no perfil de configurações loom_sql_surface:
readonly = 1: um comando não altera nenhuma configuração além definal,join_use_nulls,group_by_use_nullsetransform_null_in, que não mudam as linhas de nenhuma view e que os clientes enviam por conta própria (pg_clickhouseentre eles). Qualquer outra configuração poderia encurtar o filtro de uma view: um modo de overflow,additional_table_filters, PREWHERE sobFINAL.- valores que o perfil mantém quaisquer que sejam os padrões do servidor:
apply_deleted_mask = 1eapply_patch_parts = 1(uma linha removida continua oculta),use_query_cache = 0euse_query_condition_cache = 0(ambos usam como chave o texto do comando, que todos os usuários compartilham),use_skip_indexes_if_final_exact_mode = 1,do_not_merge_across_partitions_select_final = 0eoptimize_move_to_prewhere_if_final = 0(FINALlê a versão mais recente de cada chave), todo modo de overflow em'throw'(read e timeout com suas formas_leaf, set, transfer, join, sort, distinct, group by e result),send_logs_level = 'none', nenhuma função de introspecção, equery_plan_filter_push_down = 0eenable_optimize_predicate_expression = 0, de modo que o filtro de quem chama roda sobre o que uma view retorna e nunca sobre linhas de outro tenant (um filtro que gera erro por causa de um valor o citaria); - os limites de
insights.query, exceto os limites de resultado, já que um cliente SQL lê conjuntos de resultados inteiros:LOOM_CH_ANALYSIS_MAX_EXECUTION_S,_MAX_ROWS_TO_READ,_MAX_MEMORY_BYTESe_MAX_THREADS, e_MAX_CONCURRENTcomandos por vez.
Cada view roda com os privilégios de seu definidor (SQL SECURITY DEFINER, o usuário que executou
a migração) e admite apenas as linhas cujo (org, namespace) a tabela
loom.sql_access concede a currentUser(), o usuário que enviou o comando. Um usuário sem
nenhuma linha concedida não lê nada, e o mesmo vale para todo outro usuário do ClickHouse, inclusive
os do próprio 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
grantcria o usuário quando ele não existe e exibe a senha uma única vez; o Loom não guarda nenhuma cópia.--orge--allse excluem mutuamente, e--allnão aceita--namespaces. Executado de novo, define o escopo do usuário exatamente como o que ele nomeia: namespaces que ele deixa de nomear param de aparecer assim que as novas linhas chegam à réplica que atende a leitura;revokeencerra o login imediatamente.--rotateexibe uma nova senha. Quando uma etapa posterior à senha falha,grantinforma; execute-o de novo com--rotate.--allé para um deployment cujos dados pertencem a uma única org. Em um deployment compartilhado, conceda a cada tenant sua própria org.grantrecusa um escopo que nomeia um namespace restrito, e um curinga que alcançaria um que somente a configuração do repositório de código classifica: as views não conseguem ler essa configuração, então execute o comando com a do servidor. Um namespace restringido ali depois de um grant que o alcança está nas views desse grant:listnomeia cada um desses grants, para substituí-los pelos outros namespaces por nome, e termina com código 2.revokeprimeiro remove as linhas de escopo e depois apaga o usuário. Um namespace que um grant nomeia conta como em uso até querevokeremova essa linha: seu nome não é entregue a um novo dono, e uma primeira escrita nele o registra sem dono. Um grant*não nomeia nenhum namespace: ele lê todos os namespaces da org, inclusive os criados depois, então nunca conceda um em uma org compartilhada por sign-ups (LOOM_SELF_SIGNUP_ORG).- O comando roda como
LOOM_CH_USER, que precisa de gerenciamento de acesso:CREATE USER,ALTER USER,DROP USER,CREATE SETTINGS PROFILEeALTER SETTINGS PROFILE,SELECT ... WITH GRANT OPTIONnas cinco views, eSHOW USERScom leitura desystem.usersesystem.settings_profile_elements. Ele recusa um nome já usado por um usuário do ClickHouse que não está no perfilloom_sql_surface, e os usuários do próprio Loom (LOOM_CH_USER, o usuário leitor,loom_analyst,default). - Remova um usuário com
revoke, não comDROP USER: suas linhas de escopo continuam concedidas até querevokeas reescreva, e um usuário posterior com o mesmo nome eSELECTnas views as leria.
Consultas
A partir do Postgres da própria organização, consulte Consultar o Loom pelo Postgres.
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;