Перейти к основному содержимому

Сопоставление и преобразование тем

Фильтр выбирает данные, не меняя тему. Сопоставление переписывает её в трёх местах:

  • На входе — subject transform потока меняет сохраняемую тему.
  • На выходе — republish выдаёт сохранённое в новые темы обычным подписчикам без потребителя.
  • При копировании — преобразования зеркала или источника, см. Зеркала и источники.

Язык преобразований общий.

Язык преобразований​

Пара source → destination: исходный фильтр с */>, целевой шаблон с совпавшими токенами:

  • {{wildcard(1)}} — токен первого *, {{wildcard(2)}} — второго; старый $1 эквивалентен.
  • {{partition(n, 1)}} хеширует первый токен в 0…n-1. Значение всегда попадает в один раздел.
  • Конечный > переносит остаток без изменений: orders.> → dash.orders.>.
  • {{split(1, -)}}, {{splitfromleft(1, 3)}} делят токен по разделителю без кавычек, кроме точки, либо по позиции символа.

Полный список — в ADR-30 ниже. Обычно нужны wildcard и partition; split, splitfromleft/right и slicefromleft/right изменяют отдельный токен.

Проверьте без потока через nats server mappings, передав источник, цель и тему:

nats server mappings "orders.*" "orders.{{wildcard(1)}}.archived" orders.created
orders.created.archived

Преобразование на входе​

Subject transform меняет тему при сохранении. Подписки потока прежние: совпавшее преобразуется, остальное сохраняется как есть. Сообщения не отбрасываются.

Для детерминированного разбиения оставьте ORDERS и создайте временный поток ingest.*. Токен заказчика хешируется в три раздела:

#!/bin/bash

# A subject transform rewrites the subject a message is STORED under, which
# is separate from the subjects the stream listens on. Leave ORDERS alone:
# this is a throwaway stream that ingests on ingest.* and shards each
# message into one of three buckets by hashing the customer token.
# --transform-source which incoming subjects to match (wildcards ok)
# --transform-destination the stored subject, pulling matched tokens in
# {{partition(3,1)}} hash the 1st token into bucket 0, 1, or 2
# {{wildcard(1)}} the 1st * token from the source
nats stream add ORDERS-SHARDED \
--subjects "ingest.*" \
--transform-source "ingest.*" \
--transform-destination "orders.{{partition(3,1)}}.{{wildcard(1)}}" \
--defaults

Опубликуйте заказы нескольких заказчиков: результат — orders.<bucket>.<customer>.

nats pub ingest.acme "an order"
nats pub ingest.globex "an order"
nats pub ingest.wayne "an order"
nats stream subjects ORDERS-SHARDED
Subject │ Count
orders.1.acme │ 1
orders.1.globex │ 1
orders.2.wayne │ 1

Фильтр orders.1.> всегда получает одну долю заказчиков. Изменение — nats stream edit --transform-source/--transform-destination, удаление — --no-transform.

Уже сохранённые записи не переписываются; подробнее ниже.

Повторная публикация в живые темы​

Republish повторно выдаёт каждую сохранённую запись в другую тему. Это дешёвое живое наблюдение для панели без потребителя и истории.

#!/bin/bash

# Republish re-emits every message the stream stores onto a second subject,
# in real time. A plain core subscriber on that subject sees the data flow
# by without creating a consumer. This adds republish to ORDERS; clear it
# later with: nats stream edit ORDERS --no-republish
nats stream edit ORDERS \
--republish-source "orders.>" \
--republish-destination "dash.orders.>"

Обычная подписка видит поступающие заказы:

nats sub "dash.orders.>"
[#1] Received on "dash.orders.created"
Nats-Stream: ORDERS
Nats-Subject: orders.created
Nats-Sequence: 5
Nats-Time-Stamp: 2026-05-22T11:02:00Z
Nats-Last-Sequence: 4

{"order_id":"ord_5xk1","customer":"initech","total_cents":1500,"ts":"2026-05-22T11:02:00Z"}

Пять заголовков происхождения: Nats-Stream, Nats-Subject, Nats-Sequence, Nats-Time-Stamp, Nats-Last-Sequence. Последний — прежний номер той же темы либо 0, что помогает обнаружить пропуск. Заголовки издателя тоже сохраняются.

--republish-headers исключает тела, добавляя их размер Nats-Msg-Size. Отключение — nats stream edit ORDERS --no-republish.

Преобразование при копировании​

Каждый источник или зеркало может менять пространство тем, например добавляя регион при агрегации. Это разобрано с механизмом копирования.

Отличие от сопоставления учётной записи​

Сопоставление Core NATS настраивается серверу для учётной записи и меняет маршрутизацию до записи в поток. Это отдельный механизм.

Типичные ошибки​

Основные ловушки:

Потерянный токен фильтра. Шаблон сохраняет только указанные части. orders.* → orders.archived без {{wildcard(1)}} лишает потребителя фильтрации по типу. Сохраняйте нужные токены.

Republish не заменяет потребителя. Это Core без хранения, ack и повторов: отключённый читатель пропускает. Для наверстывания нужна долговременная доставка.

Цикл republish. Цель не должна пересекать подписки потока. Для orders.> цель orders.dash.> отклоняется кодом 10052; используйте dash.orders.>. Циклы между двумя потоками сервер не всегда обнаруживает.

Правка не переписывает историю. Для изменения прежних тем копируйте в новый поток с преобразованием источника.

Количество разделов нельзя безболезненно менять. Переход partition(3, …) → partition(4, …) перемещает заказчиков между фильтрами orders.0.>, orders.1.> и другими. Планируйте число заранее.

Что уже готово​

Преобразование выполнялось на временном ORDERS-SHARDED, не ORDERS. Если добавлен republish, его убирает nats stream edit ORDERS --no-republish. Три места изменения:

  • Subject transform при сохранении.
  • Republish в живые темы.
  • Преобразования источников при копировании.

Что дальше​

TTL отдельных сообщений сокращает жизнь выбранной записи.

См. также​