Créer et enregistrer un schéma

Un schéma Google Cloud Search est une structure JSON qui définit les objets, les propriétés et les options à utiliser pour l'indexation et l'interrogation des données. Votre connecteur de contenu utilise le schéma enregistré pour structurer et indexer les données du dépôt.

Pour créer un schéma, fournissez un objet de schéma JSON à l'API. Vous devez enregistrer un schéma pour chaque dépôt avant d'indexer les données.

Ce document couvre les bases de la création de schémas. Pour optimiser l'expérience de recherche, consultez Améliorer la qualité de la recherche.

Créer un schéma

Pour créer un schéma Cloud Search, procédez comme suit :

1. Déterminer le comportement attendu des utilisateurs
2. Initialiser une source de données
3. Définir vos objets
4. Définir les propriétés des objets
5. Enregistrer votre schéma
6. Indexer vos données
7. Tester votre schéma
8. Ajuster votre schéma

Déterminer le comportement attendu des utilisateurs

Anticiper la façon dont les utilisateurs effectuent des recherches vous permet de définir votre stratégie de schéma. Pour une base de données de films, les utilisateurs peuvent rechercher "films avec Robert Redford". Votre schéma doit être compatible avec les requêtes de films avec un acteur spécifique.

Pour aligner votre schéma sur le comportement des utilisateurs :

1. Évaluez différentes requêtes de différents utilisateurs.
2. Identifiez les ensembles de données logiques, ou objets, tels qu'un "film."
3. Identifiez les propriétés (attributs) telles que le titre ou la date de sortie.
4. Identifiez les valeurs valides pour les propriétés, telles que "Les Aventuriers de l'arche perdue".
5. Déterminez les besoins en matière de tri et de classement, comme l'ordre chronologique ou les notes des spectateurs.
6. Identifiez les propriétés de contexte, telles que le rôle professionnel, pour améliorer les suggestions de saisie semi-automatique.
7. Répertoriez ces objets, propriétés et exemples de valeurs. Utilisez cette liste pour définir les options d'opérateur.

Initialiser votre source de données

Une source de données représente les données de dépôt indexées stockées dans Google Cloud. Consultez Gérer les sources de données tierces. Lorsqu'un utilisateur clique sur un résultat, Cloud Search le dirige vers l'élément à l'aide de l'URL de la requête d'indexation.

Définir vos objets

L'objet est l'unité fondamentale d'un schéma. Les structures logiques telles que "film" ou "personne" sont des objets. Chaque objet possède des propriétés telles que le titre, la durée ou le nom.

Un schéma est une liste de définitions d'objet dans la balise objectDefinitions.

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

Utilisez des noms uniques pour chaque objet, par exemple movie. Le service de schéma utilise ces noms comme clés. Consultez ObjectDefinition.

Définir les propriétés des objets

