Data model¶

Загрузка через веб-интерфейс¶

Чтобы загрузить модель данных через веб-интерфейс TDG, выполните следующие шаги:

1. Откройте веб-интерфейс на экземпляре, входящем в набор реплик с кластерной ролью runner. Если вы используете уже развернутый TDG-кластер, URL экземпляра будет следующий: http://172.19.0.2:8082.

2. В веб-интерфейсе выберите вкладку Model.

3. Вставьте созданную модель данных в поле Request.

4. Нажмите Submit. Если модель данных загружена успешно, в окне Response появится ответ OK.

Загрузка в составе zip-архива¶

Загрузить модель данных можно также в составе zip-архива вместе с файлом конфигурации. Для этого:

1. Упакуйте в zip-архив:

   • модель данных в файле с расширением .avsc, например, model.avsc;

   • файл конфигурации config.yml.

2. Загрузите архив в TDG согласно инструкции.

Задание отношений между объектами¶

Явно задавать связи между объектами нужно:

• для валидации внешних ключей при вставке объектов;

• для запросов связанных объектов через GraphQL.

Чтобы указать такую связь, используется поле relations в теле описания типа объекта. Это поле игнорируется существующими парсерами Avro Schema. Связываемые поля (внешние ключи в терминологии SQL) должны быть объявлены на уровне типов объектов.

Например, чтобы задать связь между страной и ее городами, требуются следующие поля:

• title (Country) – первичный ключ доступен через обращение к типу объекта Country.title;

• country (City) – внешний ключ доступен через обращение к типу объекта City.country.

Пример поля relations из заданной ранее модели данных:

{
    "relations": [
        {
            "name": "city_relation",
            "to": "City",
            "count": "many",
            "from_fields": "title",
            "to_fields": "country"
        },
        ...
    ]
}

где:

• name – название поля, через которое можно получить связанные объекты в GraphQL-запросах;

• to – тип объекта, с которым устанавливается связь;

• count – вид связи. Возможные значения:

  • one – связь один к одному;

  • many – связь один ко многим;

• from_fields – название поля или индекса, содержащего первичный ключ. Возможные значения:

  • название индекса ("from_fields": "title");

  • название поля ("from_fields": "field_name");

  • список названий полей ("from_fields": ["field_name1", "field_name2"]);

• to_fields – название поля или индекса, содержащего внешний ключ. Возможные значения:

  • название индекса ("to_fields": "country");

  • название поля ("to_fields": "field_name");

  • список названий полей ("to_fields": ["field_name1", "field_name2"]).

Все параметры поля обязательные.

Поле relations можно задать как с одной стороны отношения, так и с обеих. Поле указывается только в одном типе объекта, когда запрашивать данные в обратном направлении не требуется.

Дополним модель данных еще одним полем relations (City), чтобы можно было запрашивать данные в обоих направлениях. Полный пример может выглядеть так:

[
    {
        "name": "Country",
        "type": "record",
        "doc": "Страна",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "phone_code", "type": ["null", "string"]}
        ],
        "indexes": ["title"],
        "relations": [
            {"name": "city_relation", "to": "City", "count": "many", "from_fields": "title", "to_fields": "country"}
        ]
    },
    {
        "name": "City",
        "type": "record",
        "doc": "Город",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "population", "type": "int"},
            {"name": "capital", "type": "boolean"},
            {"name": "postcodes", "type": {"type":"array", "items":"int"}}
        ],
        "indexes": [
            {"name":"primary", "parts":["title", "country"]},
            "title",
            "country",
            "population",
            "postcodes"
        ],
        "relations": [
            {"name": "country_relation", "to": "Country", "count": "one", "from_fields": "country", "to_fields": "title"}
        ]
    }
]

Задание индексов (ключей)¶

Для задания индексов используется поле indexes в описании типа объекта. Поле не меняет поведение, регулируемое стандартом Avro Schema, а добавляет дополнительные ограничения на хранение и запросы. Если для типа объекта указаны индексы, TDG создает спейсы под этот тип.

Синтаксис поля indexes:

{
    "indexes": ["<index1>", <"index2">, <"index3">, ...]
}

Каждый индекс в поле indexes может быть задан в виде:

• строки с названием поля, по которому будет построен индекс ("indexes": ["title"]);

