Создать и зарегистрировать схему

Схема Google Cloud Search — это структура JSON, определяющая объекты, свойства и параметры для индексирования и запроса данных. Ваш коннектор контента использует зарегистрированную схему для структурирования и индексирования данных репозитория.

Схема создается путем предоставления объекта JSON-схемы в API. Перед индексированием данных необходимо зарегистрировать схему для каждого репозитория.

Примечание: Схема не требуется для неструктурированных данных, таких как базовые системы обмена файлами без предопределенных типов файлов. Вы также можете использовать SDK для создания объектов схемы.

В этом документе рассматриваются основы создания схемы. Для оптимизации поиска см. раздел «Улучшение качества поиска» .

Создайте схему

Выполните следующие шаги, чтобы создать схему Cloud Search:

1. Определите ожидаемое поведение пользователей.
2. Инициализация источника данных
3. Определите ваши объекты
4. Определите свойства объекта
5. Зарегистрируйте свою схему
6. Проиндексируйте свои данные
7. Проверьте свою схему
8. Настройте свою схему

Примечание: В этом документе используется гипотетическая схема базы данных фильмов. Полный пример см. в файле schema.json .

Определите ожидаемое поведение пользователей.

Предвидение того, как пользователи осуществляют поиск, помогает определить стратегию построения схемы. Например, в базе данных фильмов пользователи могут искать «фильмы с Робертом Редфордом в главной роли». Ваша схема должна поддерживать запросы на фильмы с конкретным актером.

Чтобы привести вашу схему в соответствие с поведением пользователей:

1. Оценивайте разнообразные запросы от разных пользователей.
2. Определите логические наборы данных или объекты , например, «фильм».
3. Укажите свойства (атрибуты), такие как название или дата выпуска.
4. Определите допустимые значения для таких свойств, как «Индиана Джонс и искатели утраченного ковчега».
5. Определите потребности в сортировке и ранжировании, например, в хронологическом порядке или по рейтингу аудитории.
6. Для улучшения подсказок автозаполнения необходимо учитывать такие контекстные свойства, как должность.
7. Перечислите эти объекты, свойства и примеры значений. Используйте этот список для определения параметров оператора .

Инициализируйте источник данных.

Источник данных представляет собой проиндексированные данные репозитория, хранящиеся в Google Cloud. См. раздел «Управление сторонними источниками данных» . Когда пользователь щелкает по результату, Cloud Search перенаправляет его к элементу, используя URL-адрес из запроса на индексацию.

Определите ваши объекты

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

Рисунок 1. Пример схемы с двумя объектами и одним подобъектом.

Схема представляет собой список определений объектов в теге objectDefinitions .

{
  "objectDefinitions": [
    { "name": "movie" },
    { "name": "person" }
  ]
}

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

Примечание: Вы можете игнорировать operationIds возвращаемые при запросе зарегистрированной схемы; они относятся к ожидающим операциям.

Определите свойства объекта

Определите свойства, такие как заголовок и дата выпуска, в разделе propertyDefinitions . Используйте options freshnessOptions (рейтинг) и displayOptions (метки пользовательского интерфейса).

{
  "objectDefinitions": [{
    "name": "movie",
    "propertyDefinitions": [
      {
        "name": "movieTitle",
        "isReturnable": true,
        "textPropertyOptions": {
          "retrievalImportance": { "importance": "HIGHEST" },
          "operatorOptions": { "operatorName": "title" }
        },
        "displayOptions": { "displayLabel": "Title" }
      },
      {
        "name": "releaseDate",
        "isReturnable": true,
        "isSortable": true,
        "datePropertyOptions": {
          "operatorOptions": {
            "operatorName": "released",
            "lessThanOperatorName": "releasedbefore",
            "greaterThanOperatorName": "releasedafter"
          }
        }
      }
    ]
  }]
}

Примечание: имена свойств внутри объекта должны быть уникальными независимо от регистра.

В состав PropertyDefinition входят:

• Строка name .
• Параметры, не зависящие от типа (например, isReturnable ).
• Тип и параметры, специфичные для данного типа (например, textPropertyOptions ).
• operatorOptions для поисковых операторов.
• displayOptions для меток пользовательского интерфейса.

Вы можете повторно использовать имена свойств в разных объектах. Например, movieTitle может встречаться как в фильмографии объекта movie , так и в фильмографии объекта person .

Примечание: Cloud Search отбрасывает незарегистрированные поля во время индексирования и отклоняет запросы с некорректными типами данных.

Добавить параметры, не зависящие от типа

В PropertyDefinition есть логические параметры для настройки функциональности поиска по объекту недвижимости, независимо от его типа. По умолчанию эти параметры имеют значение false и должны быть установлены в true для использования.

