Criar e registrar um esquema

Um esquema do Google Cloud Search é uma estrutura JSON que define os objetos, as propriedades e as opções a serem usados na indexação e na consulta de dados. O conector de conteúdo lê os dados do repositório e, com base no esquema registrado, estrutura e indexa os dados.

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

Observação :não será necessário criar um esquema se o repositório de dados tiver apenas dados não estruturados. Por exemplo, se você tiver um sistema básico de compartilhamento de arquivos sem estruturas e de tipos de arquivos predeterminados, geralmente não precisará de um esquema. Também é possível criar um objeto de esquema usando o SDK, em vez de fornecer um objeto JSON à API.

Este documento aborda os conceitos básicos sobre criação de esquemas. Para mais informações sobre como ajustar um esquema para melhorar a experiência de pesquisa, consulte Melhorar a qualidade da pesquisa.

Criar um esquema

Veja a seguir a lista de etapas para criar um esquema do Cloud Search:

1. Identificar o comportamento esperado do usuário
2. Inicializar uma fonte de dados
3. Criar um esquema
4. Exemplo de esquema completo
5. Registrar o esquema
6. Indexar seus dados
7. Testar o esquema
8. Ajustar o esquema

Observação: neste documento, são usados snippets de um esquema para um banco de dados de filmes hipotéticos. Para ter acesso ao esquema completo, consulte schema.json

Identificar o comportamento esperado do usuário

Prever os tipos de consultas que os usuários farão ajudará você a determinar a direção da sua estratégia para criar o esquema.

Por exemplo, ao emitir consultas em um banco de dados de filmes, é possível prever que o usuário fará uma consulta como "Mostre todos os filmes estrelados por Robert Redford". Portanto, seu esquema precisa ser compatível com resultados de consultas baseados em "todos os filmes com um ator específico".

Para definir o esquema de modo que ele reflita os padrões comportamentais dos usuários, realize as seguintes tarefas:

1. Avalie um conjunto diversificado de consultas desejadas de usuários diferentes.
2. Identifique os objetos que talvez sejam usados nas consultas. Objetos são conjuntos lógicos de dados relacionados, como um filme em um banco de dados de filmes.
3. Identifique as propriedades e os valores que compõem o objeto e talvez sejam usados nas consultas. Propriedades são os atributos indexáveis do objeto e podem incluir valores primitivos ou outros objetos. Por exemplo, um objeto filme pode ter propriedades como o título do filme e a data de lançamento como valores primitivos. O objeto filme também pode conter outros objetos, como membros do elenco, que têm as próprias propriedades, como nome ou papel.
4. Identifique exemplos de valores válidos de propriedades. Valores são os dados reais indexados de uma propriedade. Por exemplo, o título de um filme no banco de dados pode ser "Os Caçadores da Arca Perdida".
5. Determine as opções de ordenação e classificação que os usuários querem. Por exemplo, ao consultar filmes, talvez os usuários queiram classificá-los por ordem cronológica e nota de avaliação do público, sem a necessidade de listá-los em ordem alfabética do título.
6. (Opcional) Considere se uma das suas propriedades representa um contexto mais específico em que as pesquisas podem ser realizadas, como a função ou o departamento dos usuários, para que as sugestões de preenchimento automático possam ser fornecidas com base no contexto. Por exemplo, para pessoas que pesquisam em um banco de dados de filmes, os usuários podem estar interessados apenas em um determinado gênero de filmes. Os usuários definiriam o gênero que querem que as pesquisas retornem, possivelmente como parte do perfil de usuário. Então, quando um usuário começa a digitar uma consulta de filmes, somente filmes do gênero preferido, como "filmes de ação", são sugeridos como parte das sugestões de preenchimento automático.
7. Faça uma lista desses objetos, propriedades e valores de exemplo que podem ser usados nas pesquisas. Para mais detalhes sobre como essa lista é usada, consulte a seção Definir opções do operador.

Inicializar uma origem de dados

Uma fonte de dados representa os dados de um repositório que foi indexado e armazenado no Google Cloud. Para instruções sobre como inicializar uma fonte de dados, consulte Gerenciar fontes de dados de terceiros.

