Формирование страниц с результатами поиска

Способ сортировки найденных документов, может принимать значения:

rlv - сортировка по релевантности (степени соответствия запросу);

tm - сортировка по дате последней модификации;

usrf - сортировка с использованием заданной пользователем функции вычисления релевантности;

<имя группировочного атрибута> - сортировка по значению указанного атрибута.

Поле g имеет структуру mode.attr.ngrp.ndoc.cur, где

mode - тип группировки. "0" - пустая. "1" - плоская или глубокая, если атрибут иерархический. "2" - широкая, имеет смысл только для иерархического атрибута.

attr - имя группировочного атрибута, по которому будет осуществляться группировка, в случае пустой группировки - пустая строка.

ngrp - число групп на одной странице.

ndoc - максимальное число документов в группе, документы сверх этого числа выкидываются на этапе выполнения группировки.

cur - значение атрибута для того узла иерархии, группы документов которого надо показать. Группы, не имеющие этого узла среди "родителей", выкидываются на этапе выполнения группировки. Имеет смысл только в случае иерархического атрибута. Значение по умолчанию: "1" (показать всю иерархию).

Заметим, что по умолчанию при выполнении запроса не делается никаких группировок. Для того чтобы получить ту или иную группировку, необходимо задать поле g. Группировка и сортировка происходят на этапе выполнения запроса, поэтому нельзя использовать функции работы с группами при построении выдачи, если до выполнения поиска не были заданы соответствующие поля.

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

Использование поля fa для фильтрации результатов поиска по группировочным атрибутам предпочтительнее, чем использование поисковых атрибутов в поисковом запросе (если в индексе есть поисковые атрибуты с теми же названиями и числовыми значениями), так как работает быстрее.

Поле fa может содержать несколько подвыражений, разделенных точкой с запятой. Каждое подвыражение состоит из названия атрибута, двоеточия и диапазона, в котором должен находиться указанный атрибут у прошедших фильтр документов. Диапазон указывается в виде двух чисел, разделенных дефисом. Если одно из задающих диапазон значений отсутствует, фильтр пройдут документы со значением атрибута большим или меньшим указанного.

Пример:

fa=price:40-50
fa=f:1-20;d:-30;t:40-

int UserInit(IInitContext *ictx, void **userHndl)

sub UserInit

Вызывается только один раз при старте поискового сервера, позволяет в случае необходимости инициализировать глобальные переменные и объекты. Для языка Perl вызывается без параметров.

Для C++ принимает два аргумента.

Первый является указателем на интерфейс контекста инициализации, декларированный в файле initcb.h. Функция IInitContext::GetCommandLine() позволяет получить аргумент директивы Options секции SearchPageTemplate конфигурационного файла.

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

int UserDone(void *userHndl)

Вызывается только один раз при завершении поисковой сессии.

int UserSearch(void *userHndl, IRequestContext* rc)

sub UserSearch

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

Если возвращает "0", выполнение запроса поисковым сервером прекращается, иначе сервер выполняет запрос, вызывая функции в той же последовательности, как и в следующем примере.

Интерфейс IRequestContext описан в pagecb.h.

int UserSearch(void* /*userHandler*/, IRequestContext* rc)
  {
      ISearchContext* ysc = rc->CreateContext();
      UserHttpHeaders(rc, ysc);
      UserRequest(ysc);
      rc->Search(ysc);
      UserReport(ysc);
      rc->DestroyContext(ysc);
      return 0;
  }

int UserHttpHeaders(ISearchContext* ysc)

sub UserHttpHeaders

void UserRequest(ISearchContext* ysc)

sub UserRequest

Вызывается до выполнения поискового запроса. Предназначена для преобразования полей поисковой формы в строку запроса на языке запросов Яндекса.

Использование этой функции полезно, если пользователи системы не знакомы с языком запросов и используют переключатели формы для уточнения области поиска.

В этой функции также можно установить поля запроса, влияющие на сортировку и группировку с помощью вызова FormFieldInsert.

На C++ текст запроса следует установить с помощью функции void IReqResults::SetUserRequest(const char *req), на Perl запрос является возвращаемым значением.

