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 os 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.

Observação: não é necessário um esquema para dados não estruturados, como sistemas básicos de compartilhamento de arquivos sem tipos de arquivos predeterminados. Também é possível usar o SDK para criar objetos de esquema.

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.

crie um esquema

Siga estas etapas para criar seu esquema do Cloud Search:

1. Identificar o comportamento esperado do usuário
2. Inicializar uma fonte de dados
3. Definir os objetos
4. Definir propriedades de objetos
5. Registrar o esquema
6. Indexar seus dados
7. Testar o esquema
8. Ajustar o esquema

Observação: este documento usa um esquema hipotético de banco de dados de filmes. Consulte schema.json para ver o exemplo completo.

Identificar o comportamento esperado do usuário

Prever como os usuários pesquisam ajuda a definir sua estratégia de esquema. Em 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:

1. Avalie consultas diversas de usuários diferentes.
2. Identifique conjuntos de dados lógicos, ou objetos, como um "filme".
3. Identifique propriedades (atributos) como título ou data de lançamento.
4. Identifique valores válidos para propriedades, como "Os Caçadores da Arca Perdida".
5. Determine as necessidades de ordenação e classificação, como ordem cronológica ou classificações do público.
6. Identifique propriedades de contexto, como função de trabalho, para melhorar as sugestões de preenchimento automático.
7. 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 os dados de um repositório indexado 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.

Figura 1. Um exemplo de esquema 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.

Observação: é possível ignorar operationIds retornado ao solicitar um esquema registrado. Eles se referem a operações pendentes.

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

Observação: os nomes de propriedades em um objeto precisam ser exclusivos, independentemente do uso de maiúsculas e minúsculas.

Uma PropertyDefinition inclui:

• Uma string name.
• Opções independentes de tipo (por exemplo, isReturnable).
• Um tipo e opções específicas do 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.

Observação: o Cloud Search descarta campos não registrados durante a indexação e rejeita solicitações com tipos de dados incorretos.

Adicionar opções independentes de tipo

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

• isReturnable: definido como true se os dados da propriedade precisarem ser retornados nos resultados da pesquisa usando a API Query. É possível usar propriedades não retornáveis para pesquisar ou classificar sem que elas apareçam 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: definido como true se a propriedade puder ser usada para gerar refinamentos (atributos usados para refinar os resultados da pesquisa).
  • Exige que isReturnable seja true.
  • Disponível apenas para propriedades de enumeração, booleanas e de texto.
• isWildcardSearchable: defina como true para permitir que os usuários façam pesquisas com caracteres 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 é 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 enums (enumPropertyOptions) se você souber todos os valores possíveis. Uma propriedade pode ter apenas um tipo de dados.

Definir opções do operador

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

Aviso: defina retrievalImportance como DEFAULT, a menos que você tenha certeza de que uma propriedade exige uma classificação mais alta. Não é possível mudar essa configuração depois.

Todo 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 mostre-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 todo o valor como um único token.

Adicionar opções de exibição

A seção displayOptions opcional contém um displayLabel. É um rótulo fácil de usar que aparece 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. Envie uma solicitação UpdateSchema:

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

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

Indexar os dados

Depois do registro, preencha a fonte de dados usando chamadas de indexação, geralmente 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"
}

Observação: objectType precisa corresponder ao nome do objeto do esquema. Os nomes de propriedades na solicitação precisam corresponder ao caso do esquema.

Testar o esquema.

Teste com um repositório pequeno 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 de operador: use um operador (por exemplo, actor:Zane) para limitar os resultados.

Ajustar o esquema

Monitore o feedback dos usuários e ajuste seu esquema. Você pode indexar novos campos ou renomear operadores para que sejam mais intuitivos.

Indexar novamente após uma mudança de esquema

Não é necessário reindexar para que as 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.
• Mudando isReturnable, isFacetable ou isSortable para true.
• Marcar uma propriedade isSuggestable.

Alterações de propriedade não permitidas

Não são permitidas mudanças que corrompam o índice ou causem resultados inconsistentes, incluindo:

• Tipo de dados ou nome da propriedade.
• Configurações de 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:

1. Adicione uma nova propriedade com um nome diferente ao esquema.
2. Registre o esquema com as propriedades novas e antigas.
3. Faça o preenchimento do índice usando apenas a nova propriedade.
4. Exclua a propriedade antiga do esquema.
5. Atualize o código da 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.
• No máximo 1.000 campos por objeto (incluindo campos aninhados).

Próximas etapas

1. Crie uma interface de pesquisa.
2. Melhorar a qualidade da pesquisa.
3. Estrutura de um esquema para a interpretação ideal de consultas.
4. Definir sinônimos.