Os resultados das pesquisas de usuários são retornados da fonte de dados. Quando um usuário clica em um resultado de pesquisa, o Cloud Search o direciona para o item real usando o URL fornecido na solicitação de indexação.

Definir os objetos

A unidade fundamental de dados em um esquema é o objeto, também chamado de "objeto do esquema", que é uma estrutura lógica de dados. Em um banco de dados de filmes, uma estrutura lógica de dados é "filme". Outro objeto pode ser "pessoa" para representar o elenco e a equipe envolvida no filme.

Cada objeto em um esquema tem uma série de propriedades ou atributos que descrevem esse objeto, como o título e a duração de um filme ou o nome e a data de nascimento de uma pessoa. As propriedades de um objeto podem incluir valores primitivos ou outros objetos.

A Figura 1 mostra os objetos filme e pessoa e as propriedades associadas a eles.

Figura 1. Uma amostra de esquema com dois objetos e um subobjeto.

Um esquema do Cloud Search é, essencialmente, uma lista de instruções de definição de objetos definidas na tag objectDefinitions. O snippet de esquema a seguir mostra as instruções objectDefinitions dos objetos de esquema de filme e pessoa.

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

Ao definir um objeto de esquema, você fornece um name para o objeto que precisa ser exclusivo entre todos os outros no esquema. Normalmente, você usa um valor name que descreve o objeto, como movie para um objeto de filme. O serviço de esquema usa o campo name como um identificador de chave de objetos indexáveis. Para mais informações sobre o campo name, consulte Definição de objetos.

Observação :na verdade, um esquema do Cloud Search tem duas seções de nível superior: objectDefinitions e operationIds. Quando seu esquema estiver em uso e houver operações de longa duração (LROs, na sigla em inglês) pendentes para ele, as operationIds dessas LROs serão retornadas quando você solicitar o esquema registrado. Como não é possível definir operationIds, ignore essa parte do esquema.

Definir propriedades de objetos

Conforme especificado na referência de ObjectDefinition, o nome do objeto é seguido por um conjunto de options e uma lista de propertyDefinitions. O options pode consistir ainda mais em freshnessOptions e displayOptions. O freshnessOptions é usado para ajustar a classificação da pesquisa com base na atualização de um item. O displayOptions é usado para definir se propriedades e rótulos específicos são exibidos nos resultados da pesquisa de um objeto.

Observação: para detalhes sobre como ajustar freshnessOptions para melhorar a experiência de pesquisa, consulte Influenciar a atualização em Melhorar a qualidade da pesquisa.

A seção propertyDefinitions é onde você define as propriedades de um objeto, como o título do filme e a data de lançamento.

O snippet a seguir mostra o objeto movie com duas propriedades: movieTitle e releaseDate.

{
  "objectDefinitions": [
    {
      "name": "movie",
      "propertyDefinitions": [
        {
          "name": "movieTitle",
          "isReturnable": true,
          "isWildcardSearchable": 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"
            }
          },
          "displayOptions": {
            "displayLabel": "Release date"
          }
      ...
      ]
    }
  ]
}

Observação :quando definidos no mesmo objeto, os nomes de propriedades que diferem apenas no caso, como movieTitle e movietitle, são considerados iguais e causarão um erro.

A PropertyDefinition consiste nos seguintes itens:

• Uma string name.
• Uma lista de opções independentes de tipo, como isReturnable no snippet anterior.
• Um tipo e as opções específicas associadas, como textPropertyOptions e retrievalImportance no snippet anterior.
• Um operatorOptions que descreve como a propriedade é usada como um operador de pesquisa.
• Um ou mais displayOptions, como displayLabel no snippet anterior.

O name de uma propriedade precisa ser exclusivo no objeto que a contém, mas o mesmo nome pode ser usado em outros objetos e subobjetos. Na Figura 1, o título e a data de lançamento do filme foram definidos duas vezes: uma vez no objeto movie e novamente no subobjeto filmography do objeto person. Esse esquema reutiliza o campo movieTitle para oferecer suporte a dois tipos de comportamentos de pesquisa:

• Mostrar resultados de filmes quando os usuários pesquisam o título de um filme.
• Mostrar resultados de pessoas quando os usuários pesquisam o título de um filme em que um ator atuou.

Da mesma forma, o esquema reutiliza o campo releaseDate porque ele tem o mesmo significado para os dois campos movieTitle.

Ao desenvolver seu próprio esquema, pense em como seu repositório pode ter campos relacionados contendo dados que você queira declarar mais de uma vez no esquema.

Observação: se uma solicitação de indexação tentar indexar um item com um campo ou uma propriedade não registrada, como date em vez de releaseDate, o sistema vai descartar o campo. Se a solicitação de indexação fornecer um tipo de dado incorreto para uma propriedade, como fornecer um número inteiro para o campo duração (que precisa de texto para processar abreviações de unidades), o sistema rejeitará toda a solicitação.

Adicionar opções independentes de tipo

PropertyDefinition lista opções gerais de funcionalidade de pesquisa comuns a todas as propriedades, independentemente do tipo de dados.

• isReturnable: indica se a propriedade identifica os dados que precisam ser retornados nos resultados da pesquisa usando a API Query. Todas as propriedades de filme de exemplo são retornáveis. É possível usar propriedades não retornáveis para pesquisar ou classificar resultados sem que sejam retornados ao usuário.
• isRepeatable: indica se vários valores são permitidos para a propriedade. Por exemplo, um filme tem apenas uma data de lançamento, mas pode ter vários atores.
• isSortable: indica que a propriedade pode ser usada para classificação. Essa opção não pode ser verdadeira para propriedades que são repetíveis. Por exemplo, os resultados de filmes podem ser classificados por data de lançamento ou nota do público.
• isFacetable: indica que a propriedade pode ser usada para gerar atributos. Um atributo é usado para refinar os resultados da pesquisa, o usuário vê os resultados iniciais e depois adiciona critérios ou atributos para refinar ainda mais os resultados. Essa opção não pode ser verdadeira para propriedades com o tipo objeto e isReturnable precisa ser verdadeiro para definir essa opção. Por fim, essa opção é compatível apenas com propriedades booleanas, de enumeração e de texto. Por exemplo, no esquema de amostra, podemos transformar genre, actorName, userRating e mpaaRating em atributos para permitir que sejam usados no refinamento interativo dos resultados da pesquisa.
• isWildcardSearchable indica que os usuários podem realizar a pesquisa de caracteres curinga nessa propriedade. Essa opção está disponível apenas nas propriedades de texto. O funcionamento da pesquisa de caracteres curinga no campo de texto depende do valor definido no campo exactMatchWithOperator. Se exactMatchWithOperator for definido como true, o valor do texto será tokenizado como um valor atômico, e uma pesquisa de caracteres curinga será realizada nele. Por exemplo, se o valor do texto for science-fiction, uma consulta de caractere curinga science-* vai corresponder a ele. Se exactMatchWithOperator for definido como false, o valor do texto será tokenizado, e uma pesquisa de caracteres curinga será realizada em cada token. Por exemplo, se o valor do texto for "science-science", as consultas curinga sci* ou fi* corresponderão ao item, mas science-* não.

Esses parâmetros gerais de funcionalidade de pesquisa são todos valores booleanos. Todos eles têm um valor padrão de false e precisam ser definidos como true para serem usados.

A tabela a seguir mostra os parâmetros booleanos definidos como true para todas as propriedades do objeto movie:

Propriedade	isReturnable	isRepeatable	isSortable	isFacetable	isWildcardSearchable
movieTitle	verdadeiro				verdadeiro
releaseDate	verdadeiro		verdadeiro
genre	verdadeiro	verdadeiro		verdadeiro
duration	verdadeiro
actorName	verdadeiro	verdadeiro		verdadeiro	verdadeiro
userRating	verdadeiro		verdadeiro
mpaaRating	verdadeiro			verdadeiro