int UserReport(ISearchContext* ysc)

sub UserReport

Вызывается после выполнения запроса для формирования страницы с результатами поиска. Вся структура и дизайн страницы результатов задается в этой функции.

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

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

void HitStartBody(ISearchContext* ysc)

Hit::StartBody()

void HitEndBody(ISearchContext* ysc, int DocChanged, int FoundInBody, int FoundInCData)

Hit::EndBody(DocChanged, FoundInBody, FoundInCData)

Нижняя вывеска-табличка в подсвеченном документе.

DocChanged - равен "0", если документ не был изменен с момента последнего индексирования, в противном случае равен "1".

FoundInBody - найдено слов в теле документа (можно подсветить).

FoundInCData - найдено слов в области, не разрешающей подсветку (заголовок документа, меню, многострочные области ввода).

void HitFirst(ISearchContext* ysc)

Hit::First()

void HitLast(ISearchContext* ysc)

Hit::Last()

void HitLeft(ISearchContext* ysc, int word_num, int word_prev_num)

Hit::Left(word_num, word_prev_num)

Стрелочка-ссылка на предыдущее найденное слово.

word_num - номер найденного слова.

word_prev_num - номер предыдущего найденного слова.

void HitRight(ISearchContext* ysc, int word_num)

Hit::Right(word_num)

Стрелочка-ссылка на следующее найденное слово.

word_num - номер найденного слова.

int IIndexProperty::AttrCount()

Yx::AttrCount()

Возвращает число атрибутов в базе группировочных атрибутов.

const char *IIndexProperty::Attr(int attrnum)

Yx::Attr(attrnum)

Возвращает имя каждого группировочного атрибута.

attrnum - номер атрибута по порядку, от нуля до значения, возвращаемого AttrCount().

const char *IIndexProperty::CategName(const char *attr, long cat)

Yx::CategName(attr, cat)

Возвращает строковый идентификатор данного значения группировочного атрибута.

attr - имя группировочного атрибута.

cat - числовое значение атрибута.

Функцию можно использовать, если в индексном каталоге есть файл attr.c2n, где "attr" - значение первого аргумента функции (подробности см. в разделе База группировочных атрибутов).

long IIndexProperty::CategParent(const char *attr, long cat)

Yx::CategParent(attr, cat)

Возвращает родительское значение данного значения иерархического группировочного атрибута.

attr - имя группировочного атрибута.

cat - числовое значение атрибута.

Функцию можно использовать, если в индексном каталоге есть файл attr.c2p, где "attr" - значение первого аргумента функции (подробности см. в разделе База группировочных атрибутов).

time_t IIndexProperty::IndexModTime()

Yx::IndexModTime()

Возвращает время создания индекса в секундах от 00:00:00 1 января 1970 до момента последней модификации файла indexkey.

const char *IIndexProperty::ImagesUrl()

Yx::ImagesUrl()

Возвращает веб-адрес встроенного каталога с картинками.

Возвращаемое значение можно использовать, если в дизайне страниц результатов и подсветки используются изображения, выдаваемые Яндекс.Сервером.

Фактически функция возвращает строку вида http://host:port/images/ , где "host" - значение директивы Host, а "port" - значение директивы Port секции Server конфигурационного файла поискового модуля.

const char *IIndexProperty::ConfigParam(const char *directive)

Yx::ConfigParam(directive)

Возвращает аргумент указанной директивы конфигурационного файла.

Директива должна находится в подсекции UserParams секции Collection конфигурационного файла.

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

const char* MyTest = ysc->IndexProperty()->ConfigParam("MyTest");
if (MyTest && strcmp(MyTest, "yes") == 0)
    YxPrint(ysc, "Test!");

directive - ключ директивы, расположенной в подсекции UserParams секции Collection конфигурационного файла.

const char *IReqEnv::SearchUrl()

Yx::SearchUrl()

Возвращает префикс веб-страницы, принимающей поисковые запросы.

Возвращаемое значение нужно использовать в качестве значения атрибута action html-тага form.

Фактически функция возвращает строку вида http://host:port/id , где "host" и "port" - значения директив Host и Port секции Server конфигурационного файла поискового модуля, а id - идентификатор коллекции документов, то есть значение одноименного атрибута секции Collection конфигурационного файла поискового модуля.

