API результатов кросс-идентификации

[Kraysent]

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

Цель: предоставить пользователю возможность по итогам загрузки таблицы в HyperLeda просматривать результаты кросс-идентификации объектов и, при необходимости, их корректировать.

[Kraysent]

После загрузки новой таблицы через метод API /api/v1/admin/table (см. документацию API) начинается кросс-идентификация. Этот процесс могут успешно пройти не все загруженные объекты. В частности, пока что вижу у каждого входящего объекта четыре возможных статуса (для пользователя) при кросс-идентификации:

• unprocessed - кросс-идентификация этого объекта ещё не началась, нужно ждать.
• new - кросс-идентификация прошла успешно и заключила, что объекта в нашей базе данных нет, поэтому ему присвоен новый pgc-номер.
• existing - кросс-идентификация прошла успешно и заключила, что это один из уже существующих в базе объектов.
• collided - кросс-идентификация не смогла однозначно определить, что это за объект - в базе данных ему соответствовало два и более существующих объекта.

Пока что предлагается сделать два новых метода API для просмотра результатов кросс-идентификации и для разрешения коллизий при кросс-идентификации. В частности:

Просмотр результатов

GET /api/v1/admin/table/status - метод для получения статуса загрузки объектов таблицы. Принимает в качестве обязательного параметра только table_id - id таблицы в нашем реестре таблиц rawdata. В качестве ответа отдаёт список объектов, у каждого из которых есть:

• id: str - уникальный идентификатор объекта в его таблице.
• status: enum[unprocessed, new, existing, collided] - статус по итогам кросс-идентификации в соответствии с описанием выше.
• status_info: dict - дополнительная информация о статусе. Так:
  • для статуса unprocessed тут можно оставить пустоту
  • для статуса new - поле pgc, в котором будет написан новый pgc-номер, присвоенный по итогам кросс-идентификации
  • для статуса existing - поле pgc, в котором написан pgc-номер объекта, который уже присутствует в нашей БД и к которому кросс-идентификация отнесла новый объект.
  • для статуса collided - поле collided_with, в котором лежит список из двух и более pgc-номеров, с которыми произошла коллизия.

Для более удобного пользования методом можно добавить дополнительные параметры для фильтрации - например, чтобы показать только объекты, у которых случилась коллизия, можно добавить параметр status=collided.

Разрешение коллизий

POST /api/v1/admin/table/status - метод для ручного присваивания объектам pgc-номеров. Так, если в результате кросс-идентификации случились коллизии, тут можно будет передать, какие pgc-номера присвоить каким объектам. При этом я пока что не вижу необходимости где-либо проверять, что у переданных здесь объектов вообще случалась коллизия - если пользователь хочет явным образом перезаписать pgc-номер у объекта (даже если мы по результатам кросс-идентификации успешно присвоили ему другой номер), я не вижу особенных причин не дать пользователю этого сделать.

Для конкретики, я представляю себе передаваемые сюда параметры примерно следующим образом:

{
    "table_id": 1234, // id таблицы, в которой мы хотим pgc объектов
    "overwrites": [
        {
            "id": "SDSS_ID_1", // id объекта в оригинальной таблице
            "pgc": 8765 // id объекта в HyperLeda
        },
        {
            "id": "SDSS_ID_2",
            "pgc": 5678
        }
    ]
}

И в итоге объекту SDSS_ID_1 будет явным образом присвоен pgc номер 8765.

[d-makarov-d]

Re: просмотр результатов

Так, опишу какие статусы процесса транзакции с 0 на 1 уровень сейчас существуют, чтобы потом решить, что из этого показывать позьзователю.

Сама транзакция может быть в состояниях:

• Запущена (Также известно, на какой стадии. Для стадии кросс идентификации есть коллбак с прогрессом пообъектно)
• Ошибка (Из за битой метадаты, например указана несуществующая колонка для имени и т.д)
• Завершена (И здесь уже инфа для каждого конкретного объекта)
  • id - такой колонки в сырых данных может не быть. Мб использовать индекс?
  • status - тут примерно так и есть
  • status_info - тут поле collided гораздо сложнее, чем может показаться
    По полю collided - то есть фэйл обработки конкретной строчки - может быть много разных фейлов:
