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 é 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. Esquema de exemplo 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, com relação a um banco de dados de filmes, é provável que um usuário faça uma consulta como "Mostre todos os filmes estrelados por Robert Redford". Portanto, seu esquema precisa aceitar resultados de consultas com base 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 executadas, 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 um banco de dados de filmes, os usuários podem estar interessados apenas em um determinado gênero de filmes. Os usuários definiriam qual gênero eles querem que as pesquisas retornem, possivelmente como parte do perfil de usuário. Em seguida, quando um usuário começa a digitar uma consulta de filmes, somente os 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 é "movie". Outro objeto pode ser "person" para representar o elenco e a equipe envolvidos 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. Um exemplo de esquema mostrando 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 "movie" e "person".

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

Ao definir um objeto de esquema, forneça um name para o objeto que precisa ser único entre todos os outros objetos no esquema. Normalmente, usa-se um valor name que descreva o objeto, como movie para um objeto 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 a Definição de objetos.

Observação: o 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 relacionadas a ele, os operationIds dessas LROs serão retornados quando você solicitar o esquema registrado. Não é possível definir o 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 ser composto por freshnessOptions e displayOptions. As freshnessOptions são usadas para ajustar a classificação da pesquisa com base na atualização de um item. As displayOptions são usadas para definir se propriedades e rótulos específicos são exibidos nos resultados da pesquisa de um objeto.

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

Na seção propertyDefinitions, 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 propriedade que diferem apenas por caso, como movieTitle e movietitle, são considerados iguais e vão gerar 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. No entanto, é possível usar o mesmo nome 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 aceitar 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 um número inteiro para o campo duração, em que se espera um texto para processar abreviações de unidades, o sistema rejeitará a solicitação inteira.

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 a serem retornados nos resultados da pesquisa pela API Query. Todas as propriedades de filme de exemplo podem ser devolvidas. É 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, na nossa amostra de esquema, podemos transformar genre, actorName, userRating e mpaaRating em atributos para permitir que sejam usadas no refinamento interativo dos resultados da pesquisa.
• isWildcardSearchable indica que os usuários podem realizar pesquisas com curinga para essa propriedade. Essa opção está disponível apenas em propriedades de texto. A forma como a pesquisa com curinga funciona no campo de texto depende do valor definido no campo exactMatchWithOperator. Se exactMatchWithOperator for definido como true, o valor de texto será tokenizado como um valor atômico, e uma pesquisa com caractere curinga será realizada. Por exemplo, se o valor de texto for science-fiction, uma consulta com caractere curinga science-* vai corresponder a ele. Se exactMatchWithOperator estiver definido como false, o valor de texto será tokenizado e uma pesquisa com caractere curinga será realizada em cada token. Por exemplo, se o valor de texto for "ficção científica", as consultas com curinga sci* ou fi* vão corresponder ao item, mas science-* não vai.

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	true				verdadeiro
releaseDate	verdadeiro		verdadeiro
genre	verdadeiro	verdadeiro		verdadeiro
duration	verdadeiro
actorName	verdadeiro	verdadeiro		verdadeiro	verdadeiro
userRating	verdadeiro		verdadeiro
mpaaRating	verdadeiro			verdadeiro

As propriedades 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ários 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 de uma propriedade, use um enum (enumPropertyOptions) em vez de um tipo de string. Se o tipo enumerado mudar em versões futuras, use introspecções para verificar o esquema e atualizá-lo quando necessário.

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

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 no 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 de tipo retrievalImportance e operatorOptions.

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

Aviso: a menos que você tenha certeza absoluta de que uma propriedade precisa ser classificada em uma posição mais alta do que 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 atribuir a ele a importância HIGHEST. No entanto, se uma propriedade contiver números de peça que são referências a outras peças, mas não forem a peça em si, considere marcar a propriedade como de BAIXA importância. Se você não tiver certeza sobre a importância da propriedade, use DEFAULT. Se você tiver certeza de que o texto não será usado para recuperação, use NONE. Para mais informações, consulte Importância.

Cada operatorOptions tem um operatorName, como title para um 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 filme tenha as propriedades plotSummary e plotSynopsis e cada uma delas tenha um operatorName de plot. Enquanto as duas propriedades forem de texto (textPropertyOptions), uma única consulta usando o operador de pesquisa plot vai recuperar ambas.

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, o 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, a pesquisa de um gênero ou a seleção da faceta "Science" ou "Fiction" também retornaria resultados para "Science-Fiction", já que o texto é tokenizado e os tokens "Science" e "Fiction" existem em "Science-Fiction". Quando exactMatchWithOperator é true, o texto é tratado como um único token. Portanto, "científica" e "ficção" não corresponderão a "ficção científica".

(Opcional) Adicionar a seção displayOptions

Há uma seção displayOptions opcional no final de todas as seções propertyDefinition. Esta 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 exibição usando ObjectDisplayOptions, esse rótulo será exibido na frente da propriedade. Se a propriedade estiver configurada para exibição e displayLabel não estiver definida, 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"
  }
},

Confira a seguir os valores de displayLabel para todas as propriedades do objeto movie no exemplo 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 suggestionFilteringOperators[] opcional no final de qualquer seção propertyDefinition. Use esta seção 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 do usuário. Em seguida, 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ão. Se você definir mais de um filtro, apenas o primeiro 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 são herdadas pela propriedade porque ela é definida como um tipo de dados date usando datePropertyOptions para defini-la. 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.

Por fim, observe que 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 do 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 da 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
• Alterar 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, é necessário reindexar os dados, o que causa um atraso no uso do preenchimento automático para essa 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.
• Configuração exactMatchWithOperator.
• Configuração 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. Você não conseguirá fazer essas alterações por meio de uma simples solicitação UpdateSchema, mesmo se 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.

Siga as etapas abaixo para alterar 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. Estrutura de um esquema para a interpretação ideal de consultas.

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

5. Crie um conector.