genre e actorName têm isRepeatable definido como true, porque um filme pode pertencer a mais de um gênero e normalmente tem mais de um ator. Uma propriedade não pode ser classificada se for repetível ou estiver contida em um subobjeto repetível.

Definir tipo

A seção de referência PropertyDefinition lista várias xxPropertyOptions, em que xx é um tipo específico, como boolean. Para definir o tipo de dados da propriedade, é necessário definir o objeto de tipo de dados apropriado. Definir um objeto de tipo de dados para uma propriedade estabelece o tipo de dados dessa propriedade. Por exemplo, definir textPropertyOptions para a propriedade movieTitle indica que o título do filme é do tipo texto. O snippet a seguir mostra a propriedade movieTitle com textPropertyOptions definindo o tipo de dados.

{
  "name": "movieTitle",
  "isReturnable": true,
  "isWildcardSearchable": true,
  "textPropertyOptions": {
    ...
  },
  ...
},

Observação :se você entender o conjunto completo de valores possíveis para uma propriedade, use um tipo enumerado (enumPropertyOptions) em vez de um tipo de string. Se a enumeração mudar em versões futuras, use introspecções para verificar o esquema e atualizar quando necessário.

Uma propriedade pode ter apenas um tipo de dados associado. Por exemplo, no esquema de filmes, releaseDate só pode ser uma data (por exemplo, 2016-01-13) ou uma string (por exemplo, January 13, 2016), mas não os dois.

Veja a seguir os objetos de tipo de dados usados para especificar os tipos de dados para as propriedades na amostra de esquema de filmes:

Propriedade	Objeto de tipo de dados
movieTitle	textPropertyOptions
releaseDate	datePropertyOptions
genre	enumPropertyOptions
duration	textPropertyOptions
actorName	textPropertyOptions
userRating	integerPropertyOptions
mpaaRating	textPropertyOptions

O tipo de dados escolhido para propriedade depende dos casos de uso esperados. No cenário imaginado do esquema de filmes, espera-se que os usuários queiram classificar os resultados cronologicamente. Portanto, releaseDate é um objeto de data. Se, por exemplo, houvesse um caso de uso esperado de comparação entre lançamentos de dezembro ao longo dos anos com lançamentos de janeiro, um formato de string seria útil.

Configurar opções específicas de tipo

A seção de referência PropertyDefinition contém links para as opções de cada tipo. A maioria das opções específicas de tipo é opcional, exceto a lista de possibleValues em enumPropertyOptions. Além disso, a opção orderedRanking permite classificar os valores em relação uns aos outros. O snippet a seguir mostra a propriedade movieTitle com textPropertyOptions definindo o tipo de dados e com a opção específica do tipo retrievalImportance.

{
  "name": "movieTitle",
  "isReturnable": true,
  "isWildcardSearchable": true,
  "textPropertyOptions": {
    "retrievalImportance": { "importance": "HIGHEST" },
    ...
  },
  ...
}

Veja a seguir outras opções específicas de tipo usadas na amostra de esquema:

Propriedade	Tipo	Opções específicas de tipo
movieTitle	textPropertyOptions	retrievalImportance
releaseDate	datePropertyOptions
genre	enumPropertyOptions
duration	textPropertyOptions
actorName	textPropertyOptions
userRating	integerPropertyOptions	orderedRanking, maximumValue
mpaaRating	textPropertyOptions

Definir opções do operador

Além das opções específicas de tipo, cada tipo tem um conjunto de operatorOptions opcionais. Essas opções descrevem como a propriedade é usada como um operador de pesquisa. O snippet a seguir mostra a propriedade movieTitle com textPropertyOptions definindo o tipo de dados e com as opções específicas do tipo retrievalImportance e operatorOptions.

{
  "name": "movieTitle",
  "isReturnable": true,
  "isWildcardSearchable": true,
  "textPropertyOptions": {
    "retrievalImportance": { "importance": "HIGHEST" },
    "operatorOptions": {
      "operatorName": "title"
    }
  },
  ...
}