• isReturnable : Установите значение true , если данные свойства должны возвращаться в результатах поиска при использовании Query API. Невозвращаемые свойства можно использовать для поиска или ранжирования без отображения в результатах.
• isRepeatable : Установите true если свойство может принимать несколько значений. Например, у фильма одна дата выхода, но несколько актеров.
• isSortable : Установите значение true , если свойство можно использовать для сортировки. Не может быть true если isRepeatable равно true или если свойство находится внутри повторяющегося подобъекта.
• isFacetable : Установите значение true если свойство может использоваться для генерации фасетов (атрибутов, используемых для уточнения результатов поиска).
  • Для корректной работы требуется, чтобы isReturnable было true .
  • Поддерживается только для свойств типа перечисление (enum), логическое значение (boolean) и текстовое значение (text).
• isWildcardSearchable : Установите значение true , чтобы разрешить пользователям выполнять поиск с использованием подстановочных знаков для этого свойства. Эта опция доступна только для текстовых свойств, и ее поведение зависит от параметра exactMatchWithOperator :
  • Если exactMatchWithOperator равно true : текстовое значение рассматривается как единый токен. Запрос типа science-* соответствует значению science-fiction .
  • Если exactMatchWithOperator равно false : текстовое значение токенизируется. Запрос типа sci* или fi* соответствует science-fiction , но science-* нет.

Определить тип

Задайте тип данных, определив соответствующий объект параметров свойства (например, textPropertyOptions ). Используйте перечисления ( enumPropertyOptions ), если известны все возможные значения. Свойство может иметь только один тип данных.

Определить параметры оператора

operatorOptions описывает, как свойство функционирует в качестве оператора поиска.

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

Для каждого operatorOptions требуется operatorName (например, title ). Это параметр, который пользователи вводят в запросы (например, title:titanic ). Используйте интуитивно понятные имена и предоставляйте к ним доступ пользователям.

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

Сортируемые свойства могут включать lessThanOperatorName и greaterThanOperatorName для запросов сравнения. Текстовые свойства могут использовать exactMatchWithOperator для обработки всего значения как единого токена.

Добавить параметры отображения

В необязательном разделе displayOptions содержится параметр displayLabel . Это удобная для пользователя метка, отображаемая в результатах поиска.

Добавить операторы фильтрации подсказок

Используйте suggestionFilteringOperators[] , чтобы определить свойство, которое фильтрует подсказки автозаполнения (например, фильтрует подсказки фильмов по предпочтительному жанру пользователя). Вы можете определить только один фильтр подсказок.

Зарегистрируйте свою схему

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

PUT https://cloudsearch.googleapis.com/v1/indexing/{name=datasources/*}/schema

Используйте validateOnly: true чтобы протестировать вашу схему без ее регистрации.

Проиндексируйте свои данные

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

Пример запроса на индексирование:

{
  "name": "datasource/<data_source_id>/items/titanic",
  "metadata": {
    "title": "Titanic",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [{
        "name": "movieTitle",
        "textValues": { "values": ["Titanic"] }
      }]
    }
  },
  "itemType": "CONTENT_ITEM"
}

Примечание: objectType должен совпадать с именем объекта схемы. Имена свойств в запросе должны соответствовать регистру символов схемы.

Проверьте свою схему

Перед запуском в продакшен проведите тестирование на небольшом репозитории. Создайте список контроля доступа (ACL), который ограничит доступ к результатам только для тестового пользователя.

• Общий запрос : выполните поиск по строке (например, "titanic"), чтобы увидеть все соответствующие элементы.
• Запрос с использованием оператора : Используйте оператор (например, actor:Zane ), чтобы ограничить количество результатов.

Настройте свою схему

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

Переиндексация после изменения схемы

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

• Названия операторов.
• Числовые пределы.
• Упорядоченный рейтинг.
• Варианты отображения свежести или внешнего вида.

Необходимо выполнить переиндексацию для:

• Добавление или удаление свойств или объектов.
• Изменить значения isReturnable , isFacetable или isSortable на true .
• isSuggestable отметить объект недвижимости.

Запрещенные изменения свойств

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

• Тип или название данных объекта недвижимости.
• Настройки exactMatchWithOperator или retrievalImportance .

Внесите сложные изменения в схему.

Чтобы внести недопустимые изменения, перенесите свойства из старого определения в новое:

1. Добавьте в схему новое свойство с другим именем.
2. Зарегистрируйте схему, включив в нее как новые, так и старые свойства.
3. Заполните индекс, используя только новое свойство.
4. Удалите старое свойство из схемы.
5. Обновите код запроса, чтобы использовать новое имя свойства.

Облачный поиск хранит удаленные элементы в течение 30 дней, чтобы предотвратить проблемы с их повторным использованием.

Ограничения по размеру

• Максимум 10 объектов верхнего уровня.
• Максимальная глубина — 10 уровней.
• Максимальное количество полей на объект — 1000 (включая вложенные поля).

Следующие шаги

1. Создайте интерфейс поиска .
2. Улучшить качество поиска .
3. Создайте схему для оптимальной интерпретации запросов .
4. Дайте определение синонимам .