Данные о поисковом запросе

До и после выполнения поискового запроса можно получить или изменить данные о нем.

const char *IReqEnv::HeaderIn(const char* key)

Yx::HeaderIn(key)

Возвращает значение HTTP-заголовка key, переданного клиентом в запросе к поисковому веб-серверу. Если указанного заголовка нет, возвращает "0" (C++) или неопределенное ("undef") значение (Perl).

key - название HTTP-заголовка в запросе

const char *IReqEnv::Environment(const char* key)

Yx::GetEnv(key)

Возвращает значение одной из переменных окружения, указанных ниже.

Если указанной переменной нет, возвращает "0" (C++) или неопределенное ("undef") значение (Perl). В переменной key может передаваться одна из следующих строк:

"QUERY_STRING" - часть URL поисковой страницы после знака вопроса, содержащая значения полей поисковой формы.

"SERVER_NAME" - доменное имя поискового сервера.

"SERVER_PORT" - порт, на котором работает поисковый сервер.

"SCRIPT_NAME" - часть относительного URL поисковой страницы до знака вопроса, abs_path в терминах RFC 2616.

"REMOTE_ADDR" - если в поисковом запросе есть HTTP-заголовок "X-Real-IP", будет возвращено значение этого заголовка, в противном случае - IP-адрес клиента, задавшего поисковый запрос.

int IReqEnv::FormFieldTest(const char* key, const char* value)

Yx::FormFieldTest(key, value)

Возвращает "1", если есть поле формы key со значением value, в противном случае - "0".

key - имя поля формы.

value - значение поля формы.

int IReqEnv::FormFieldCount(const char* key)

Yx::FormFieldCount(key)

Возвращает число одноименных полей.

key - имя поля формы.

const char *IReqEnv::FormField(const char* key, int num, bool encode = false)

Yx::FormField(key, num = 0)

Возвращает значение поля формы key. Если запрашиваемого поля нет, возвращает "0" (C++) или неопределенное ("undef") значение (Perl).

key - имя поля формы.

num - номер значения, начиная с 0.

encode - флаг, указывающий, нужно ли перекодировать запрещенные в HTML символы.

const char *IReqEnv::QueryString()

Yx::QueryString()

Возвращает все поля поисковой формы в формате адреса веб-страницы.

Возвращаемое значение может отличаться от значения Environment("QUERY_STRING"), так как учитывает результаты вызовов FormFieldInsert и FormFieldRemove из UserRequest.

void IReqEnv::FormFieldInsert(const char* key, const char* value)

Yx::FormFieldInsert(key, value)

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

key - имя поля формы.

value - значение поля формы, которое нужно вставить.

void IReqEnv::FormFieldRemove(const char *key, int num)

Yx::FormFieldRemove(key, num)

Функция удаляет данное поле из списка переданных полей.

key - имя поля формы.

num - номер значения, которое надо удалить, начиная с 0.

const char *IReqResults::ReqId()

Yx::ReqId()

Возвращает идентификатор запроса, назначенный поисковым сервером.

const char *IReqResults::Request()

Yx::Request()

Возвращает текст выполненного запроса, который может отличаться от введенного пользователем вследствие модификаций, выполненных в функции UserRequest.

int IReqResults::ErrorCode()

Yx::ErrorCode()

При неудачном поиске возвращает код ошибки.

const char *IReqResults::ErrorText(const char* lang = "ru")

Yx::ErrorText(lang)

При неудачном поиске возвращает описание ошибки.

lang - строка-идентификатор языка.

const char *IReqResults::WordStat()

Yx::WordStat()

Возвращает строку со статистикой найденных слов в формате слово:количество.

int ICluster::TotalDocCount(int prior)

Yx::TotalDocCount(prior = 0)

Возвращает число найденных документов с данным приоритетом релевантности.

prior - приоритет релевантности.

Значение "2" соответствуют совпадению фразы, "1" - строгому соответствию запросу, "0" - нестрогому соответствию запросу.