• Ошибка обработки (Напр. невалидные координаты в колонке координат, нечисловое значение в числовом поле)
• Коллизия кросс идентификации: Много разных вариантов коллизий, на данный момент 9 (все варианиы в файле app/domain/model/params/cross_identification_result.py). И каждый вариант коллизии можно отобразить по своему

Re: Разрешение коллизий

Здесь, скорее всего, надо добавить еще варианты решения. Потому что не все коллизии кросс идентификации можно решить присвоением существующего pgc-номера (наверное, вопрос открытый). И, возможно, надо добавить возможность скипнуть строчку или подредактирвать ее для ошибок обработки сырых данных

[Kraysent]

По итогам встречи модифицирую интерфейс взаимодействия по загрузке данных. Пока что предалгаю сделать 4 новых метода для взаимодействия:

• POST /api/v1/admin/table/process - метод для начала обработки загруженных данных.
• GET /api/v1/table/status/stats - метод для получения статистики обработки загруженных данных.
• GET /api/v1/table/status - метод для получения подробной информации о каждом объекте.
• POST /api/v1/admin/table/status - метод для утверждения статусов загруженных объектов. В рамках него же можно ручным образом изменить эти статусы.

Теперь подробнее про загрузку таблицы ручным образом:

Загрузка данных

• Сначала пользователь создаёт пустую таблицу при помощи POST /api/v1/admin/table, в которой указывает всю необходимую метаинформацию о таблице. В частности, сюда идёт название таблицы, название всех столбцов, типы данных во всех столбцах, единицы измерения во всех столбцах, какой столбец является первичным ключом и прочее. Если пользователь загрузил какую-то неправильную информацию (несуществующие единицы измерения, несуществующий тип данных и прочее), мы её провалидируем здесь и в случае неправильной метаинформации отдадим ошибку. Здесь же указывается, какие столбцы отвечают за прямое восхождение, склонение и имя объекта, эта информация будет использована в дальнейшем для кросс-идентификации.
• Далее пользователь загружает в только что созданную таблицу данные при помощи POST /api/v1/admin/table/data. Если таблица большая, он может делать это несколько раз, разбив данные на батчи по несколько тысяч объектов (например). Этот метод будет валидировать, что загруженные данные соответствуют типам, указанным в столбцах. Если пользователь попытался в целочисленный столбец загрузить строки, мы отдадим ошибку в ответе этого метода.

Обработка объектов

• Далее, если пользователь загрузил все данные в таблицу, которые хотел, он может стартовать обработку этой таблицы на нашей стороне. Делается это методом POST /api/v1/admin/table/process. По умолчанию он не принимает никаких параметров, кроме table_id - id таблицы, которую он хочет начать обрабатывать, но если у загружающего есть желание начать обработку с какими-то конкретными параметрами кросс-идентификации, он может их передать сюда в виде:

  {
      "table_id": 12345,
      "cross_identification": { // это поле можно не передавать, тогда будут значения по умолчанию
          "inner_radius_arcsec": 1.5,
          "outer_radius_arcsec": 5
      }
  }

  Если ничего не передано, метод сам выберет нужные параметры кросс-идентификации (пока что просто возьмёт параметры по умолчанию) и начнёт обработку с ними.
