Criar e registrar um esquema

Um esquema do Google Cloud Search é uma estrutura JSON que define objetos, propriedades e opções para indexar e consultar dados. O conector de conteúdo usa o esquema registrado para estruturar e indexar dados do repositório.

Para criar um esquema, forneça um objeto de esquema JSON à API. É necessário registrar um esquema para cada repositório antes de indexar os dados.

Este documento aborda os conceitos básicos da criação de esquemas. Para otimizar a experiência de pesquisa, consulte Melhorar a qualidade da pesquisa.

Criar um esquema

Siga estas etapas para criar um esquema do Cloud Search:

Identificar o comportamento esperado do usuário
Inicializar uma fonte de dados
Definir os objetos
Definir propriedades de objetos
Registrar o esquema
Indexar os dados
Testar o esquema
Ajustar o esquema

Identificar o comportamento esperado do usuário

Prever como os usuários pesquisam ajuda a definir sua estratégia de esquema. Para um banco de dados de filmes, os usuários podem pesquisar "filmes estrelados por Robert Redford". Seu esquema precisa aceitar consultas de filmes com um ator específico.

Para alinhar seu esquema ao comportamento do usuário:

Avalie diversas consultas de diferentes usuários.
Identifique conjuntos de dados lógicos ou objetos, como um "filme".
Identifique propriedades (atributos) como título ou data de lançamento.
Identifique valores válidos para propriedades, como "Os Caçadores da Arca Perdida".
Determine as necessidades de classificação e ordenação, como ordem cronológica ou classificações de público.
Identifique propriedades de contexto, como função de trabalho, para melhorar as sugestões de preenchimento automático.
Liste esses objetos, propriedades e valores de exemplo. Use essa lista para definir opções de operador.

Inicializar uma origem de dados

Uma fonte de dados representa dados indexados do repositório armazenados no Google Cloud. Consulte Gerenciar fontes de dados de terceiros. Quando um usuário clica em um resultado, o Cloud Search o direciona para o item usando o URL da solicitação de indexação.

Definir os objetos

O objeto é a unidade fundamental de um esquema. Estruturas lógicas como "filme" ou "pessoa" são objetos. Cada objeto tem propriedades como título, duração ou nome.

Desenho das conexões do esquema entre entidades — **Figura 1.** Um esquema de exemplo com dois objetos e um subobjeto.

Um esquema é uma lista de definições de objetos na tag objectDefinitions.

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

Use nomes exclusivos para cada objeto, como movie. O serviço de esquema usa esses nomes como chaves. Consulte ObjectDefinition.

Definir propriedades de objetos

Defina propriedades, como título e data de lançamento, na seção propertyDefinitions. Use options para freshnessOptions (classificação) e displayOptions (rótulos da interface).

{
  "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"
          }
        }
      }
    ]
  }]
}

Uma PropertyDefinition inclui:

Uma string name.
Opções independentes de tipo (por exemplo, isReturnable).
Um tipo e opções específicas de tipo (por exemplo, textPropertyOptions).
operatorOptions para operadores de pesquisa.
displayOptions para rótulos da interface.

É possível reutilizar nomes de propriedades em diferentes objetos. Por exemplo, movieTitle pode aparecer em um objeto movie e na filmografia de um objeto person.

Adicionar opções independentes de tipo

PropertyDefinition inclui opções booleanas para configurar a funcionalidade de pesquisa de uma propriedade, independentemente do tipo. Essas opções são definidas como false por padrão e precisam ser definidas como true para serem usadas.

isReturnable: defina como true se os dados da propriedade precisarem ser retornados nos resultados da pesquisa usando a API Query. Propriedades não retornáveis podem ser usadas para pesquisar ou classificar sem aparecer nos resultados.
isRepeatable: defina como true se a propriedade puder ter vários valores. Por exemplo, um filme tem uma data de lançamento, mas vários atores.
isSortable: defina como true se a propriedade puder ser usada para classificação. Não pode ser true se isRepeatable for true ou se a propriedade estiver dentro de um subobjeto repetível.
isFacetable: defina como true se a propriedade puder ser usada para gerar facetas (atributos usados para refinar os resultados da pesquisa).
- Exige que isReturnable seja true.
- Compatível apenas com propriedades de enumeração, booleanas e de texto.
isWildcardSearchable: defina como true para permitir que os usuários realizem pesquisas curinga nessa propriedade. Essa opção só está disponível em propriedades de texto, e o comportamento dela depende da configuração exactMatchWithOperator:
- Se exactMatchWithOperator for true: o valor de texto será tratado como um único token. Uma consulta como science-* corresponde ao valor science-fiction.
- Se exactMatchWithOperator for false: o valor de texto será tokenizado. Uma consulta como sci* ou fi* corresponde a science-fiction, mas science-* não.

