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

Remarque : Vous n'avez pas besoin de schéma pour les données non structurées, comme les systèmes de partage de fichiers de base sans types de fichiers prédéterminés. Vous pouvez également utiliser le SDK pour créer des objets de schéma.

Ce document décrit 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 votre schéma Cloud Search, procédez comme suit :

1. Identifier 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

Remarque : Ce document utilise un schéma de base de données de films hypothétique. Pour obtenir l'exemple complet, consultez schema.json.

Identifier le comportement attendu des utilisateurs

Anticiper la façon dont les utilisateurs effectuent leurs recherches vous aide à 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. Évaluer diverses requêtes provenant 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, comme "Les Aventuriers de l'arche perdue".
5. Déterminez les besoins de tri et de classement, comme l'ordre chronologique ou les notes de l'audience.
6. Identifiez les propriétés du contexte, telles que le poste, pour améliorer les suggestions de saisie semi-automatique.
7. Énumérez 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 redirige vers l'élément à l'aide de l'URL de la demande 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.

Figure 1. Exemple de schéma avec deux objets et un sous-objet.

Un schéma est une liste de définitions d'objets 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.

Remarque : Vous pouvez ignorer operationIds renvoyé lorsque vous demandez un schéma enregistré. Il fait référence aux opérations en attente.

Définir les propriétés des objets

Définissez des propriétés, comme le titre et la date de sortie, dans la section propertyDefinitions. Utilisez options pour freshnessOptions (classement) et displayOptions (libellés d'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"
          }
        }
      }
    ]
  }]
}

Remarque : Les noms de propriétés dans un objet doivent être uniques, quelle que soit la casse.

Une PropertyDefinition inclut les éléments suivants :

• Chaîne name.
• Options indépendantes du 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 d'UI.

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.

Remarque : Cloud Search ignore les champs non enregistrés lors de l'indexation et rejette les requêtes avec des types de données incorrects.

Ajouter des options indépendantes du type

PropertyDefinition inclut des options booléennes permettant de configurer la fonctionnalité de recherche pour 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éfini 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 sur true si la propriété peut avoir plusieurs valeurs. Par exemple, un film a une seule date de sortie, mais peut avoir plusieurs acteurs.
• isSortable : définissez la valeur sur true si la propriété peut être utilisée pour le tri. Ne peut pas être true si isRepeatable est true ou si la propriété se trouve dans un sous-objet reproductible.
• isFacetable : définissez 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).
  • Nécessite que isReturnable soit défini sur true.
  • Disponible uniquement pour les propriétés "Enum", "Boolean" et "Text".
• isWildcardSearchable : définissez sur true pour autoriser les utilisateurs à effectuer des recherches avec caractère générique sur cette propriété. Cette option n'est disponible que pour les propriétés de texte. 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 textuelle 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 énumérations (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écrire comment une propriété fonctionne en tant qu'opérateur de recherche.

Avertissement : Définissez retrievalImportance sur DEFAULT, sauf si vous êtes sûr qu'une propriété nécessite un rang plus élevé. Vous ne pourrez plus modifier ce paramètre par la suite.

Chaque operatorOptions a besoin d'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 des 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. Envoyez une requête 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 demande 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"
}

Remarque : objectType doit correspondre au nom de l'objet de schéma. Les noms de propriété dans la requête doivent respecter la casse du schéma.

Tester votre schéma

Testez 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 avec 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 les modifications suivantes :

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

Vous devez réindexer pour :

• Ajout ou suppression de propriétés ou d'objets
• Remplacement de isReturnable, isFacetable ou isSortable par true.
• Marquer une propriété isSuggestable.

Modifications de propriété non autorisées

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

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

Exécuter une modification de schéma complexe

Pour apporter 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 nouvelles et les anciennes propriétés.
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 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éez une interface de recherche.
2. Améliorer la qualité de la recherche :
3. Structurez un schéma pour une interprétation optimale des requêtes.
4. Définir des synonymes