Разбор датасета и схема

Импорт данных обычно начинается с догадки. Вы смотрите на записи, решаете, какое поле — заголовок, какое — фасет, какое хранит цену, и создаёте схему коллекции вручную. Если догадка неверна, вы узнаёте об этом позже — по плохим результатам поиска.

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

• профиль образца: найденные поля, наблюдаемые типы и полноту заполнения;
• предложение: готовое сопоставление ваших полей с ролями вроде title, price или category, включая получившуюся схему и query_by;
• оценку возможностей: какие функции платформы эти данные способны поддерживать.

Ничего не записывается, пока вы не подтвердите.

Прежде чем начать

• Полный API-ключ — подтверждение профиля записывает данные для коллекции.
• Репрезентативный образец: до 100 документов или 2 МБ текста.
• Коллекция для самого preview не нужна. Разбор — это способ решить, что создавать.

Что вы получите

Схему коллекции, которую не пришлось придумывать, и сохранённый согласованный профиль, которого будут придерживаться последующие импорты.

Шаги

1. Отправьте образец

curl -X POST https://api.aacsearch.com/v1/ingest/preview \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "source": "documents",
    "documents": [
      { "id": "1", "title": "Дрель аккумуляторная 18В", "brand": "Acme", "price": 89.0, "in_stock": true },
      { "id": "2", "title": "Гайковёрт 18В", "brand": "Acme", "price": 119.0, "in_stock": false }
    ]
  }'

source определяет, как читается образец:

Для текстовых источников передавайте content вместо documents — вместе они дают 400. Используйте source_name, чтобы указать происхождение, и total_count, чтобы сказать, что реальный датасет больше образца.

При необходимости передайте roles, чтобы заявить то, что вы уже знаете, например {"price": "price"}: тогда предложение строится от вашего знания, а не от догадки. Заданные вами поля помечаются role_source: "explicit", выведенные — "inferred".

Ожидаемый результат: 200 с profile, proposal и capabilities.

2. Прочитайте профиль

{
  "profile": {
    "version": 1,
    "sample_count": 2,
    "truncated": false,
    "fields": [
      {
        "name": "title",
        "types": ["string"],
        "present_count": 2,
        "null_count": 0,
        "coverage": 1,
        "role": "title",
        "role_source": "inferred",
        "reasons": ["unique text with high coverage"]
      }
    ],
    "domain_candidates": ["commerce", "generic"],
    "warnings": []
  },
  "proposal": { "fields": [], "query_by": [], "roles": {}, "…": "…" },
  "capabilities": [{ "id": "keyword_search", "data": "candidate", "…": "…" }]
}

Профиль описывает образец, а не весь датасет:

3. Проверьте, какие возможности поддерживают данные

capabilities[] отвечает на главный вопрос до того, как вы начнёте строить на этой схеме. У каждой записи есть id — keyword_search, facets, semantic_search, image_search, assistant или recommendations — и она оценивает одно измерение:

По вашему образцу оценивается только data. Право доступа по тарифу и конфигурация проверяются в другом месте — см. лимиты и оплату.

Проверка: нужные вам возможности сообщают data: "candidate". Если нет — добавьте недостающее поле в источнике и отправьте образец снова: у preview нет побочных эффектов, поэтому итерируйте здесь, а не после импорта.

4. Подтвердите профиль

Подтверждение сохраняет принятое предложение для коллекции, чтобы последующие импорты следовали согласованным ролям, а не выводили их заново.

curl -X PUT https://api.aacsearch.com/v1/collections/products/profile \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "source": "documents",
    "documents": [ { "id": "1", "title": "Дрель аккумуляторная 18В", "price": 89.0 } ],
    "roles": { "title": "title", "price": "price" }
  }'

Тело имеет ту же форму, что и у preview — образец и выбранные вами roles. Подтверждение заново выполняет разбор и сохраняет результат.

Ожидаемый результат: сохранённый профиль в той же форме, что и ответ preview.

Проверка: GET /collections/products/profile возвращает его. Повторное подтверждение заменяет профиль, поэтому следующий импорт пойдёт по новому решению.

Частые проблемы

Далее

• Инкрементальная индексация — создайте коллекцию и импортируйте данные.
• CMS-коннекторы — тот же разбор внутри сценария Sources.
• Профили поиска и релизы — что настроить после схемы.