# Язык поисковых запросов Telegram (/ru/docs/tg/query-language)

Здесь собран синтаксис запросов для поиска сообщений. Вы сможете сочетать слова, людей, чаты, даты и условия по файлам, проверять запрос и понимать найденные совпадения.

Если вы используете ИИ-агента с tg, вам не нужно учить этот язык: опишите, что вы хотите, простыми словами, и агент напишет запрос. Эта страница предназначена для людей, которые сами вводят поисковые запросы, и для всех, кому нужны все фильтры: точные операторы, каждое поле, предустановки, правила дат и ограничения.

Это справочник для запросов `tg personal search messages`, `tg personal search all`, `tg personal stats messages show`, сохраненные поисковые запросы и `--filter` [тематического поиска](/llms.mdx/docs/ru/tg/topic-search/content.md). Для повседневных примеров начните с [поиск сообщений](/llms.mdx/docs/ru/tg/search/content.md).

Термины, используемые на этой странице:

- **Запрос**: текст, который вы ищете, например `invoice from:me date:7d`.
- **Поле**: имя и двоеточие, которые ограничивают одну часть запроса одним свойством сообщения, например `from:` (отправитель) или `date:` (когда оно было отправлено). Слова без поля ищут текст сообщения.
- **Оператор**: слово или знак, объединяющий условия, например `AND`, `OR` и `NOT`.
- **Словоформы**: одно и то же слово с разными окончаниями. `piso` и `pisos` — формы одного слова.