Définissez des propriétés, telles que le titre et la date de sortie, dans la section propertyDefinitions. Utilisez options pour freshnessOptions (classement) et displayOptions (libellés de l'interface utilisateur).

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

Une PropertyDefinition inclut les éléments suivants :

• Une chaîne name.
• Des options non spécifiques au type (par exemple, isReturnable).
• Un type et des options spécifiques au type (par exemple, textPropertyOptions).
• operatorOptions pour les opérateurs de recherche.
• displayOptions pour les libellés de l'interface utilisateur.

Vous pouvez réutiliser les noms de propriétés dans différents objets. Par exemple, movieTitle peut apparaître à la fois dans un objet movie et dans la filmographie d'un objet person.

Ajouter des options indépendantes du type

PropertyDefinition inclut des options booléennes permettant de configurer la fonctionnalité de recherche d'une propriété, quel que soit son type. Ces options sont définies sur false par défaut et doivent être définies sur true pour être utilisées.

• isReturnable: définissez cette option sur true si les données de la propriété doivent être renvoyées dans les résultats de recherche à l'aide de l'API Query. Les propriétés non renvoyables peuvent être utilisées pour la recherche ou le classement sans apparaître dans les résultats.
• isRepeatable : définissez cette option sur true si la propriété peut avoir plusieurs valeurs. Par exemple, un film a une date de sortie, mais plusieurs acteurs.
• isSortable : définissez cette option sur true si la propriété peut être utilisée pour le tri. Cette option ne peut pas être définie sur true si isRepeatable est défini sur true ou si la propriété se trouve dans un sous-objet reproductible.
• isFacetable: définissez cette option sur true si la propriété peut être utilisée pour générer des facettes (attributs utilisés pour affiner les résultats de recherche).
  • Cette option nécessite que isReturnable soit défini sur true.
  • Elle n'est compatible qu'avec les propriétés "Enum", "Boolean" et "Text".
• isWildcardSearchable: définissez cette option sur true pour permettre aux utilisateurs d'effectuer des recherches génériques sur cette propriété. Cette option n'est disponible que sur les propriétés de texte, et son comportement dépend du paramètre exactMatchWithOperator :
  • Si exactMatchWithOperator est défini sur true, la valeur de texte est traitée comme un jeton unique. Une requête telle que science-* correspond à la valeur science-fiction.
  • Si exactMatchWithOperator est défini sur false, la valeur de texte est tokenisée. Une requête telle que sci* ou fi* correspond à science-fiction, mais pas science-*.

Définir le type

Définissez le type de données en définissant l'objet d'options de propriété approprié (par exemple, textPropertyOptions). Utilisez des enums (enumPropertyOptions) si vous connaissez toutes les valeurs possibles. Une propriété ne peut avoir qu'un seul type de données.

Définir les options d'opérateur

operatorOptions décrit le fonctionnement d'une propriété en tant qu'opérateur de recherche.

Chaque operatorOptions nécessite un operatorName (par exemple, title). Il s'agit du paramètre que les utilisateurs saisissent dans les requêtes (par exemple, title:titanic). Utilisez des noms intuitifs et exposez-les aux utilisateurs.

Vous pouvez partager un operatorName entre les propriétés du même type. Les requêtes utilisant ce nom récupèrent les résultats de toutes les propriétés correspondantes.

Les propriétés triables peuvent inclure lessThanOperatorName et greaterThanOperatorName pour les requêtes de comparaison. Les propriétés de texte peuvent utiliser exactMatchWithOperator pour traiter l'intégralité de la valeur comme un jeton unique.

Ajouter des options d'affichage

La section facultative displayOptions contient un displayLabel. Il s'agit d'un libellé convivial affiché dans les résultats de recherche.

Ajouter des opérateurs de filtrage des suggestions

Utilisez suggestionFilteringOperators[] pour définir une propriété qui filtre les suggestions de saisie semi-automatique (par exemple, en filtrant les suggestions de films par genre préféré d'un utilisateur). Vous ne pouvez définir qu'un seul filtre de suggestions.

Enregistrer votre schéma

Enregistrez votre schéma auprès du service de schéma à l'aide de l'ID de votre source de données. Émettez une UpdateSchema UpdateSchema :

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

Utilisez validateOnly: true pour tester votre schéma sans l'enregistrer.

Indexer vos données

Après l'enregistrement, remplissez la source de données à l'aide d' appels d'index, généralement avec un connecteur.

Exemple de requête d'indexation :

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

Tester votre schéma

Effectuez des tests avec un petit dépôt avant la production. Créez une LCA qui limite les résultats à un utilisateur test.

• Requête générique : recherchez une chaîne (par exemple, "titanic") pour afficher tous les éléments correspondants.
• Requête d'opérateur : utilisez un opérateur (par exemple, actor:Zane) pour limiter les résultats.

Ajuster votre schéma

Surveillez les commentaires des utilisateurs et ajustez votre schéma. Vous pouvez indexer de nouveaux champs ou renommer des opérateurs pour les rendre plus intuitifs.

Réindexer après une modification du schéma

Vous n'avez pas besoin de réindexer pour les modifications apportées aux éléments suivants :

• Noms d'opérateurs
• Limites numériques
• Classement ordonné
• Options d'actualisation ou d'affichage

Vous devez réindexer pour les éléments suivants :

• Ajout ou suppression de propriétés ou d'objets
• Modification de isReturnable, isFacetable ou isSortable sur true
• Marquage d'une propriété isSuggestable

Modifications de propriété non autorisées

Les modifications qui interrompent l'index ou entraînent des résultats incohérents ne sont pas autorisées, y compris les suivantes :

• Type de données ou nom de la propriété
• Paramètres exactMatchWithOperator ou retrievalImportance

Exécuter une modification de schéma complexe

Pour effectuer une modification non autorisée, migrez les propriétés d'une ancienne définition vers une nouvelle :

1. Ajoutez une nouvelle propriété avec un nom différent au schéma.
2. Enregistrez le schéma avec les propriétés nouvelles et anciennes.
3. Remplissez l'index en utilisant uniquement la nouvelle propriété.
4. Supprimez l'ancienne propriété du schéma.
5. Mettez à jour le code de votre requête pour utiliser le nouveau nom de propriété.

Cloud Search enregistre les éléments supprimés pendant 30 jours pour éviter les problèmes de réutilisation.

Limites de taille

• Maximum de 10 objets de premier niveau
• Profondeur maximale de 10 niveaux
• Maximum de 1 000 champs par objet (y compris les champs imbriqués)

Étapes suivantes

1. Créer une interface de recherche.
2. Améliorer la qualité de la recherche.
3. Structurer un schéma pour une interprétation optimale des requêtes.
4. Définir des synonymes.