В числе, возвращаемом при меньшем значении параметра, суммируется количество документов с худшим приоритетом, так что при значении "0" функция возвращает полное число найденных документов.

long ICluster::CurCateg(const char *attr, int gMode)

Yx::CurCateg(attr, gMode)

Возвращает текущую группу (числовое значение атрибута), заданную при определении группировки.

attr - имя группировочного атрибута.

gMode - тип группировки, "1" - плоская или глубокая, если атрибут иерархический, "2" - широкая, имеет смысл только для иерархического атрибута.

const char *IReqEnv::SearchPageUrl(int npage, const char *attr)

Yx::SearchPageUrl(npage, attr)

Возвращает веб-адрес одной из страниц с найденными документами данной группировки. Этот адрес всегда начинается со строки, возвращаемой функцией SearchUrl.

npage - номер страницы по порядку, начиная с нуля.

attr - имя группировочного атрибута.

int ICluster::Count(int prior, const char *attr, int gMode)

Yx::Count(prior, attr, gMode)

Возвращает число найденных групп в данной группировке, полученное в процессе выполнения запроса.

prior - приоритет релевантности, как описано для функции TotalDocCount.

long ICluster::GroupCateg(int nGroup, const char *attr, int gMode)

Yx::GroupCateg(nGroup, attr, gMode)

Возвращает числовое значение группировочного атрибута, соответствующее данной группе.

nGroup - номер группы по порядку, начиная с нуля на первой странице, и с произведения (номер страницы)*(количество групп на странице) на последующих.

attr - имя группировочного атрибута.

gMode - тип группировки, "1" - плоская или глубокая, если атрибут иерархический, "2" - широкая, имеет смысл только для иерархического атрибута.

int ICluster::GroupDocCount(int prior, int nGroup, const char *attr, int gMode)

Yx::GroupDocCount(prior, nGroup, attr, gMode)

Возвращает число документов, попавших в данную группу в процессе группировки.

prior - приоритет релевантности, как описано для функции TotalDocCount. Полному числу документов в группе соответствует значение "0".

int ICluster::GroupRelevance(int nGroup, const char *attr, int gMode)

Yx::GroupRelevance(nGroup, attr, gMode)

Возвращает релевантность группы в виде положительного целого числа.

int ICluster::GroupPriority(int nGroup, const char *attr, int gMode)

Yx::GroupPriority(nGroup, attr, gMode)

Возвращает приоритет релевантности группы.

Значения "5", "6", "7" соответствуют совпадению фразы, "2", "3", "4" - строгому соответствию запросу, "0", "1" - нестрогому соответствию запросу.

long ICluster::DocId(int nGroup, int nDoc, const char *attr, int gMode)

Yx::DocId(nGroup, nDoc, attr, gMode)

Возвращает числовой идентификатор документа, назначенный при индексировании.

nGroup - номер группы по порядку, начиная с нуля на первой странице, и с произведения (номер страницы)*(количество групп на странице) на последующих.

nDoc - номер документа в группе по порядку, от нуля до значения "GroupDocCount(...)-1" включительно.

attr - имя группировочного атрибута.

gMode - тип группировки, "1" - плоская или глубокая, если атрибут иерархический, "2" - широкая, имеет смысл только для иерархического атрибута.

int ICluster::DocPriority(int nGroup, int nDoc, const char *attr, int gMode)

Yx::DocPriority(nGroup, nDoc, attr, gMode)

Возвращает приоритет релевантности документа, как описано для функции GroupPriority.

long ICluster::DocRelevance(int nGroup, int nDoc, const char *attr, int gMode)

Yx::DocRelevance(nGroup, nDoc, attr, gMode)

Возвращает релевантность документа в виде положительного целого числа.

const char *IReqEnv::HighlightedDocUrl(int nGroup, int nDoc, const char *attr, int gMode)

Yx::HighlightedDocUrl(nGroup, nDoc, attr, gMode)

Возвращает веб-адрес страницы с подсвеченным документом. Этот адрес всегда начинается со строки, возвращаемой функцией SearchUrl.

int ICluster::DocPropertyCount(int nGroup, int nDoc, const char *attr, int gMode, const char* property)

Yx::DocPropertyCount(nGroup, nDoc, attr, gMode, property)