• словаря, на основе которого строятся составной индекс или индекс по полю вложенного объекта. Такой индекс указывается в следующем формате:

  {
      "name": "<index_name>",
      "parts": [
          {"path": "<field_name>", "collation": "<collation_type>"},
          {"path": "<field_name>", "collation": "<collation_type>"},
          ...
      ]
  }
  

  где:

  • name – название индекса, не совпадающее с именами существующих полей;

  • parts – части индекса. Включает в себя:

    • path – названия полей, по которым строится индекс;

    • collation (опционально) – способ сравнения строк. Возможные значения:

      • binary (по умолчанию) – бинарное сравнение ('A' < 'B' < 'a');

      • case_sensitivity – сравнение, зависящее от регистра ('a' < 'A' < 'B');

      • case_insensitivity – сравнение, не зависящее от регистра (('a' = 'A') < 'B' и 'a' = 'A' = 'á' = 'Á').

Пример составного индекса

{
    "name": "City",
    "type": "record",
    "fields": [
        {"name": "title", "type": "string"},
        {"name": "country", "type": "string"},
        {"name": "population", "type": "int"},
        {"name": "capital", "type": "boolean"},
        {"name": "postcodes", "type": {"type":"array", "items":"int"}}
    ],
    "indexes": [
        {"name":"primary", "parts":["title", "country"]},
        "title",
        "country",
        "population",
        "postcodes"
    ]
}

Пример индексации по полю вложенного объекта

Иногда требуется построить индекс по полю не из самого объекта, а из его вложенного объекта. Вложенный объект при этом создается, чтобы сгруппировать логически набор стандартных полей.

Например, представьте, что каждая страна (Country) в примере содержит дополнительный блок информации для туристов. Создадим новый тип объекта Info и сложный индекс в типе объекта Country. Тип объекта Info включается здесь непосредственно в тип объекта Country, поэтому индекс может сослаться на поле из Info:

[
    {
        "name": "Info",
        "type": "record",
        "doc": "Информация для туристов",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "info_text", "type": "string"}
        ]
    },
    {
        "name": "Country",
        "type": "record",
        "doc": "Страна",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "info", "type": "Info"},
            {"name": "phone_code", "type": ["null", "string"]}
        ],
        "indexes": [
            "title",
            {"name": "info_id", "parts": ["info.id"]}
        ]
    }
]

Распределение объектов по хранилищам¶

В случае распределенного хранилища данных объекты распределяются с использованием хеш-функции от первичного ключа объекта. Указать такой индекс можно в поле affinity.

Пример

Перед загрузкой модели с новым полем affinity удалите старую модель данных. Кроме того, проверьте список спейсов во вкладке Settings > Unlinked spaces в веб-интерфейсе TDG. Если в списке есть спейсы с типом объекта City, удалите их, чтобы избежать ошибки при загрузке новой модели.

Теперь дополните модель данных новым полем и загрузите модель в TDG:

{
    "name": "City",
    "type": "record",
    "doc": "Город",
    "fields": [
        {"name": "title", "type": "string"},
        {"name": "country", "type": "string"},
        {"name": "population", "type": "int"},
        {"name": "capital", "type": "boolean"},
        {"name": "postcodes", "type": {"type":"array", "items":"int"}}
    ],
    "indexes": [
        {"name":"primary", "parts":["title", "country"]},
        "title",
        "country",
        "population",
        "postcodes"
    ],
    "affinity": ["country"]
}

В примере города одной и той же страны размещены физически на одном хранилище. Поле affinity при этом содержит индекс из составного первичного ключа.

Атрибуты полей¶

Расширение для TDG дополняет список стандартных атрибутов полей Avro Schema:

• default_function (function) – задает для поля динамическое значение по умолчанию. Значение атрибута – это функция, файл с которой хранится в директории src в корне проекта. При вставке в спейс новой записи вызывается указанная функция, и результат функции становится значением для данного поля. Атрибут не стоит путать со стандартным атрибутом default, который задает для поля статическое значение;

• auto_increment (boolean) – значение true делает поле автоинкрементным. По умолчанию: false. Может использоваться в качестве числового идентификатора, уникального для объектов данного типа, даже при шардировании базы данных. Автоинкрементное поле обязательно должно иметь тип long. Атрибут несовместим с атрибутами default и default_function.

Пример

Расширьте тип объекта City этими атрибутами:

• задайте по умолчанию для поля population динамическое значение;

• добавьте поле с числовым идентификатором города.

Обновленные поля объекта могут выглядеть так:

{
    "name": "City",
    "type": "record",
    "fields": [
        {"name": "city_id", "type": "long", "auto_increment": true},
        {"name": "title", "type": "string"},
        {"name": "country", "type": "string"},
        {"name": "population", "type": "int", "default" : "count_population.call"}},
        ...
    ],
    ...
}