Definir tipo

Defina o tipo de dados definindo o objeto de opções de propriedade apropriado (por exemplo, textPropertyOptions). Use enumerações (enumPropertyOptions) se você souber todos os valores possíveis. Uma propriedade pode ter apenas um tipo de dados.

Definir opções do operador

operatorOptions descreve como uma propriedade funciona como um operador de pesquisa.

Cada operatorOptions precisa de um operatorName (por exemplo, title). Esse é o parâmetro que os usuários digitam nas consultas (por exemplo, title:titanic). Use nomes intuitivos e exponha-os aos usuários.

É possível compartilhar um operatorName entre propriedades do mesmo tipo. As consultas que usam esse nome recuperam resultados de todas as propriedades correspondentes.

As propriedades classificáveis podem incluir lessThanOperatorName e greaterThanOperatorName para consultas de comparação. As propriedades de texto podem usar exactMatchWithOperator para tratar o valor inteiro como um único token.

Adicionar opções de exibição

A seção displayOptions opcional contém um displayLabel. Esse é um rótulo fácil de usar mostrado nos resultados da pesquisa.

Adicionar operadores de filtragem de sugestões

Use suggestionFilteringOperators[] para definir uma propriedade que filtra sugestões de preenchimento automático (por exemplo, filtrar sugestões de filmes pelo gênero preferido de um usuário). Só é possível definir um filtro de sugestões.

Registrar o esquema

Registre seu esquema com o serviço de esquema usando o ID da fonte de dados. Emita uma UpdateSchema:

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

Use validateOnly: true para testar seu esquema sem registrá-lo.

Indexar os dados

Após o registro, preencha a fonte de dados usando Index chamadas, normalmente com um conector.

Exemplo de solicitação de indexação:

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

Testar o esquema

Teste com um pequeno repositório antes da produção. Crie uma ACL que limite os resultados a um usuário de teste.

Consulta genérica: pesquise uma string (por exemplo, "titanic") para ver todos os itens correspondentes.
Consulta do operador: use um operador (por exemplo, actor:Zane) para limitar os resultados.

Ajustar o esquema

Monitore o feedback do usuário e ajuste seu esquema. É possível indexar novos campos ou renomear operadores para serem mais intuitivos.

Reindexar após uma mudança de esquema

Não é necessário reindexar para mudanças em:

Nomes de operador
Limites numéricos
Classificação ordenada
Opções de atualização ou exibição

É necessário reindexar para:

Adicionar ou remover propriedades ou objetos
Mudar isReturnable, isFacetable ou isSortable para true
Marcar uma propriedade isSuggestable

Alterações de propriedade não permitidas

As mudanças que interrompem o índice ou causam resultados inconsistentes não são permitidas, incluindo:

Tipo de dados ou nome da propriedade
Configurações exactMatchWithOperator ou retrievalImportance

Fazer uma alteração complexa no esquema

Para fazer uma mudança não permitida, migre as propriedades de uma definição antiga para uma nova:

Adicione uma nova propriedade com um nome diferente ao esquema.
Registre o esquema com propriedades novas e antigas.
Preencha o índice usando apenas a nova propriedade.
Exclua a propriedade antiga do esquema.
Atualize o código de consulta para usar o novo nome da propriedade.

O Cloud Search registra itens excluídos por 30 dias para evitar problemas de reutilização.

Limitações de tamanho

Máximo de 10 objetos de nível superior
Profundidade máxima de 10 níveis
Máximo de 1.000 campos por objeto (incluindo campos aninhados)