Aviso :a menos que você tenha absoluta certeza de que uma propriedade precisa ter uma classificação mais alta do que as outras nos resultados da pesquisa, defina retrievalImportance como DEFAULT. Essa opção não pode ser alterada depois de definida. Por exemplo, se uma propriedade representa um título, é uma boa ideia dar a ela a importância HIGHEST. No entanto, se uma propriedade contém números de peça que são referências a outras partes, mas não são a parte em si, considere marcar a propriedade como importância BAIXA. Se você não tiver certeza sobre a importância da propriedade, use DEFAULT. Se você tiver certeza de que o texto não pode ser usado para recuperação, use NONE. Para mais informações, consulte Importância.

Cada operatorOptions tem um operatorName, como title para uma movieTitle. O nome do operador é o operador de pesquisa da propriedade. Um operador de pesquisa é o parâmetro real que você espera que os usuários usem ao restringir uma pesquisa. Por exemplo, para pesquisar filmes com base no título, o usuário digitaria title:movieName, em que movieName é o nome de um filme.

Os nomes de operador não precisam ser iguais ao nome da propriedade. Em vez disso, use nomes de operadores que reflitam as palavras mais comuns usadas pelos usuários na sua organização. Por exemplo, se os usuários preferirem o termo "name" em vez de "title" como título do filme, defina o nome do operador como "name".

Observação: é importante informar os nomes de operadores aos usuários, como opções na interface de pesquisa ou na documentação. Os usuários precisam saber quais operadores usar para refinar as consultas de pesquisa.

É possível usar o mesmo nome de operador em várias propriedades, contanto que todas elas sejam resolvidas para o mesmo tipo. Ao usar um nome de operador compartilhado durante uma consulta, todas as propriedades que usam esse nome de operador são recuperadas. Por exemplo, suponha que o objeto "Movie" tenha as propriedades plotSummary e plotSynopsis, e cada uma delas tenha um operatorName de plot. Contanto que as duas propriedades sejam de texto (textPropertyOptions), uma única consulta usando o operador de pesquisa plot vai recuperar as duas.

Além de operatorName, as propriedades classificáveis podem ter campos lessThanOperatorName e greaterThanOperatorName em operatorOptions. Os usuários podem usar essas opções para criar consultas baseadas em comparações com um valor enviado.

Por fim, textOperatorOptions tem um campo exactMatchWithOperator em operatorOptions. Se você definir exactMatchWithOperator como true, a string de consulta precisará corresponder ao valor inteiro da propriedade, e não apenas estar contida no texto. O valor do texto é tratado como um valor atômico nas pesquisas do operador e nas correspondências com atributos.

Por exemplo, pense em indexar objetos livro ou filme com propriedades de gênero. Os gêneros podem incluir "Science-Fiction", "Science" e "Fiction". Com exactMatchWithOperator definido como false ou omitido, pesquisar um gênero ou selecionar o atributo "Ciência" ou "Ficção" também retornaria resultados para "ficção científica", já que o texto é tokenizado, e os tokens de "ficção científica" e "ficção" existem em "ficção científica". Quando exactMatchWithOperator é true, o texto é tratado como um único token. Portanto, "Ciência" ou "Ficção" não correspondem a "Ficção científica".

(Opcional) Adicionar a seção displayOptions

Há uma seção displayOptions opcional no final de qualquer seção propertyDefinition. Essa seção contém uma string displayLabel. O displayLabel é um rótulo de texto fácil de usar e recomendado para a propriedade. Se a propriedade estiver configurada para ser exibida usando ObjectDisplayOptions, esse rótulo será exibido na frente da propriedade. Se a propriedade estiver configurada para exibição e displayLabel não estiver definido, apenas o valor da propriedade será exibido.

O snippet a seguir mostra a propriedade movieTitle com um displayLabel definido como "Title".

{
  "name": "movieTitle",
  "isReturnable": true,
  "isWildcardSearchable": true,
  "textPropertyOptions": {
    "retrievalImportance": { "importance": "HIGHEST" },
    "operatorOptions": {
       "operatorName": "title"
    }
},
  "displayOptions": {
    "displayLabel": "Title"
  }
},

