Lenguaje de consulta de la búsqueda
Documentación: v0.28.0
Todos los campos, operadores, presets y límites de la búsqueda de mensajes de Telegram, con reglas de fechas, expresiones regulares y la respuesta JSON para scripts y agentes.
La referencia de las consultas de tg messages search, tg messages stats y las búsquedas guardadas. Para ejemplos del día a día, empieza por buscar mensajes.
El lenguaje es un perfil estricto de la sintaxis de consultas de Apache Lucene: palabras, frases, AND/OR/NOT, grupos, campos, intervalos, comodines con límites y expresiones regulares. La referencia completa (en ruso) contiene las tablas generadas de campos, operadores, filtros preparados y límites, y ejemplos ejecutables; la especificación técnica describe la gramática y el compilador.
Operadores
| Operador | Ejemplo | Significado |
|---|---|---|
| palabras | invoice paid | las dos palabras |
| frase | "invoice paid" | las palabras en este orden |
AND, && | alpha AND beta | las dos |
OR, || | alpha OR beta | cualquiera de las dos |
NOT, !, - | alpha NOT beta | la primera sin la segunda |
+ | +alpha OR beta | alpha obligatoria, beta opcional |
| grupo | (alpha OR beta) gamma | los paréntesis fijan el orden |
| grupo de campo | from:(alice OR bob) | el campo se aplica a cada valor |
| intervalo | date:[2026-01-01 TO 2026-02-01} | [ ] incluyen, { } excluyen, * abierto |
| comparación | size>10MB, date>=7d | un intervalo abierto |
| comodín | invo*, te?t | * cualquier número de caracteres, ? uno |
| expresión regular | text:/pass(port)?/ | una expresión regular de Lucene con límites |
alpha OR beta gamma significa (alpha OR beta) AND gamma; alpha OR beta AND gamma significa alpha OR (beta AND gamma). Usa paréntesis para evitar dudas. and, or y not en minúsculas son palabras normales. Una consulta con solo NOT no encuentra nada: añade una condición positiva, por ejemplo kind:group NOT preset:secret. La coincidencia difusa ~, la proximidad, la relevancia ponderada y los intervalos se rechazan con un error; no se ignoran.
Campos
Los nombres de campo distinguen mayúsculas. Un campo, valor o combinación desconocidos son un error, nunca una respuesta vacía ni texto normal. Un nombre que el archivo local no conoce no se busca en Telegram.
kind:bot selecciona un chat con un bot; in:bots selecciona los archivos de las cuentas de tg bot. topic: necesita exactamente un chat en chat: o --chat, porque los números de tema se repiten entre grupos. filename, mime y size coinciden con un mensaje cuando al menos uno de sus archivos coincide. / inicia una expresión regular, así que pon un tipo completo entre comillas: mime:"application/pdf".
Filtros preparados
| Filtro | Un candidato es |
|---|---|
password | una etiqueta de contraseña seguida de un valor |
code | una etiqueta de código de verificación y de 4 a 8 cifras |
api-key | una etiqueta de clave de API y un valor |
secret | una etiqueta de contraseña, secreto, token o clave de API y un valor |
card | de 13 a 19 cifras, con espacios o guiones opcionales |
bank | un valor con forma de IBAN |
passport | un valor de pasaporte con etiqueta o la forma rusa de 4+6 cifras |
phone | un teléfono internacional con prefijo + |
email | una forma de dirección de correo electrónico |
telegram-link | un enlace t.me o telegram.me |
url | un enlace HTTP(S) |
contact | un contacto adjunto, o un correo electrónico o un teléfono |
location | una ubicación adjunta o un enlace geo: |
Un filtro preparado señala un candidato por su forma. No verifica una contraseña, una tarjeta ni un documento, y puede coincidir con algo inofensivo. No borres ni reenvíes mensajes de forma automática solo por su resultado.
Fechas
--timezone acepta una zona IANA como Europe/Madrid; sin ella se usa la zona del equipo, que se devuelve en la respuesta. Una fecha sin hora es un día natural completo. Un límite superior inclusivo incluye todo ese día; uno exclusivo lo excluye; un día con cambio de hora puede durar 23 o 25 horas.
date:today y date:yesterday son días naturales. date:7d significa desde hace 7 días hasta ahora (también 30m, 2h); date>=7d y date:[30d TO 7d} funcionan en comparaciones e intervalos, contados desde el momento en que se ejecuta la consulta. Una hora exacta va entre comillas, con segundos y desplazamiento horario: date>="2026-01-01T10:00:00+02:00".
Palabras, comodines y expresiones regulares
El texto se normaliza antes de indexarlo y buscarlo: minúsculas y sin tildes. Un efecto secundario: algunas palabras distintas pasan a ser iguales, como año y ano. Las expresiones regulares y los comodines de text: se normalizan del mismo modo.
text:/pay/ coincide con la palabra completa pay, no con payment. body:/pay/ coincide solo con un mensaje cuyo texto entero es pay, distinguiendo mayúsculas; para encontrarla en cualquier parte, usa body:/.*pay.*/. Es la sintaxis de expresiones regulares de Lucene, sin anticipaciones de JavaScript, referencias hacia atrás, anclas ni opciones.
En un archivo grande, un prefijo corto como a* puede abarcar más de 10 000 palabras y se rechaza; alárgalo. Las consultas largas, el anidamiento profundo, los patrones grandes y los recorridos lentos se rechazan con query_limit, no se recortan: limita el chat, las fechas o el patrón.
La respuesta
--json devuelve { items, page, limit, hasMore, corrections, completeness, wordsReady, query, coverage }, aunque no haya coincidencias. --jsonl emite solo los elementos.
query: la versión del lenguaje, la zona horaria y el orden usados.coverage: en qué cuentas y chats se buscó.lastSyncedAtes el momento más antiguo en questore fetchdescargó un chat del ámbito, onullsi alguno no se descargó nunca.inventoryCompletesignifica que cada cuenta del ámbito ha listado alguna vez todos sus chats; no garantiza un historial completo.completeness: por chat, si su historial guardado llega al principio y si tiene huecos.wordsReady: si el índice de palabras está completo. Cuando esfalse, una consulta con palabras falla conindex_not_readyy el comando que lo termina,tg store migrate; una consulta sin palabras se ejecuta.hasMorese refiere a la página, no a si Telegram tiene más.
Un error incluye la posición del problema en la consulta y una pista.
En MCP
tg_messages_search acepta la consulta como text, o como árbol sintáctico versionado en ast (no ambos); language elige lucene o legacy, y timezone, la zona del calendario. chat acepta un id o un nombre guardado; source, newest, context y limit funcionan como las opciones del comando; saved ejecuta una búsqueda guardada. El historial de consultas sigue al servidor: tg mcp --no-record, o record con valor false, deja fuera sus llamadas. La respuesta tiene los mismos campos que --json. tg_messages_stats cuenta las mismas consultas.
Los modos anteriores
tg messages search 'from:alice after:7d invoice -draft' --language legacy --json
tg messages search --regex 'invoice\s+\d+' --json--language legacy conserva los filtros anteriores y su corrección de erratas. --regex es un modo aparte: una expresión regular de JavaScript, sin distinguir mayúsculas, sobre el texto completo, en un proceso aislado con límites de tiempo y tamaño. --regex no se puede combinar con --language lucene.
| Anterior | Estricto |
|---|---|
after:2026-01-01 | date:[2026-01-01 TO *] |
before:2026-02-01 | date:[* TO 2026-02-01} |
after:7d | date:7d |
| prefijo y corrección de erratas automáticos | invo* de forma explícita; erratas solo en --language legacy |
--thread sigue el grafo de respuestas guardado; en messages context sustituye a los mensajes vecinos en orden cronológico. Los valores predeterminados son 8 saltos, 50 mensajes, 65 536 bytes y un día alrededor de cada resultado. Cámbialos con --thread-hops, --thread-messages, --thread-bytes y --thread-within. Sin grafo, vuelve al contexto cronológico; los enlaces desactualizados se marcan y no se recorren.
Por defecto, la búsqueda lee el archivo local. --sync-first descarga de forma explícita los mensajes nuevos antes de buscar y no marca nada como leído: como máximo 5 chats, 500 mensajes y 30 segundos. Cambia estos límites con --max-chats, --max-messages y --sync-time. Si la actualización falla o queda incompleta, se conservan los resultados locales, con la cobertura desactualizada y los detalles de la actualización.
MCP usa thread, thread_hops, thread_messages, thread_bytes, thread_within y sync_first. sync_first solo está disponible con messages.sync-first: allow. Un messages_context normal con offline: true lee los mensajes guardados.