Язык представляет собой строгий профиль синтаксиса запросов Apache Lucene: слова, фразы, AND/OR/NOT, группы, поля, диапазоны, ограниченные подстановочные знаки и регулярные выражения. «Строгий» означает, что все, что он не поддерживает, является ошибкой, которую никогда не игнорируют молча. В [полном справочнике](https://github.com/WireCatLabs/cli-core/blob/v0.350.0/docs/search/query-language.md) (пока только на русском языке) есть сгенерированные таблицы полей, операторов, пресетов и лимитов, а также исполняемые примеры; [техническая спецификация](https://github.com/WireCatLabs/cli-core/blob/v0.350.0/docs/search/query-language-spec.md) описывает грамматику и компилятор.

Для почты `chat:` выбирает цепочку писем по id или теме; `from:` выбирает отправителя. У почты нет `kind:` и `topic:`.

## Что можно выразить [#что-можно-выразить]

| Вы хотите | Написать |
|---|---|
| сообщения со всеми этими словами в любой форме | `invoice paid` |
| эти слова вместе, в таком порядке | `"invoice paid"` |
| то или иное слово, без третьего | `(cafe OR library) NOT loud` |
| только эта точная форма слова | `exact:piso` или `--exact` для каждого слова без поля |
| слова, начинающиеся с чего-то | `invo*` |
| отправитель, чат, разновидность чата | `from:me`, `chat:"Book club"`, `kind:private` |
| период | `date:7d`, `date:[2026-01-01 TO 2026-02-01}` |
| файлы по имени, типу или размеру | `filename:*.pdf`, `mime:image`, `size>10MB` |
| текст, похожий на пароль, карту или телефон | `preset:secret`, `preset:card` |
| ваши метки | `tag:work` |
| шаблон | `text:/pass(port)?/` |

Слова и словосочетания без полей соответствуют словоформам. `--exact` выбирает точные формы слов без полей; явный `text:` по-прежнему соответствует формам. Языковые настройки архива определяют, какие формы совпадают ([формы слов](/llms.mdx/docs/ru/tg/archive/content.md#repair-and-index-maintenance)).

## Операторы [#операторы]

| Оператор | Пример | Значение |
|---|---|---|
| слова | `invoice paid` | оба слова |
| фраза | `"invoice paid"` | слова в этом порядке |
| `AND`, `&&` | `alpha AND beta` | оба |
| `OR`, `\|\|` | `alpha OR beta` | любое из двух |
| `NOT`, `!`, `-` | `alpha NOT beta` | первое без второго |
| `+` | `+alpha OR beta` | alpha обязательно, beta необязательно |
| группа | `(alpha OR beta) gamma` | скобки задают порядок |
| группа поля | `from:(alice OR bob)` | поле применяется к каждому значению |
| диапазон | `date:[2026-01-01 TO 2026-02-01}` | `[ ]` включают, `{ }` исключают, `*` — открытая граница |
| сравнение | `size>10MB`, `date>=7d`, `date:>=7d` | открытый диапазон; форма с двоеточием означает то же самое |
| подстановка | `invo*`, `te?t` | `*` — любые символы, `?` — один |
| регулярное выражение | `text:/pass(port)?/` | ограниченное регулярное выражение Lucene |

`alpha OR beta gamma` означает `(alpha OR beta) AND gamma`; `alpha OR beta AND gamma` означает `alpha OR (beta AND gamma)`. Используйте скобки для ясности. Строчные буквы `and`, `or`, `not` — это простые слова. Запрос только с `NOT` ничего не находит: укажите положительное условие, например `kind:group NOT preset:secret`. Нечёткий поиск `~`, поиск по близости, повышение веса и интервалы отклоняются с ошибкой, а не игнорируются. Опечатки не исправляются: чтобы охватить разные окончания, используйте подстановочный знак, например `invo*`.

## Поля [#поля]

| Поле | Что находит | Пример |
|---|---|---|
| `text` | слова сообщения (поле по умолчанию) | `text:invoice` |
| `exact` | точная форма слова или фразы | `exact:piso`, `exact:"invoice paid"` |
| `body` | весь исходный текст с учётом регистра | `body:/.*invoice.*/` |
| `from` | отправителя по имени, @username или идентификатору; `me` — это вы | `from:"Alice Synthetic"` |
| `chat` | чат по названию, @username или идентификатору | `chat:"Book club"` |
| `date` | время отправки | `date:today`, `date:7d`, `date:[2026-01-01 TO 2026-02-01}` |
| `kind` | вид чата: `private`, `group`, `channel`, `saved`, `bot`, `service`, `unknown` | `kind:private` |
| `has` | `attachment`, `link`, `file`, `photo`, `image`, `video`, `audio`, `voice`, `sticker`, `contact`, `location`, `poll` | `has:file` |
| `topic` | одну тему форума; нужен один чат | `chat:"Book club" AND topic:42` |
| `in` | какие аккаунты: провайдер или `bots` | `in:bots` |
| `preset` | текст, похожий на секрет или контактные данные | `preset:secret` |
| `content` | проиндексированный текст вложений | `content:invoice` |
| `filename` | полное имя прикреплённого файла | `filename:*.pdf` |
| `mime` | тип прикреплённого файла; значение без `/` сравнивается с первой частью | `mime:image` |
| `size` | размер прикреплённого файла в байтах или в KB/MB/GB по 1024 | `size>10MB` |
| `tag` | ваша локальная метка на сообщении, его чате или отправителе | `tag:work` |
| `phone` | номер телефона в тексте, как бы он ни был записан | `phone:"+34 600 000 000"` |
| `email` | адрес почты в тексте | `email:ana@example.com` |
| `url` | ссылку в тексте, без параметров отслеживания | `url:"https://example.com/a"` |
| `domain` | сайт ссылки или адреса в тексте | `domain:example.com` |
| `mentions` | человека, организацию или документ, с которым вы связали найденное упоминание | `mentions:"person:12"` |

Имена полей чувствительны к регистру. Неизвестное поле, значение или комбинация — это ошибка, а не пустой ответ и никогда не простой текст. Имя, которое архиву неизвестно, не ищется в Telegram.

`kind:bot` выбирает чат с ботом; `in:bots` выбирает архивы аккаунтов `tg personal bot`. `topic:`
требует ровно одного чата в `chat:`, поскольку номера тем в разных группах повторяются. `filename`,
`mime` и `size` подходят сообщению, если подходит хотя бы один из его файлов. `/` начинает регулярное
выражение, поэтому полный тип заключайте в кавычки: `mime:"application/pdf"`.

## Упоминания [#упоминания]

`tg` находит в сохранённых сообщениях телефоны, адреса почты, ссылки, документы и имена людей. Эти поля
находят сообщения, в которых они есть. Сами находки показывает `tg personal mentions list`.

```sh
tg personal search messages 'phone:"+34 600 000 000"'
tg personal search messages 'email:ana@example.com OR domain:example.com'
tg personal search messages 'mentions:"person:12"'
```

Значение с `+` или `@` берите в кавычки: оба знака — операторы. Телефон находится, как бы он ни был записан:
`+34 600 000 000` и `600000000` — один телефон, а номер без `+` читается по странам из настройки
`phone_countries`. `domain:` считает `docs.example.com` тем же, что `example.com`. `mentions:` принимает
ссылку на человека, организацию или документ и находит сообщения, упоминания в которых вы связали с ним
через `tg mentions confirm`.

## Пресеты [#пресеты]

Пресет находит текст по его форме. Используйте его, чтобы найти пароль, код или номер карты, который кто-то прислал.

| Пресет | Кандидат — это |
|---|---|
| `password` | подпись пароля, за которой следует значение |
| `code` | подпись кода подтверждения и 4–8 цифр |
| `api-key` | подпись ключа API и значение |
| `secret` | подпись пароля, секрета, токена или ключа API и значение |
| `card` | 13–19 цифр, возможно с пробелами или дефисами |
| `bank` | значение в формате IBAN |
| `passport` | значение с подписью «паспорт» или российский формат 4+6 цифр |
| `phone` | международный телефон, начинающийся с плюса |
| `email` | адрес электронной почты |
| `telegram-link` | ссылка t.me или telegram.me |
| `url` | ссылка HTTP(S) |
| `contact` | вложение-контакт, либо адрес почты или телефон |
| `location` | вложение-место или ссылка geo: |

Пресет сообщает о кандидате по его виду. Он не проверяет пароль, карту или документ и
может совпасть с чем-то безобидным. Не удаляйте и не пересылайте сообщения автоматически на основании пресета.

## Даты [#даты]

`--timezone` принимает часовой пояс IANA, например `Europe/Madrid`; без него используется пояс компьютера,
и он возвращается в ответе. Дата без времени — целый календарный день. Включающая верхняя граница охватывает
весь этот день, исключающая — не включает его; день перевода часов может длиться 23 или 25 часов.

`date:today` и `date:yesterday` — календарные дни. `date:7d` означает от 7 дней назад до текущего момента (также
`30m`, `2h`); `date>=7d` и `date:[30d TO 7d}` работают в сравнениях и диапазонах и отсчитываются от
момента запуска запроса. Точное время заключайте в кавычки, с секундами и смещением:
`date>="2026-01-01T10:00:00+02:00"`.

## Слова, подстановки и регулярные выражения [#слова-подстановки-и-регулярные-выражения]

Перед индексацией и поиском текст нормализуется: нижний регистр, без диакритических знаков. Побочный эффект: некоторые
разные слова становятся одинаковыми, например `año` и `ano`. Регулярные выражения и подстановки в `text:`
нормализуются так же.

`text:/pay/` находит целое слово pay, но не payment. `body:/pay/` находит только сообщение,
весь текст которого — pay, с учётом регистра; чтобы найти его в любом месте, используйте `body:/.*pay.*/`. Это
синтаксис регулярных выражений Lucene, без проверок окружения JavaScript, обратных ссылок, якорей и флагов.

В большом архиве короткий префикс, такой как `a*`, может расширяться до более чем 10 000 слов и отклоняется; удлините его. Длинные запросы, глубокая вложенность и большие шаблоны отклоняются с `query_limit`, а не сокращаются. Поиск, который дольше своего лимита в 2 секунды, останавливается с `timeout` (причина `query.time-limit`): запрос верный, поэтому сузьте чат, даты или шаблон.

## Ответ [#ответ]

`--json` возвращает `{ items, page: { limit, has_more }, next?, missing?, meta }`,
даже если совпадений нет. `--jsonl` выводит по одному элементу на строку, затем итоговую запись с полнотой результата и данными о страницах.

- `items`: найденные сообщения, сначала лучшие (или сначала новые с `--newest`). У каждого есть `ref` (`msg:…`), `timestamp`,
  `sender_name`, `excerpt` и `matched_in`.
- `meta.accounts`: какие аккаунты обыскивались.
- `missing`: что ответ не смог увидеть, и для каждого пункта шаг, который это восполняет. `coverage` означает, что некоторые чаты в области
  ни разу не загружались или загрузка перед поиском остановилась раньше времени (шаг `messages.sync`); `text` означает, что индекс слов
  еще строится (шаг `store.migrate`, `tg personal store migrate`).
- `next`: шаги, которые нужно выполнить. `page.next` повторяет запрос для следующей страницы.
- `page.has_more` касается страницы, а не того, есть ли больше сообщений в Telegram.

Ошибка указывает место проблемы в запросе и даёт подсказку.

## Через MCP [#через-mcp]

Когда агент выполняет поиск на сервере MCP tg, `tg_read` (`command: "search messages"`) принимает запрос в `query`, а `timezone` для календарной зоны. `chat` принимает идентификатор или сохраненное имя; `source`, `newest`, `context` и `limit` работают так же, как и параметры команды; `saved` запускает сохраненный поиск. `thread`, `thread_hops`, `thread_messages`, `thread_bytes`, `thread_within` и `sync_first` соответствуют опциям `--thread…` и `--sync-first`; `sync_first` предлагается только с `messages.sync-first: allow`. Ответ имеет те же поля, что и `--json`. `tg_read` (`command: "stats messages show"`) считает одни и те же запросы. История запросов следует за сервером: `tg personal mcp serve --no-record` или `record`, установленный на `false`, не записывает свои вызовы.

## Дальше [#дальше]

- [Поиск сообщений](/llms.mdx/docs/ru/tg/search/content.md): ежедневные поиски, сохраненные поиски и подсчет.
- [Поиск по теме](/llms.mdx/docs/ru/tg/topic-search/content.md): найдите обсуждение по его смыслу, если вы не знаете его слов.