Veja a seguir os valores displayLabel para todas as propriedades do objeto movie na amostra de esquema:

Propriedade	displayLabel
movieTitle	Title
releaseDate	Release date
genre	Genre
duration	Run length
actorName	Actor
userRating	Audience score
mpaaRating	MPAA rating

(Opcional) Adicionar seção suggestionFilteringOperators[]

Há uma seção opcional suggestionFilteringOperators[] no final de qualquer seção propertyDefinition. Use-a para definir uma propriedade usada para filtrar sugestões de preenchimento automático. Por exemplo, você pode definir o operador de genre para filtrar sugestões com base no gênero de filme preferido pelo usuário. Depois, quando o usuário digita a consulta de pesquisa, apenas os filmes que correspondem ao gênero preferido são exibidos como parte das sugestões de preenchimento automático.

Observação :embora esse campo seja uma matriz, só é possível definir um filtro de sugestões. Se você definir mais de um filtro, apenas o primeiro definido será reconhecido.

Registrar o esquema

Para que dados estruturados sejam retornados nas consultas do Cloud Search, é necessário registrar seu esquema com o serviço de esquema do Cloud Search. Para registrar um esquema, você precisa usar o código da fonte de dados conseguido durante a etapa Inicializar uma fonte de dados.

Use o código da fonte de dados para emitir uma solicitação UpdateSchema e registrar seu esquema.

Conforme detalhado na página de referência UpdateSchema, emita a seguinte solicitação HTTP para registrar seu esquema:

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

O corpo da solicitação precisa conter o seguinte:

{
  "validateOnly": // true or false,
  "schema": {
    // ... Your complete schema object ...
  }
}

Use a opção validateOnly para testar a validade do esquema sem registrá-lo.

Indexar os dados

Depois de registrar seu esquema, preencha a fonte de dados usando chamadas de indexação. Normalmente, a indexação é feita no conector de conteúdo.

Usando o esquema de filmes, uma solicitação de indexação à API REST para um único filme teria a seguinte aparência:

{
  "name": "datasource/<data_source_id>/items/titanic",
  "acl": {
    "readers": [
      {
        "gsuitePrincipal": {
          "gsuiteDomain": true
        }
      }
    ]
  },
  "metadata": {
    "title": "Titanic",
    "sourceRepositoryUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [
        {
          "name": "movieTitle",
          "textValues": {
            "values": [
              "Titanic"
            ]
          }
        },
        {
          "name": "releaseDate",
          "dateValues": {
            "values": [
              {
                "year": 1997,
                "month": 12,
                "day": 19
              }
            ]
          }
        },
        {
          "name": "actorName",
          "textValues": {
            "values": [
              "Leonardo DiCaprio",
              "Kate Winslet",
              "Billy Zane"
            ]
          }
        },
        {
          "name": "genre",
          "enumValues": {
            "values": [
              "Drama",
              "Action"
            ]
          }
        },
        {
          "name": "userRating",
          "integerValues": {
            "values": [
              8
            ]
          }
        },
        {
          "name": "mpaaRating",
          "textValues": {
            "values": [
              "PG-13"
            ]
          }
        },
        {
          "name": "duration",
          "textValues": {
            "values": [
              "3 h 14 min"
            ]
          }
        }
      ]
    }
  },
  "content": {
    "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.",
    "contentFormat": "TEXT"
  },
  "version": "01",
  "itemType": "CONTENT_ITEM"
}

Observe como o valor de movie no campo objectType corresponde ao nome de definição do objeto no esquema. Ao combinar esses dois valores, o Cloud Search sabe qual objeto de esquema usar durante a indexação.

Observe também como a indexação da propriedade de esquema releaseDate usa subpropriedades de year, month e day que herda porque é definida como um tipo de dados date usando datePropertyOptions para defini-lo. No entanto, como year, month e day não estão definidos no esquema, não é possível consultar uma dessas propriedades (por exemplo, year) individualmente.

Observe também como a propriedade repetível actorName é indexada usando uma lista de valores.

