Внешние справочники

• Плоский: даже если в исходном справочнике есть иерархия, перед подключением к подсказкам он должен быть переведен в плоский вид. 
• С заголовочной строкой: она используется в настройках.
• В названии самого справочника и конфигурационного файла можно использовать только строчные латинские буквы, цифры и подчеркивание.
• В заголовках полей можно использовать только латинские буквы и подчёркивание.
• В кодировке UTF-8 (без BOM).

Особенности и ограничения

Если надо, чтобы подсказки возвращали вычисляемые поля (например, «ФИО», составленное из фамилии, имени, и отчества) — эти столбцы тоже должны быть в справочнике. Сами подсказки их делать не умеют.

Если нужен поиск по синонимам (хендай, хенде → hyundai) или с учетом опечаток (менежер → менеджер) — варианты написания нужно перечислить в отдельном столбце справочника через запятую. Подсказки не умеют автоматически искать с учетом опечаток или придумывать синонимы.

Если одни записи справочника более «весомые», чем другие (например, головные организации против филиалов), то веса должны быть предрассчитаны для всех записей и вынесены в отдельный столбец — сами подсказки этого делать не будут.

Подсказки используют префиксный поиск. Вот что это значит на примере. Допустим, есть запись справочника «Волкова Татьяна Анатольевна». Тогда:

• запрос «волк» найдет запись;
• запрос «волкова» найдет запись;
• запрос «волкова тат» найдет запись;
• запрос «волкова татьяна» найдет запись;
• запрос «волк тат» не найдет запись;
• запрос «волк татьяна» не найдет запись.

Таким образом, в тексте запроса допускается частичное совпадение только по последнему слову, по предыдущим словам совпадение должно быть полным.

По умолчанию значения полей подсказки трактуют как строки, даже если по факту это числа или даты.

Пример справочника

# название справочника
# наш пример — справочник сотрудников
name: employees
# описание справочника (21.7+)
# необязательно, используется только для показа в админке
meta:
  title: Сотрудники
  description: Справочник сотрудников компании
  source: Отдел кадров
# настройки чтения CSV файла
# необязательно, значения по умолчанию описаны ниже
csv:
  quote: '"'
  delimiter: ','
  endOfLine: '\n'
  encoding: UTF-8
# какие есть поля и как их использовать
fields:
  # Исправлять латинскую раскладку, по умолчанию true
  switch_layout: false
  # какие поля участвуют в поиске по идентификаторам
  # необязательно, по умолчанию не задано
  ids:
    hid: ~
    inn: ~
  # какие поля участвуют в полнотекстовом поиске (обязательно хотя бы одно)
  # для полей можно указать параметр boost — вес для ранжирования
  #   чем больше вес, тем «весомее» считается совпадение по этому полю
  #   например, если вес по fullname = 10, а по email = 1,
  #   то совпадение по ФИО считается весомее, чем по адресу эл. почты
  #   по умолчанию вес = 1
  search:
    fullname:
      boost: 10
    email: ~
    phone: ~
  # по каким полям фильтровать
  # необязательно, по умолчанию не задано
  filter:
    department: ~
  # по какому полю ранжировать
  # необязательно, по умолчанию не задано
  # чем больше значение, тем выше ранжируется соответствующая запись справочника
  # если указано несколько полей, то значения умножаются
  # по умолчанию вес = 1
  boost:
    salary: ~
  # по какому полю сортировать
  # необязательно, по умолчанию равно настройке fields.value + ALPHA_NUMERIC
  # принцип сортировки:
  #   ALPHA_NUMERIC - по алфавиту (с честной сортировкой чисел)
  #   TOKEN_COUNT - по количеству слов (чем меньше слов, тем выше позиция)
  sort:
    fullname:   TOKEN_COUNT
    department: ALPHA_NUMERIC
  # какое поле показывать в списке (suggestion.value, обязательно)
  value: fullname
  # какое поле содержит полное значение одной строкой
  # необязательно, по умолчанию равно настройке fields.value
  unrestricted_value: fullname_with_position
  # какие поля возвращать в объекте подсказки (suggestion.data)
  # необязательно, по умолчанию не задано (suggestion.data == null)
  data:
    name: ~
    surname: ~
    patronymic: ~
    email: ~
    phone: ~
    position: ~
    department: ~

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