• После начала пользователь может начать проверять статус обработки. Есть два способа это сделать:

  • Для получения статистики есть метод GET /api/v1/table/status/stats - принимает table_id, отдаёт статистику обработки этой таблицы - число объектов в каждом статусе. Например:

    {
        "data": {
            "processing": {
                "unprocessed": 120,
                "new": 50,
                "collided": 200,
                "existing": 27
            }
        }
    }

    Если загружающему не нравится статистика, он может перезапустить кросс-идентификацию, вызвав метод POST /api/v1/admin/table/process ещё раз. Тогда текущая обработка будет прервана, и запустится новая обработка с новыми параметрами.

  • Для подробной информации есть метод GET /api/v1/table/status - принимает table_id, отдаёт текущие результаты обработки. В ответе этого метода будут перечислены все объекты, которые находятся в таблице и подвергаются обработке сейчас. В нём нужна будет фильтрация, поэтому этот метод будет принимать помимо обязательного table_id ещё и параметры:

    • status - фильтрация по статусу, если передан, метод будет отдавать только объекты с соответствующим статусом. Например, status=collided отдаст только объекты, для которых кросс-идентификация не смогла заключить, что это за объект.
    • page_number, page_size - номер и размер страницы. Нужны для пагинации, т.е. отображения не всех объектов сразу - если загружается таблица из миллиона объектов, мы не хотим отдавать в API весь миллион объектов, только страницами по сотням объектов.

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

    • id: str - уникальный идентификатор объекта в его таблице.
    • status: enum[unprocessed, new, existing, collided] - статус по итогам кросс-идентификации в соответствии с описанием выше.
    • status_info: dict - дополнительная информация о статусе. Так:
      • для статуса unprocessed тут ничего нет
      • для статуса new тоже ничего нет
      • для статуса existing - поле pgc, в котором написан pgc-номер объекта, который уже присутствует в нашей БД и к которому кросс-идентификация отнесла новый объект.
      • для статуса collided - поле collided_with, в котором лежит список из объектов с которыми произошла коллизия. Тут могут лежать pgc-номера, если коллизия произошла с объектами из базы данных, либо id объектов, если коллизия произошла с объектом и этой же таблицы.

    Например:

    {
        "data": {
            "objects": [
                {
                    "id": "SDSS-123",
                    "status": "unprocessed"
                },
                {
                    "id": "SDSS-1234",
                    "status": "new"
                },
                {
                    "id": "SDSS-12345",
                    "status": "existing",
                    "status_info": {
                        "pgc": 1234
                    }
                },
                {
                    "id": "SDSS-123456",
                    "status": "collided",
                    "status_info": {
                        "collided_with": [
                            {
                                "pgc": 12345
                            },
                            {
                                "id": "SDSS-1234567"
                            }
                        ]
                    }
                },
            ]
        }
    }

Разрешение коллизий и загрузка на 1-й уровень

• Последним этапом обработки идёт утверждение пользователем правильности обработки. Для этого есть метод POST /api/v1/admin/table/status, при помощи которого пользователь загружает корректно идентифицированные объекты на 1-й уровень базы данных. Если есть объекты, у которых пользователь явно хочет перезаписать статус (вместо colliding выставить existing и явным образом указать pgc-номер, например), то он может передать их в этот метод вот таким образом:

  {
      "table_id": 12345,
      "overrides": [
          { // этому объекту будет явным образом присвоен pgc-номер 123456, вне зависимости от того, существует объект с pgc-номером 123456 уже или нет.
              "id": "SDSS-12345",
              "pgc": 123456
          },
          { // этому объекту будет присвоен следующий свободный pgc-номер.
              "id": "SDSS-1234567"
          }
      ]
  }

  Если pgc-номер указан явно, то он может быть создан, если его не было до этого. Это позволит безболезненно присвоить pgc-номера для объектов, у которых pgc номер уже был из старой версии HyperLeda.

  В методе не обязательно присваивать статусы всем необработанным объектам - даже если в поле overrides передать пустой список, он просто загрузит успешно обработанные объекты и не будет ничего делать с объектами в статусе collided. Если пользователь захочет после обработки дозагрузить объекты, которые находятся в статусе collided, он может вызывать метод POST /api/v1/admin/table/status столько раз, сколько хочет, каждый раз догружая те объекты, которые он обработал.

Дополнения:

• В текущей версии API ничего не запрещает пользователю полностью обработать и загрузить обработанные объекты на 1-й уровень, а потом оставшиеся объекты переобработать с другими параметрами кросс-идентификации и загрузить их в другой раз. Позволять пользователю так делать, или нет - нужно решить отдельно, пока что ничего это не запрещает. Если эту функциональность захотим оставить, то в методе начала обработки нужно будет учесть, что обработка должна начаться только для объектов, которые ещё не были загружены на первый уровень, а не для всех объектов таблицы.
• Для загрузки на 1-й уровень нужно будет где-то передавать параметры, из которых можно будет понять, как переводить столбцы из оригинальной таблицы в каталоги 1-ого уровня, это тоже нетривиальная задача, но её предлагаю обсудить отдельно.