Observação :o nome da propriedade em uma solicitação de indexação precisa corresponder ao caso da propriedade no esquema. Caso contrário, uma parte da solicitação de indexação será descartada como propriedade não registrada.

Como identificar possíveis problemas de indexação

Os dois problemas mais comuns relacionados a esquemas e indexação são os seguintes:

• A solicitação de indexação contém um objeto de esquema ou nome de propriedade que não foi registrado com o serviço de esquema. Esse problema faz com que a propriedade ou objeto seja ignorado.

• A solicitação de indexação tem uma propriedade com um valor de tipo diferente do tipo registrado no esquema. Esse problema faz com que o Cloud Search retorne um erro no momento da indexação.

Testar o esquema com vários tipos de consulta

Antes de registrar seu esquema para um grande repositório de dados de produção, teste-o com um repositório de dados de teste menor. Isso ajudará você a fazer ajustes rapidamente no esquema e excluir os dados indexados, sem afetar um índice maior ou o índice em produção atual. Para o repositório de dados de teste, crie uma lista de controle de acesso (ACL, na sigla em inglês) que autorize apenas um usuário de teste para que outros usuários não vejam esses dados nos resultados da pesquisa.

Para criar uma interface de pesquisa para validar tais consultas, leia A interface de pesquisa.

Essa seção contém vários exemplos de consulta para você testar um esquema de filmes.

Testar com uma consulta genérica

Uma consulta genérica retorna todos os itens na fonte de dados que contêm uma string específica. Em uma interface de pesquisa, execute uma consulta genérica em uma fonte de dados de filmes digitando a palavra titanic e pressionando Return. Todos os filmes com a palavra "titanic" serão retornados nos resultados da pesquisa.

Testar com um operador

Adicionar um operador à consulta limita os resultados aos itens que correspondem ao valor do operador. Por exemplo, use o operador actor para encontrar todos os filmes estrelados por um ator específico. Usando uma interface de pesquisa, é possível executar essa consulta de operador simplesmente digitando um par operador=valor, como "actor:Zane", e pressionando Return. Todos os filmes com o ator chamado Zane serão retornados nos resultados da pesquisa.

Ajustar o esquema

Depois que o esquema e os dados estiverem em uso, continue a monitorar o que está dando certo ou não para os usuários. Ajuste seu esquema nas seguintes situações:

• Indexação de um campo que não havia sido indexado anteriormente. Por exemplo, os usuários talvez pesquisem repetidamente filmes com base no nome do diretor. Portanto, ajuste seu esquema para aceitar "directorname" como um operador.
• Alteração dos nomes de operadores de pesquisa como base no feedback de usuários. Os nomes dos operadores precisam ser fáceis de usar. Se os usuários frequentemente usam um nome de operador incorreto, pense em alterá-lo.

Observação: quando o esquema é atualizado ou excluído, o aplicativo de pesquisa também é atualizado. Por exemplo, se um operador de esquema for renomeado, ele também será renomeado na configuração do aplicativo de pesquisa. Se a atualização do esquema for incompatível com o aplicativo de pesquisa e não for possível atualizá-lo, a atualização do esquema falhará e um erro será enviado na resposta de atualização.

Como indexar novamente após a alteração do esquema

Alterar qualquer um dos valores a seguir no esquema não exigirá uma nova indexação dos dados. Basta enviar uma nova solicitação UpdateSchema e o índice continuará funcionando:

• Nomes de operador
• Valores inteiros mínimos e máximos
• Classificação ordenada de valores inteiro e de enumeração
• Opções de frequência
• Opções de exibição

No caso das alterações a seguir, os dados indexados anteriormente continuarão a funcionar de acordo com o esquema já registrado. No entanto, será necessário indexar novamente as entradas atuais para ver as alterações com base no esquema atualizado, se as seguintes alterações tiverem sido realizadas:

• Inclusão ou remoção de uma propriedade ou um objeto novo
• Mudança de isReturnable, isFacetable ou isSortable de false para true.

Defina isFacetable ou isSortable como true apenas se você tiver uma necessidade e um caso de uso claros.