fields:
    ...
    geolocate:
        latitude: {название поля с широтой}
        longitude: {название поля с долготой}
    ...

Начиная с версии 19.11 можно явно указать тип полей справочника. Поддерживаются типы: int, float, bool, str.

fields:
  ...
  data:
    postal_code: str
    is_closed: bool
    address_qc: int
    geo_lat: float
    ...

По умолчанию для boost и geolocate полей устанавливается тип float, для всех остальных полей – string. Для boost-полей тип может быть только float или int, а для geolocate-полей тип может быть только float.

1. Сохранить конфигурацию в файл {name}.yaml, где {name} — название справочника, как указано в самом первом параметре конфигурации.
   Для нашего примера это employees.yaml
2. Создать на сервере каталог SGT_ROOT/configuration/outward/ и скопировать в него файл конфигурации.
   Для нашего примера итоговый путь к файлу будет /opt/suggestions/configuration/outward/employees.yaml

Справочник:

1. Сохранить справочник в файл {name}.csv, где {name} — название справочника, как указано в конфигурации.
   Для нашего примера это employees.csv
2. Запаковать справочник в zip-архив вида {name}.zip, где {name} — название справочника, как указано в конфигурации.
   Для нашего примера это employees.zip
3. Создать на сервере каталог SGT_ROOT/dictionaries/{name}/ и скопировать в него архив со справочником.
   Для нашего примера итоговый путь к файлу будет /opt/suggestions/dictionaries/employees/employees.zip

Чтобы «Подсказки» увидели справочник, перезапустите их либо используйте API загрузки.

Поиск по справочнику

Аналогично «родным» справочникам:

POST /suggestions/api/4_1/rs/suggest/employees HTTP/1.1
Host: suggestions.evercorp.ru
Content-Type: application/json

{
  "query": "Василий"
}

Фильтрация

Поддерживается стандартный параметр count и фильтрация (если настроена фильтрация, параметр filter в конфигурации справочника):

POST /suggestions/api/4_1/rs/suggest/employees HTTP/1.1
Host: suggestions.evercorp.ru
Content-Type: application/json

{
  "query": "Василий",
  "filters": [{"department": "Маркетинг"}, {"department": "ИТ"}]
  "count": 5
}

Поиск по идентификатору

Работает, если настроен параметр ids в конфигурации справочника:

POST /suggestions/api/4_1/rs/findById/employees HTTP/1.1
Host: suggestions.evercorp.ru
Content-Type: application/json

{
  "query": "1024"
}

Поиск ближайшего объекта

Работает в версиях 19.11+, если настроен параметр geolocate в конфигурации справочника. Работает аналогично геолокации для адресов – возвращает ближайшие объекты по заданным координатам:

POST /suggestions/api/4_1/rs/geolocate/postal_unit HTTP/1.1
Host: suggestions.evercorp.ru
Content-Type: application/json

{
  "lat": 55.763938,
  "lon": 37.637281,
  "radius_meters": 10000,
  "count": 15
}

Геолокация работает не только через POST, но и через GET:

GET /suggestions/api/4_1/rs/geolocate/postal_unit?lat=55.763938&lon=37.637281 HTTP/1.1
Host: suggestions.evercorp.ru

Параметры запроса:

lon

count

radius_meters

$("#manager").suggestions({
  type: "employees",
  ...
});

Если конфигурация справочника допускает, можно использовать фильтрацию:

$("#manager").suggestions({
  type: "employees",
  params: {
    filters: [
      { "department": "Отдел закупок"}
    ]
  }
});