CJSON: внутренний формат Reindexer для обработки данных

В Reindexer используется внутренний формат представления данных CJSON (Compact JSON). С его помощью решаются задачи:

1. Хранение - -tuple (используется в ядре Reindexer совместно с со структурой PayloadValue).
2. Передача данных по сети - «транспортный» CJSON.

Структура CJSON для обоих случаев схожая, однако между -tuple и «транспортным» CJSON есть различия в способах хранения значений полей документа.

Структура CJSON

Каждое поле в СJSON представлено в виде ctag, который кодирует тип, имя и двоичное представление данных поля в формате, зависящем от типа.

Формат ctag представлен в таблице:

Возможные значения поля TypeTag:

Словарь имён (TagsMatcher)

TagsMatcher представляет из себя словарь имён, в котором каждому уникальному имени поля сопоставлено числовое значение. Этот механизм используется для более компактной сериализации документов. Объект TagsMatcher'a создаётся в момент создания неймспейса и дальше накапливает новые теги/имена по мере их появления в документах (при этом старые теги никогда не удаляются).

Общее максимальное количество уникальных тегов в одном неймспейсе не может превышать 4095, поэтому не рекомендуется использовать в качестве имён полей различного рода хеши. При достижении этого лимита невозможно будет добавить в неймспейс документ с каким-либо новым уникальным именем поля, которое никогда не встречалось ранее. На текущий момент, единственный способ полностью очистить TagsMatcher от старых имён (если они не используются) это полное пересоздание неймспейса из бэкапа, используя reindexer_tool.

Помимо словаря в объекте TagsMatcher также содержатся:

• StateToken - случайное uint32-значение, идентифицирующее конкретный объект словаря. Используется для синхронизации словарей между узлами;
• Version - текущая версия словаря. Инкрементально возрастает при добавлении новых полей. Каждая следующая версия словаря целиком содержит в себе предыдущую, а также включает как минимум одну новую пару “тег-имя”.

Для правильного декодирования CJSON объекты TagsMatcher для каждого неймспейса синхронизируются между клиентом и сервером, а также между лидером и всеми фолловерами в кластере, используя StateToken и Version.

Важно отметить то, что при формировании новых тегов для словаря не имеет значения уровень вложенности имён, их тип и сколько раз каждое из них встретится в документе. Например, для следующего JSON-документа:

{
    "field1": 123,
    "arr": [
    {
      "obj": {
        "field1": "string",
        "field2": 321
      },
      "arr": [ 1, 1],
      "flag": false
    },
    {
      "obj": {
        "field1": 10.7,
        "arr": []
      },
      "field1": [1, 1]
    }
  ],
  "flag": true
}

в словаре будет создано всего 5 уникальных тегов:

Текущий статус TagsMather‘а (Version, StateToken, текущее и максимальное количества тегов в словаре) отображаются в неймспейсе #memstats в поле tags_matcher.

Хранение массивов

Массивы могут храниться двумя различными способами:

• однородный массив из элементов одного типа,
• смешанный массив из элементов разных типов.

Оба типа массивов в дополнение к ctag используют atag.

atag — формат тега массива

atag — тег (4 байта, int), с помощью которого кодируется количество и тип элементов массива:

Формат пакета CJSON

names_dictionary :=
  <varint(count)>
  [[<varint(string length)>, <name char array>],
   [<varint(string length)>, <name char array>],
   ...

Offset to names dict не всегда присутствует в пакете. Если пакет начинается с TAG_END, за ним размещается Offset to names dict. Если же пакет начинается не с TAG_END, то в нем вообще не содержится словарь имен.

Формат записи:

record :=
  ctag := (TAG_OBJECT,name)
    [field :=
      ctag := (TAG_VARINT,name) data := <varint> |
      ctag := (TAG_DOUBLE,name) data := <8 byte double> |
      ctag := (TAG_BOOL,name) data := <1 byte: 0 - False, 1 - True> |
      ctag := (TAG_STRING,name) data := <varint(string length)>, <char array> |
      ctag := (TAG_NULL,name) |
      ctag := (TAG_ARRAY,name)
        data := atag := (TAG_OBJECT|TAG_VARINT|TAG_DOUBLE|TAG_BOOL, count)
        array := [ctag := TAG_XXX] <data>,[[ctag := TAG_XXX>]<data>]] ... |
      ctag (TAG_OBJECT,name)>
        [subfield := field]
      ...
      ctag := (TAG_END)
    ]
    ...
  ctag := (TAG_END)