Por fim, ao atualizar o esquema marcando uma propriedade isSuggestable, reindexe seus dados, o que causa um atraso no uso do preenchimento automático nessa propriedade.

Alterações de propriedade não permitidas

Algumas alterações de esquema não são permitidas, mesmo se você indexar novamente os dados. O motivo disso é que elas podem corromper o índice ou produzir resultados de pesquisa insatisfatórios ou inconsistentes. Dentre as alterações proibidas incluem-se mudanças nos:

• tipos de dados de propriedades;
• nomes de propriedades.
• exactMatchWithOperator.
• retrievalImportance.

No entanto, há uma maneira de contornar essa limitação.

Fazer uma alteração complexa no esquema

Para evitar alterações que geram resultados de pesquisa insatisfatórios ou corrompem o índice, o Cloud Search impede certos tipos de mudanças nas solicitações UpdateSchema após a indexação do repositório. Por exemplo, não é possível alterar o tipo de dados ou o nome de uma propriedade depois de definidos. Essas alterações não podem ser feitas por meio de uma simples solicitação UpdateSchema, mesmo se você indexar novamente os dados.

Em situações em que é necessário fazer uma alteração não permitida no seu esquema, costuma ser possível fazer uma série de alterações permitidas que terão o mesmo efeito. Em geral, isso envolve primeiro migrar as propriedades indexadas de uma definição de objeto mais antiga para uma mais recente e, depois, enviar uma solicitação de indexação que usa apenas a propriedade mais nova.

As etapas a seguir mostram como mudar o tipo de dados ou o nome de uma propriedade:

1. Adicione uma propriedade nova à definição de objeto no esquema. Use um nome diferente da propriedade que você quer alterar.
2. Emita a solicitação UpdateSchema com a definição nova. Lembre-se de enviar o esquema inteiro, incluindo a propriedade nova e a antiga, na solicitação.

3. Preencha o índice do repositório de dados. Para fazer isso, envie todas as solicitações de indexação usando a propriedade nova, mas não a propriedade antiga. Isso resultaria em uma contagem duplicada de consultas correspondentes.

   1. Durante o preenchimento da indexação, verifique a propriedade nova e defina como padrão a propriedade antiga para evitar um comportamento inconsistente.
   2. Após a conclusão do preenchimento, execute consultas de teste para verificar.

4. Exclua a propriedade antiga. Emita outra solicitação UpdateSchema sem o nome da propriedade antiga e interrompa o uso dele nas futuras solicitações de indexação.

5. Migre todos os usos da propriedade antiga para a propriedade nova. Por exemplo, se você alterar o nome da propriedade de "creator" para "author", atualize o código de consulta para usar "author" onde anteriormente ele fazia referência a "creator".

O Cloud Search mantém um registro de todas as propriedades ou objetos excluídos por 30 dias para impedir qualquer reutilização que cause resultados de indexação inesperados. Dentro desse período de 30 dias, é necessário migrar todos os usos da propriedade ou objeto excluído, além de omiti-los de futuras solicitações de indexação. Assim, se posteriormente você decidir restabelecer a propriedade ou o objeto, será possível fazê-lo de modo a manter a exatidão do índice.

Conhecer as limitações de tamanho

O Cloud Search impõe limites no tamanho de esquemas e objetos de dados estruturados. Esses limites são os seguintes:

• O número máximo de objetos de nível superior é de 10 objetos.
• A profundidade máxima de uma hierarquia de dados estruturados é de 10 níveis.
• O número total de campos em um objeto é limitado a 1.000, o que inclui o total de campos primitivos mais a soma do número de campos em cada objeto aninhado.

Próximas etapas

Estas são algumas das próximas etapas que podem ser seguidas:

1. Crie uma interface de pesquisa para testar o esquema.

2. Ajuste o esquema para melhorar a qualidade da pesquisa.

3. Estruture um esquema para a interpretação ideal de consultas.

4. Saiba como aproveitar o esquema _dictionaryEntry para definir sinônimos de termos comumente usados na sua empresa. Para usar o esquema _dictionaryEntry, consulte Definir sinônimos.

5. Crie um conector.