Возвращает число различных значений свойства документа, указанного в аргументе property.

property - название свойства в виде строки.

В качестве свойства можно передавать следующие значения.

• Название группировочного атрибута, которое возвращается функцией Attr(attrnum).

  В этом случае функция вернет "0", если у данного документа указанный группировочный атрибут отсутствует, "1", если атрибут имеется, или значение, большее 1, если имеется несколько значений иерархического атрибута.

• Один из аргументов директивы DocProperty конфигурации индексатора.

  В этом случае функция вернет "0", если у данного документа указанный поисковый атрибут отсутствует, и "1", если атрибут имеется.

• Одно из следующих значений.

  "_Url" - URL документа.

  "_ModTime" - время в секундах, прошедшее с 00:00:00 1 января 1970 года до момента последнего изменения файла с документом.

  "_ModTimeStr" - то же, что и "_ModTime", но в виде строки формата 18 Aug 2000, 08:52.

  "_Size" - размер файла с документом в байтах.

  "_Charset" - кодировка документа.

  "_MimeType" - медиа-тип документа.

  "_Title" - заголовок документа.

  "_HeadLine" - краткое содержание документа или первые 200 символов текста.

  "_Passage" - отрывок текста документа, содержащий искомые слова.

  Функция вернет "1", кроме свойства "_Passage", значений которого может быть несколько, но не больше, чем указано в параметре поисковой формы t.

const char *ICluster::DocProperty(int nGroup, int nDoc, const char *attr, int gMode, const char* property, unsigned index)

Yx::DocProperty(nGroup, nDoc, attr, gMode, property, index)

Возвращает значение указанного свойства документа.

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

index - номер значения свойства от нуля до значения, возвращаемого функцией DocPropertyCount.

Для свойств "_Title", "_HeadLine" и "_Passage" функция возвращает строку, размеченную специальным символом BEL (символ с кодом "7") следующим образом.

• "BEL{" и "BEL}" окружают слова с приоритетом "совпадение фразы".
• "BEL[" и "BEL]" окружают слова с приоритетом "строгое соответствие".
• "BEL(" и "BEL)" окружают слова с приоритетом "нестрогое соответствие".

Размеченные таким образом строки могут быть преобразованы с помощью функции ConvertArchiveText.

const char* IReqEnv::ConvertArchiveText(const char* rawtext, unsigned maxLen, int mode, const char *Open1, const char *Open2, const char *Open3, const char *Close1, const char *Close2, const char *Close3)

Yx::ConvertArchiveText(rawtext, maxLen, mode, Open1, Open2, Open3, Close1, Close2, Close3)

Функция преобразует заголовок, аннотацию и фрагменты текста документа, возвращаемые функцией DocProperty.

Возвращает текст, в котором специальные символы заменены на указанные теги и который обрезан до нужной длины, по возможности, по словам.

rawtext - размеченный текст, выданный функцией DocProperty, который надо обработать.

maxLen - длина, до которой надо укоротить rawtext, если этот параметр равен "0", то текст не укорачивается.

mode - вид обработки. "0" - запрещенные в HTML символы заменяются на соответствующие последовательности, а специальная разметка слов - на указанные теги. "1" - запрещенные в HTML символы заменяются на соответсвующие последовательности, а специальная разметка слов выбрасывается. "2" - запрещенные в HTML символы не заменяются, специальная разметка слов выбрасывается.

Open1, Close1 - Открывающий и закрывающий теги для слов, найденных с нестрогим соответствием.

Open2, Close2 - Открывающий и закрывающий теги для слов, найденных со строгим соответствием.

Open3, Close3 - Открывающий и закрывающий теги для слов, найденных с совпадением фразы.

Yx::HeaderOut(header, value)

Функция печатает HTTP-заголовок header со значением "value".

header - HTTP-заголовок.

value - значение HTTP-заголовка.

Yx::ContentType(value)

value - значение заголовка.

Функция печатает HTTP-заголовок Content-Type со значением "value".

Yx::SetLastModified()

Функция печатает HTTP-заголовок Last-Modified со временем изменения индексных файлов в качестве значения заголовка.