Las páginas sin traducir se abren en inglés y se indican como inglés.
Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.
Superficie SQL
La superficie SQL es un conjunto de vistas de ClickHouse de solo lectura sobre las memorias de un tenant, el historial de memorias, las conversaciones y el registro de solicitudes. El cliente SQL, la herramienta de BI o el trabajo de warehouse de una organización las lee con un usuario de ClickHouse que crea loom sql-access. Ese usuario lee las vistas y nada más, y cada vista muestra solo las organizaciones y los espacios de nombres a los que se le dio acceso.
Versión y compatibilidad
El nombre de cada vista incluye su versión: sql_v1_memories es la versión 1. Los nombres de las columnas, sus tipos y sus significados son un contrato público:
- Una vista
v1puede ganar columnas. Nunca pierde ni cambia el nombre de una columna, y una columna nunca cambia de tipo ni de significado. - Un cambio que rompa esa regla se publica como una vista
sql_v2_*junto av1. Ambas se mantienen durante al menos una versión, y las notas de la versión indican qué vistav1se retira. - Selecciona las columnas por nombre:
SELECT *incorpora las columnas que se añadan.
Vistas
Cada vista está en la base de datos de Loom (loom, a menos que LOOM_CH_DATABASE indique otra) y
incluye las columnas de identidad org y namespace. sql_v1_memories, sql_v1_memory_history
y sql_v1_agent_events incluyen además agent, user_id y session_id;
sql_v1_conversations incluye agent y user_id; sql_v1_usage_daily incluye agent.
Un join puede coincidir con cualquier parte de la tupla de identidad
que ambos lados incluyan.
sql_v1_memories
Una fila por memoria (identidad y clave): su versión actual. Una memoria eliminada o borrada
no aparece, ni tampoco una rechazada. Los demás estados se listan con su status:
memory.list oculta las filas duplicate, superseded y proposed salvo que se pidan, así que filtre
por status = 'active' para obtener lo que muestra un listado predeterminado. Una memoria que ha pasado su expires_at se
lista con su valor hasta que el barrido de expiración actúa sobre ella, igual que la lista memory.list; añada
(expires_at IS NULL OR expires_at > now()) para obtener lo que sirve memory.search.
| Columna | Significado |
|---|---|
org, namespace, agent, user_id, session_id, run_id |
a quién pertenece la memoria y la ejecución que la escribió (- si no hay ninguna) |
memory_key, memory_id, memory_type |
la clave, el id de la memoria (una versión con version), su tipo (fact, decision, ...) |
value |
el valor tal como lo sirve memory.get, o NULL cuando se retiene |
value_withheld |
'' cuando se sirve value, sensitive para una fila high, redacted para una versión redactada |
content_sha256 |
el SHA-256 del valor, NULL siempre que value lo sea: el hash de un secreto corto se puede adivinar |
version, status, confidence, pinned, tags |
igual que en memory.get |
sensitivity, source_class, actor |
la etiqueta, la clase de procedencia, el sujeto del token que la escribió |
created_at, updated_at, expires_at, valid_at, invalid_at |
cuándo se escribió y se modificó por última vez, cuándo expira, cuándo el hecho pasó a ser verdadero y dejó de serlo |
sql_v1_memory_history
Una fila por versión de cada memoria, incluida la versión de una eliminación (status =
'tombstoned', con tombstoned_at establecido). Una versión rechazada no aparece. Las columnas son las de
sql_v1_memories sin expires_at, valid_at ni invalid_at, más tombstoned_at.
value y content_sha256 son NULL en una versión redactada y en cada versión de una clave
que alguna vez se etiquetó como high: la versión anterior a que el barrido de sensibilidad etiquetara una fila contiene
el mismo valor sin etiqueta.
sql_v1_conversations
Una fila por turno de conversación almacenado de cada usuario: org, namespace, agent, user_id,
thread_id, msg_id, role, content, tokens, run_id y ts (la última
escritura del turno). Un turno eliminado o compactado (tombstoned_at establecido) no aparece, y uno borrado
desaparece junto con su fila. Un turno no lleva etiqueta de sensibilidad, por lo que content se sirve tal como se escribió,
igual que conversation.get sirve los turnos de un hilo; la comprobación de los listados entre hilos para texto que
se lee como high se ejecuta en Loom, no en SQL.
sql_v1_agent_events
El registro de solicitudes: una fila por llamada a una op o pasada de un worker, con kind '' para una solicitud.
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 del modelo en USD), bytes_written, model, consumer, subject
(el sujeto del token que llamó) y transport. Los argumentos de la solicitud no están incluidos. Las filas de un
usuario final borrado muestran user_id <erased>.
Contiene los 31 días UTC completos anteriores a hoy y lo que va de hoy; cada sentencia lee su propio
now(). La longitud de la ventana y su alineación con los días UTC forman parte del contrato v1.
sql_v1_usage_daily
sql_v1_agent_events sumada por day UTC, org, namespace, agent, operation y
kind, sobre la misma ventana: ops, errors, input_tokens, output_tokens,
embedding_tokens, llm_calls, upstream_cost_usd, bytes_written, latency_sum_ms (con
ops, una media entre filas), y latency_p50_ms y latency_p95_ms, aproximadas y por
fila: no se combinan entre filas. Todos los day salvo el de hoy son días completos.
Qué cuesta una lectura
Una vista aplica el filtro del llamante sobre las filas que devuelve, así que un filtro sobre ts, day,
thread_id o memory_key acota la respuesta, no lo que se lee. Cada lectura de
sql_v1_memories, sql_v1_memory_history y sql_v1_conversations lee todo el ámbito de la concesión:
el historial ordena todas las versiones que contiene, y la vista de conversaciones agrupa todos los turnos
que contiene, contenido incluido. Estas lecturas crecen con lo que almacena el ámbito, y un ámbito amplio puede superar
los límites de lectura que se indican más abajo. Cada lectura de una vista del registro lee todo el ámbito de la concesión sobre la
ventana: como máximo desde el inicio del mes en que se abre la ventana, normalmente cerca de la propia
ventana. Una concesión más amplia (* espacios de nombres, --all) lee más. Los límites de lectura del usuario SQL
se aplican a esa lectura (LOOM_CH_ANALYSIS_MAX_ROWS_TO_READ, _MAX_EXECUTION_S,
_MAX_MEMORY_BYTES, _MAX_THREADS), por lo que un ámbito con mucha actividad puede superarlos: reduzca la concesión, o
aumente esos ajustes, que insights.query comparte, y ejecute de nuevo loom sql-access grant,
que los escribe en el perfil de los usuarios SQL. Los eventos anteriores a la ventana no están en la
superficie; la exportación de analítica escribe los totales de uso diarios,
con nombres con hash, en el bucket del operador. loom.agent_events en sí no tiene TTL a menos que LOOM_RETENTION_AGENT_EVENTS_DAYS establezca uno.
Lo que las vistas nunca muestran
Las vistas de memoria aplican las reglas de los listados propios de Loom
(sensibilidad); la vista de conversaciones entrega un
turno como lo hace conversation.get, según se describe arriba. Ninguna de ellas muestra:
- el valor de una fila
highni su hash, ni en la vista actual ni en ninguna versión de su clave en el historial; - el valor de una versión redactada ni su hash;
- una memoria rechazada, una memoria eliminada o borrada, ni un turno de conversación eliminado;
- ninguna fila de un espacio de nombres clasificado como
restrictedenloom.namespacesoloom.code_repos, sea cual sea la concesión, desde el momento en que se clasifica: Loom audita cada lectura de un espacio de nombres restringido, algo que una vista no puede hacer; - ninguna fila de un espejo (un espacio de nombres llamado
acl-seguido de 24 dígitos hexadecimales), sea cual sea la concesión: cada uno de sus documentos se muestra solo a un lector que la lista de permisos de su almacén admita (fuentes de documentos), algo que una vista no puede comprobar; - las tablas ajenas a las cinco vistas: tokens, concesiones, secretos, el registro de auditoría, documentos, embeddings y argumentos de las solicitudes;
- las tablas
systemque muestran las sentencias de otros usuarios, comosystem.query_log,system.mutationsysystem.processes. ClickHouse se las niega a un usuario sin concesión solo siaccess_control_improvements.select_from_system_db_requires_grantestá activado (el valor por defecto), por lo queloom sql-access grantinicia sesión como cada usuario al que le asigna una contraseña y lo elimina cuandosystem.processesresponde. En la base de datos de Loom,system.tableslista solo las cinco vistas.
Las vistas de memoria y de conversaciones leen las tablas de las que borra la
saga de borrado y que cuenta su censo de residuos, por lo que las filas de un usuario o espacio de nombres borrado salen de ellas junto con las tablas. Las vistas
del libro mayor conservan sus filas, que no contienen contenido: el borrado de un usuario reescribe el
user_id del usuario como <erased>, igual que en loom.agent_events.
Actualización de los datos
Las vistas leen ClickHouse en el momento de la consulta; no se copia nada. Postgres guarda la memoria activa (autoridad de almacenamiento), y loom.memory y loom.memory_versions son proyecciones que se publican después de cada commit, en un flush cada LOOM_PG_PUBLISH_INTERVAL_MS (250 ms por defecto). Una escritura de memoria confirmada aparece en sql_v1_memories y sql_v1_memory_history cuando se completa su flush, normalmente en aproximadamente un intervalo; una entrega que dejó pendiente un escritor detenido la publica el worker de entregas, lo que puede tardar más. Las vistas no esperan a nada: a diferencia de memory.search, que responde PROJECTION_BEHIND pasado LOOM_PG_PROJECTION_WAIT_MS, una vista devuelve lo que ClickHouse contiene. Las conversaciones y el registro de solicitudes se escriben directamente en ClickHouse.
Acceso
Un usuario SQL de la superficie es un usuario de ClickHouse con SELECT sobre las cinco vistas y ningún otro permiso, en el perfil de configuración loom_sql_surface:
readonly = 1: una sentencia no cambia ninguna configuración salvofinal,join_use_nulls,group_by_use_nullsytransform_null_in, que dejan las filas de cada vista como están y que los clientes envían por su cuenta (pg_clickhouseentre ellos). Cualquier otra configuración podría cortar el filtro de una vista: un modo de desbordamiento,additional_table_filters, PREWHERE bajoFINAL.- valores que el perfil mantiene sean cuales sean los valores por defecto del servidor:
apply_deleted_mask = 1yapply_patch_parts = 1(una fila eliminada sigue oculta),use_query_cache = 0yuse_query_condition_cache = 0(ambas se indexan por el texto de la sentencia, que todos los usuarios comparten),use_skip_indexes_if_final_exact_mode = 1,do_not_merge_across_partitions_select_final = 0yoptimize_move_to_prewhere_if_final = 0(FINALlee la última versión de cada clave), todos los modos de desbordamiento en'throw'(read y timeout con sus formas_leaf, set, transfer, join, sort, distinct, group by y result),send_logs_level = 'none', sin funciones de introspección, yquery_plan_filter_push_down = 0yenable_optimize_predicate_expression = 0, de modo que el filtro de quien llama se ejecuta sobre lo que devuelve una vista y nunca sobre filas de otro inquilino (un filtro que lance un error sobre un valor lo citaría); - los límites de
insights.query, salvo sus topes de resultado, ya que un cliente SQL lee conjuntos de resultados completos:LOOM_CH_ANALYSIS_MAX_EXECUTION_S,_MAX_ROWS_TO_READ,_MAX_MEMORY_BYTESy_MAX_THREADS, y_MAX_CONCURRENTsentencias a la vez.
Cada vista se ejecuta con los privilegios de su definidor (SQL SECURITY DEFINER, el usuario que ejecutó la migración) y admite solo las filas cuyo (org, namespace) la tabla loom.sql_access concede a currentUser(), el usuario que envió la sentencia. Un usuario sin filas concedidas no lee nada, y lo mismo ocurre con cualquier otro usuario de ClickHouse, incluido el propio de 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
grantcrea el usuario si no existe e imprime su contraseña una sola vez; Loom no guarda ninguna copia.--orgy--allse excluyen entre sí, y--allno admite--namespaces. Si se ejecuta de nuevo, fija el alcance del usuario exactamente a lo que nombra: los espacios de nombres que ya no nombra dejan de verse cuando las nuevas filas llegan a la réplica que atiende la lectura;revoketermina el acceso de inmediato.--rotateimprime una contraseña nueva. Cuando falla un paso posterior a la contraseña,grantlo indica; ejecútalo de nuevo con--rotate.--alles para un despliegue cuyos datos pertenecen a una sola org. En un despliegue compartido, concede a cada inquilino su propia org.grantrechaza un alcance que nombre un espacio de nombres restringido, y un comodín que llegaría a uno que solo clasifica la configuración del repositorio de código: las vistas no pueden leer esa configuración, así que ejecuta el comando con la del servidor. Un espacio de nombres restringido ahí después de una concesión que lo alcanza queda dentro de las vistas de esa concesión:listnombra cada una de esas concesiones, para reemplazarlas por los otros espacios de nombres por su nombre, y termina con código 2.revokeelimina primero las filas de alcance y luego borra el usuario. Un espacio de nombres que una concesión nombra cuenta como en uso hasta querevokeelimina esa fila: su nombre no se entrega a un nuevo propietario, y una primera escritura en él lo registra sin propietario. Una concesión*no nombra ningún espacio de nombres: lee todos los de la org, incluidos los creados después, así que nunca concedas una en una org que comparten los registros de nuevos usuarios (LOOM_SELF_SIGNUP_ORG).- El comando se ejecuta como
LOOM_CH_USER, que necesita gestión de accesos:CREATE USER,ALTER USER,DROP USER,CREATE SETTINGS PROFILEyALTER SETTINGS PROFILE,SELECT ... WITH GRANT OPTIONsobre las cinco vistas, ySHOW USERScon lecturas desystem.usersysystem.settings_profile_elements. Rechaza un nombre ya tomado por un usuario de ClickHouse que no esté en el perfilloom_sql_surface, y los usuarios propios de Loom (LOOM_CH_USER, el usuario lector,loom_analyst,default). - Elimina un usuario con
revoke, no conDROP USER: sus filas de alcance siguen concedidas hasta querevokelas reescribe, y un usuario posterior con el mismo nombre ySELECTsobre las vistas las leería.
Consultas
Desde el Postgres de la propia organización, consulta Consultar Loom desde 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;