Пример объекта CJSON

• Объект в JSON
• Объект в CJSON
• Словарь имен объекта

{
  "name": "Hello",
  "year": 2010,
  "articles": [
    1,
    2,
    3,
    4,
    5
  ],
  "info": {
    "name": "Info"
  },
  "table": [
    [1,2],
    [3,4]
  ]
}

(TAG_OBJECT)                                    06
  (TAG_STRING,1) 5,"Hello"                      0A 05 48 65 6C 6C 6F
  (TAG_VARINT,2) 2010                           10 B4 1F
  (TAG_ARRAY,3) (TAG_VARINT,5) 1 2 3 4 5        1B 05 00 00 00 01 02 03 04 05
  (TAG_OBJECT,4)                                26
     (TAG_STRING,1) 4,"Info"                    0A 04 49 6E 66 6F
  (TAG_END)                                     07
  (TAG_ARRAY,5) (TAG_OBJECT,2)                  2D 02 00 00 06
    (TAG_ARRAY,0) (TAG_VARINT,2) 1 2            05 02 00 00 02 01 02
    (TAG_ARRAY,0) (TAG_VARINT,2) 3 4            05 02 00 00 02 03 04
(TAG_END)                                       07

1 - "name"
2 - "year"
3 - "articles"
4 - "info"
5 - "table"

-tuple и «транспортный» CJSON

-tuple

-tuple в формате CJSON используется для обработки документов ядром Reindexer. Его применение позволяет решить проблему с отсутствием унифицированной структуры записей в документоориентированных БД, когда каждая запись может иметь уникальные поля и нужно где-то хранить информацию по ее неиндексным полям.

-tuple - всегда самый первый (с индексом 0) элемент записи (PayloadValue -> Item). В нем хранятся либо ссылки на индексные поля записи, либо сами значения — в случае если поле неиндексное.

В CJSON каждое поле записи (документа, строки неймспейса) описывается с помощью ctag (и carraytag). В ctag хранится:

• тип поля (TypeTag),
• целочисленные номер имени поля (NameIndex),
• индекс поля в PayloadValue (FieldTag) - если поле индексное .

Если поле индексное, в FieldTag хранится его индекс в PayloadType и IndexesStorage (этот индекс также позволяет вычислить его смещение в PayloadValue). При этом в -tuple сериализуется только ctag, а само значение находится в PayloadValue (доступ к нему можно получить через метод PayloadIface::Get(ctag.field)).

Если поле неиндексное, значение ctag.field = -1. Значение поля сериализуется сразу за ctag.

Все документы неймспейса хранятся в NamespaceImpl (массив items_) в виде PayloadValue. У каждого такого документа в первом поле находится значение -tuple.

«Транспортный» CJSON

«Транспортный» CJSON используется для отправки данных по сети. С ним работают cproto-клиенты, grpc-клиенты, rpc/grpc-серверы. Так же он используется при проксировании в синхронном кластере и шардировании.

В «транспортным» CJSON (в отличие от -tuple, используемого ядром) каждое поле, независимо от того, индексное оно или неиндексное, кодируется без ссылок на его значение в PayloadValue. То есть значение каждого поля хранится непосредственно внутри объекта CJSON. Ссылки на индексные поля в данном случае использоваться не могут, поскольку клиент может не иметь данных PayloadType.

Пример обхода структуры CJSON (код из skipCjsonTag):

void skipCjsonTag(ctag tag, Serializer &rdser) {
	const bool embeddedField = (tag.Field() < 0);
	switch (tag.Type()) {
		case TAG_ARRAY: {
			if (embeddedField) {
				carraytag atag = rdser.GetUInt32();
				for (int i = 0; i < atag.Count(); i++) {
					ctag t = atag.Tag() != TAG_OBJECT ? atag.Tag() : rdser.GetVarUint();
					skipCjsonTag(t, rdser);
				}
			} else {
				rdser.GetVarUint();
			}
		} break;

		case TAG_OBJECT:
			for (ctag otag = rdser.GetVarUint(); otag.Type() != TAG_END; otag = rdser.GetVarUint()) {
				skipCjsonTag(otag, rdser);
			}
			break;
		default:
			if (embeddedField) rdser.GetRawVariant(KeyValueType(tag.Type()));
	}
}

Основные модули работы с CJSON

В Reindexer для работы с CJSON используются следующие основные модули: