Creare e registrare uno schema

Uno schema di Google Cloud Search è una struttura JSON che definisce gli oggetti, le proprietà e le opzioni da utilizzare per l'indicizzazione e l'esecuzione di query sui dati. Il connettore di contenuti legge i dati dal repository e, in base allo schema registrato, struttura e indicizza i dati.

Puoi creare uno schema fornendo un oggetto schema JSON all'API e quindi registrandolo. Devi registrare un oggetto schema per ciascuno dei tuoi repository prima di poter indicizzare i dati.

Nota: non è necessario creare uno schema se il repository di dati contiene solo dati non strutturati. Ad esempio, se disponi di un sistema di condivisione file di base senza tipi di file e strutture predeterminati, di solito non hai bisogno di uno schema. Puoi anche creare un oggetto schema utilizzando l'SDK anziché fornire un oggetto JSON all'API.

Questo documento illustra le nozioni di base della creazione di schemi. Per informazioni su come ottimizzare lo schema per migliorare l'esperienza di ricerca, consulta Migliorare la qualità della ricerca.

Crea uno schema

Di seguito è riportato un elenco dei passaggi utilizzati per creare lo schema di Cloud Search:

1. Identificare il comportamento previsto degli utenti
2. Inizializzare un'origine dati
3. Crea uno schema
4. Schema di esempio completo
5. Registrare lo schema
6. Indicizzare i dati
7. Testare lo schema
8. Ottimizzare lo schema

Nota: questo documento utilizza snippet di uno schema per un database di film ipotetico. Per lo schema completo, consulta schema.json

Identificare il comportamento previsto degli utenti

Prevedere i tipi di query effettuate dagli utenti aiuta a definire la strategia di creazione dello schema.

Ad esempio, quando esegui query su un database di film, potresti aspettarti che l'utente esegua una query come "Mostrami tutti i film con Robert Redford". Il tuo schema, pertanto, deve supportare i risultati delle query basati su "Tutti i film con un attore specifico".

Per definire lo schema in modo che rifletta i pattern di comportamento dell'utente, ti consigliamo di eseguire le seguenti attività:

1. Valuta un insieme eterogeneo di query desiderate da utenti diversi.
2. Identifica gli oggetti che potrebbero essere utilizzati nelle query. Gli oggetti sono set logici di dati correlati, ad esempio un film in un database di film.
3. Identificare le proprietà e i valori che compongono l'oggetto e che potrebbero essere utilizzati nelle query. Le proprietà sono gli attributi indicizzabili dell'oggetto; possono includere valori primitivi o altri oggetti. Ad esempio, un oggetto movie potrebbe avere proprietà come il titolo e la data di uscita del film come valori primitivi. L'oggetto film può anche contenere altri oggetti, come i membri del cast, che hanno le loro proprietà, come il nome o il ruolo.
4. Identificare esempi di valori validi per le proprietà. I valori sono i dati effettivi indicizzati per una proprietà. Ad esempio, il titolo di un film nel tuo database potrebbe essere "I predatori dell'arca perduta".
5. Determina le opzioni di ordinamento e ranking desiderate dagli utenti. Ad esempio, quando eseguono query sui film, gli utenti potrebbero voler ordinare i film in ordine cronologico e classificarli in base alla valutazione del pubblico, senza dover ordinare i film in ordine alfabetico per titolo.
6. (Facoltativo) Valuta se una delle tue proprietà rappresenta un contesto più specifico in cui potrebbero essere eseguite le ricerche, ad esempio il ruolo o il reparto lavorative degli utenti, in modo che possano essere forniti suggerimenti di completamento automatico in base al contesto. Ad esempio, per chi cerca in un database di film, gli utenti potrebbero essere interessati solo a un determinato genere di film. Gli utenti devono definire il genere in cui vogliono che vengano restituite le proprie ricerche, possibilmente come parte del loro profilo utente. Quando un utente inizia a digitare una query di film, solo i film del suo genere preferito, ad esempio "film d'azione", vengono suggeriti come parte dei suggerimenti di completamento automatico.
7. Crea un elenco di questi oggetti, proprietà e valori di esempio che possono essere utilizzati nelle ricerche. Per maggiori dettagli sulle modalità di utilizzo dell'elenco, consulta la sezione Definisci le opzioni dell'operatore.

Inizializzare l'origine dati

Un'origine dati rappresenta i dati di un repository che è stato indicizzato e archiviato in Google Cloud. Per istruzioni sull'inizializzazione di un'origine dati, consulta Gestire le origini dati di terze parti.

I risultati di ricerca di un utente vengono restituiti dall'origine dati. Quando un utente fa clic su un risultato di ricerca, Cloud Search lo indirizza all'elemento effettivo utilizzando l'URL fornito nella richiesta di indicizzazione.

Definisci gli oggetti

L'unità fondamentale dei dati in uno schema è l'oggetto, chiamato anche "oggetto schema", che è una struttura logica dei dati. In un database di film, una struttura logica dei dati è "movie". Un altro oggetto potrebbe essere una "persona" che rappresenta il cast e la troupe coinvolti nel film.

Ogni oggetto in uno schema ha una serie di proprietà o attributi che descrivono l'oggetto, come il titolo e la durata di un film o il nome e la data di nascita di una persona. Le proprietà di un oggetto possono includere valori primitivi o altri oggetti.

La Figura 1 mostra gli oggetti filmato e persona e le proprietà associate.

Figura 1. Uno schema di esempio che mostra due oggetti e un oggetto secondario.

Uno schema di Cloud Search è essenzialmente un elenco di istruzioni di definizione degli oggetti definite all'interno del tag objectDefinitions. Il seguente snippet di schema mostra le istruzioni objectDefinitions per gli oggetti dello schema Movie e Person.

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

Quando definisci un oggetto schema, fornisci un name per l'oggetto, che deve essere univoco tra tutti gli altri oggetti nello schema. In genere viene utilizzato un valore name che descrive l'oggetto, ad esempio movie per un oggetto film. Il servizio di schema utilizza il campo name come identificatore chiave per gli oggetti indicizzabili. Per ulteriori informazioni sul campo name, consulta la definizione dell'oggetto.

Nota: uno schema di Cloud Search contiene in realtà due sezioni di primo livello: objectDefinitions e operationIds. Quando lo schema è in uso e sono presenti operazioni a lunga esecuzione (LRO) in sospeso, operationIds di questi LRO vengono restituiti quando richiedi lo schema registrato. Non puoi impostare operationIds e puoi ignorare questa parte dello schema.

Definisci le proprietà dell'oggetto

Come specificato nel riferimento per ObjectDefinition, il nome dell'oggetto è seguito da un insieme di options e da un elenco di propertyDefinitions. La options può essere ulteriormente costituita da freshnessOptions e displayOptions. Gli attributi freshnessOptions vengono utilizzati per modificare il ranking nei risultati di ricerca in base all'attualità di un articolo. Gli attributi displayOptions vengono utilizzati per definire se nei risultati di ricerca di un oggetto vengono visualizzate etichette e proprietà specifiche.

Nota: per informazioni dettagliate sull'ottimizzazione di freshnessOptions al fine di migliorare l'esperienza di ricerca, consulta Influenza l'aggiornamento in Migliorare la qualità della ricerca.

La sezione propertyDefinitions consente di definire le proprietà di un oggetto, come il titolo e la data di uscita del film.

Lo snippet seguente mostra l'oggetto movie con due proprietà: 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"
          }
      ...
      ]
    }
  ]
}

Nota: se definiti all'interno dello stesso oggetto, i nomi delle proprietà che differiscono solo nel caso, ad esempio movieTitle e movietitle, sono considerati uguali e generano un errore.

Il campo PropertyDefinition comprende i seguenti elementi:

• una stringa name.
• Un elenco di opzioni indipendenti dal tipo, come isReturnable nello snippet precedente.
• Un tipo e le opzioni specifiche del tipo associate, come textPropertyOptions e retrievalImportance nello snippet precedente.
• Un operatorOptions che descrive come la proprietà viene utilizzata come operatore di ricerca.
• Uno o più displayOptions, ad esempio displayLabel nello snippet precedente.

name di una proprietà deve essere univoco all'interno dell'oggetto contenitore, ma lo stesso nome può essere utilizzato in altri oggetti e oggetti secondari. Nella Figura 1, il titolo e la data di uscita del film sono stati definiti due volte: una volta nell'oggetto movie e di nuovo nell'oggetto secondario filmography dell'oggetto person. Questo schema riutilizza il campo movieTitle in modo che lo schema possa supportare due tipi di comportamenti di ricerca:

• Mostra i risultati relativi ai film quando gli utenti cercano il titolo di un film.
• Mostra i risultati relativi alle persone quando gli utenti cercano il titolo di un film in cui è recitato un attore.

Allo stesso modo, lo schema riutilizza il campo releaseDate perché ha lo stesso significato per i due campi movieTitle.

Nello sviluppo di uno schema, considera in che modo il repository potrebbe avere campi correlati contenenti dati che vuoi dichiarare più di una volta nello schema.

Nota: se una richiesta di indicizzazione tenta di indicizzare un elemento con una proprietà o un campo non registrato, come date anziché releaseDate, il sistema ignora il campo. Se la richiesta di indicizzazione fornisce un tipo di dati errato per una proprietà, ad esempio fornendo un numero intero per il campo della durata (che prevede testo in modo da poter gestire le abbreviazioni delle unità), il sistema rifiuta l'intera richiesta.

Aggiungi opzioni indipendenti dal tipo

PropertyDefinition elenca le opzioni di funzionalità di ricerca generali comuni a tutte le proprietà, indipendentemente dal tipo di dati.

• isReturnable: indica se la proprietà identifica i dati che devono essere restituiti nei risultati di ricerca tramite l'API Query. Tutte le proprietà filmato di esempio sono restituibili. Le proprietà non restituibili possono essere utilizzate per cercare o classificare i risultati senza che vengano restituiti all'utente.
• isRepeatable: indica se sono consentiti più valori per la proprietà. Ad esempio, un film ha una sola data di uscita, ma può avere più attori.
• isSortable: indica che la proprietà può essere utilizzata per l'ordinamento. Questo non può essere vero per le proprietà ripetibili. Ad esempio, i risultati relativi ai film possono essere ordinati per data di uscita o valutazione del pubblico.
• isFacetable: indica che la proprietà può essere utilizzata per generare facets. Un facet viene utilizzato per perfezionare i risultati di ricerca in cui l'utente visualizza i risultati iniziali e poi aggiunge criteri, o facet, per perfezionare ulteriormente questi risultati. Questa opzione non può essere true per le proprietà il cui tipo è oggetto e il valore isReturnable deve essere true per poter essere impostato. Infine, questa opzione è supportata solo per le proprietà enum, booleane e testo. Ad esempio, nel nostro schema di esempio, potremmo rendere suddivisi in facet genre, actorName, userRating e mpaaRating per consentirne l'utilizzo per il perfezionamento interattivo dei risultati di ricerca.
• isWildcardSearchable indica che gli utenti possono eseguire ricerche con caratteri jolly per questa proprietà. Questa opzione è disponibile solo nelle proprietà di testo. Il funzionamento della ricerca con caratteri jolly nel campo di testo dipende dal valore impostato nel campo exactMatchWithOperator. Se exactMatchWithOperator è impostato su true, il valore di testo viene tokenizzato come un valore atomico e viene eseguita una ricerca con caratteri jolly. Ad esempio, se il valore di testo è science-fiction, viene trovata una corrispondenza con una query con caratteri jolly science-*. Se il criterio exactMatchWithOperator è impostato su false, il valore di testo viene tokenizzato e viene eseguita una ricerca con caratteri jolly su ciascun token. Ad esempio, se il valore di testo è "fantascienza", le query con caratteri jolly sci* o fi* corrispondono all'elemento, ma non science-*.

Questi parametri della funzionalità di ricerca generale sono tutti valori booleani; hanno tutti un valore predefinito false e devono essere impostati su true per poter essere utilizzati.

La seguente tabella mostra i parametri booleani impostati su true per tutte le proprietà dell'oggetto movie:

Proprietà	isReturnable	isRepeatable	isSortable	isFacetable	isWildcardSearchable
movieTitle	true				true
releaseDate	true		true
genre	true	true		true
duration	true
actorName	true	true		true	true
userRating	true		true
mpaaRating	true			true

Sia genre che actorName hanno isRepeatable impostato su true perché un film potrebbe appartenere a più di un genere e in genere ha più di un attore. Una proprietà non può essere ordinabile se è ripetibile o contenuta in un oggetto secondario ripetibile.

Definisci tipo

La sezione di riferimento PropertyDefinition elenca diversi xxPropertyOptions in cui xx è un tipo specifico, ad esempio boolean. Per impostare il tipo di dati della proprietà, devi definire l'oggetto di tipo dati appropriato. La definizione di un oggetto di tipo dati per una proprietà stabilisce il tipo di dati di quella proprietà. Ad esempio, la definizione di textPropertyOptions per la proprietà movieTitle indica che il titolo del film è di tipo testo. Lo snippet seguente mostra la proprietà movieTitle con textPropertyOptions che imposta il tipo di dati.

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

Nota: se comprendi l'insieme completo dei possibili valori per una proprietà, utilizza un enum (enumPropertyOptions) anziché un tipo di stringa. Se l'enumerazione cambia nelle versioni future, utilizza le introspezioni per controllare lo schema e aggiornarlo dove necessario.

Una proprietà può avere un solo tipo di dati associato. Ad esempio, nel nostro schema dei film, releaseDate può essere solo una data (ad es. 2016-01-13) o una stringa (ad es. January 13, 2016), ma non entrambe.

Di seguito sono riportati gli oggetti di tipo dati utilizzati per specificare i tipi di dati relativi alle proprietà nello schema dei filmati di esempio:

Proprietà	Oggetto tipo di dati
movieTitle	textPropertyOptions
releaseDate	datePropertyOptions
genre	enumPropertyOptions
duration	textPropertyOptions
actorName	textPropertyOptions
userRating	integerPropertyOptions
mpaaRating	textPropertyOptions

Il tipo di dati che scegli per la proprietà dipende dai casi d'uso previsti. Nello scenario immaginario di questo schema di filmati, gli utenti dovrebbero ordinare i risultati in ordine cronologico, quindi releaseDate è un oggetto data. Se, ad esempio, esisteva un caso d'uso previsto per confrontare le release di dicembre con quelle di gennaio, potrebbe essere utile un formato stringa.

Configura opzioni specifiche per tipo

La sezione di riferimento PropertyDefinition contiene un link alle opzioni per ogni tipo. La maggior parte delle opzioni specifiche per tipo è facoltativa, ad eccezione dell'elenco di possibleValues in enumPropertyOptions. Inoltre, l'opzione orderedRanking ti consente di classificare i valori rispetto agli altri. Il seguente snippet mostra la proprietà movieTitle con textPropertyOptions che imposta il tipo di dati e l'opzione retrievalImportance specifico per il tipo.

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

Di seguito sono riportate le opzioni aggiuntive specifiche del tipo utilizzate nello schema di esempio:

Proprietà	Tipo	Opzioni specifiche per tipo
movieTitle	textPropertyOptions	retrievalImportance
releaseDate	datePropertyOptions
genre	enumPropertyOptions
duration	textPropertyOptions
actorName	textPropertyOptions
userRating	integerPropertyOptions	orderedRanking, maximumValue
mpaaRating	textPropertyOptions

Definisci opzioni operatore

Oltre alle opzioni specifiche del tipo, ogni tipo ha un insieme di operatorOptions facoltative. Queste opzioni descrivono in che modo la proprietà viene utilizzata come operatore di ricerca. Lo snippet seguente mostra la proprietà movieTitle con textPropertyOptions che imposta il tipo di dati e con le opzioni retrievalImportance e operatorOptions specifiche per il tipo.

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

Avviso: a meno che tu non abbia la certezza assoluta che una proprietà debba avere un ranking più elevato rispetto alle altre nei risultati di ricerca, imposta retrievalImportance su DEFAULT. Una volta impostata, questa opzione non può essere modificata. Ad esempio, se una proprietà rappresenta un titolo, è consigliabile assegnargli l'importanza HIGHEST. Tuttavia, se una proprietà contiene numeri di parte che sono riferimenti ad altre parti, ma non sono la parte in sé, valuta la possibilità di contrassegnare la proprietà come importanza BASSO. Se hai dubbi sull'importanza della proprietà, utilizza DEFAULT. Se sei sicuro che il testo non deve essere utilizzato per il recupero, utilizza NONE. Per saperne di più, consulta Importanza.

Ogni operatorOptions ha un operatorName, ad esempio title per un movieTitle. Il nome dell'operatore è l'operatore di ricerca per la proprietà. Un operatore di ricerca è il parametro effettivo che ti aspetti che gli utenti utilizzino quando restringono una ricerca. Ad esempio, per cercare film in base al titolo, l'utente dovrebbe digitare title:movieName, dove movieName è il nome di un film.

I nomi degli operatori non devono necessariamente corrispondere al nome della proprietà. Dovresti usare invece i nomi degli operatori che riflettono le parole più comuni utilizzate dagli utenti della tua organizzazione. Ad esempio, se gli utenti preferiscono il termine "name" anziché "title" per il titolo di un film, il nome dell'operatore deve essere impostato su "name".

Nota: è importante esporre i nomi degli operatori agli utenti, come opzioni nell'interfaccia di ricerca o nella documentazione. Gli utenti devono sapere quali operatori utilizzare per perfezionare le query di ricerca.

Puoi utilizzare lo stesso nome operatore per più proprietà purché tutte le proprietà si risolvano nello stesso tipo. Quando utilizzi un nome operatore condiviso durante una query, vengono recuperate tutte le proprietà che utilizzano il nome dell'operatore. Ad esempio, supponiamo che l'oggetto film abbia proprietà plotSummary e plotSynopsis e che ciascuna di queste proprietà abbia un operatorName pari a plot. Se entrambe queste proprietà sono testo (textPropertyOptions), una singola query che utilizza l'operatore di ricerca plot le recupera entrambe.

Oltre a operatorName, le proprietà ordinabili possono avere lessThanOperatorName e greaterThanOperatorName campi in operatorOptions. Gli utenti possono utilizzare queste opzioni per creare query basate sui confronti con un valore inviato.

Infine, textOperatorOptions ha un campo exactMatchWithOperator in operatorOptions. Se imposti exactMatchWithOperator su true, la stringa di query deve corrispondere all'intero valore della proprietà, non semplicemente all'interno del testo. Il valore di testo viene trattato come un valore atomico nelle ricerche degli operatori e nelle corrispondenze dei facet.

Ad esempio, prendi in considerazione l'indicizzazione di oggetti Book o Movie con proprietà genere. I generi potrebbero includere "Fantascienza", "Scienza" e "Fiction". Se il criterio exactMatchWithOperator è impostato su false o viene omesso, la ricerca di un genere o la selezione del facet "Scienza" o "Fiction" restituirà anche risultati per "Fantascienza", poiché il testo è tokenizzato e i token "Scienza" e "Fiction" sono presenti in "Fantascienza". Quando exactMatchWithOperator è true, il testo viene considerato come un singolo token, quindi né "Scienza" né "Fiction" corrisponde a "Fantascienza".

(Facoltativo) Aggiungi la sezione displayOptions

È presente una sezione facoltativa displayOptions alla fine di ogni sezione propertyDefinition. Questa sezione contiene una stringa displayLabel. displayLabel è un'etichetta di testo consigliata e facile da usare per la proprietà. Se la proprietà è configurata per la visualizzazione utilizzando ObjectDisplayOptions, questa etichetta viene visualizzata davanti alla proprietà. Se la proprietà è configurata per la visualizzazione e displayLabel non è definito, viene visualizzato solo il valore della proprietà.

Lo snippet seguente mostra la proprietà movieTitle con displayLabel impostato su "Titolo".

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

Di seguito sono riportati i valori displayLabel per tutte le proprietà dell'oggetto movie nello schema di esempio:

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

(Facoltativo) Aggiungi una sezione suggestionFilteringOperators[]

È presente una sezione facoltativa suggestionFilteringOperators[] alla fine di ogni sezione di propertyDefinition. Utilizza questa sezione per definire una proprietà utilizzata per filtrare i suggerimenti di completamento automatico. Ad esempio, puoi definire l'operatore genre per filtrare i suggerimenti in base al genere di film preferito dall'utente. Quando l'utente digita la query di ricerca, i suggerimenti di completamento automatico visualizzano solo i film che corrispondono al genere preferito.

Nota: anche se questo campo è un array, puoi definire un solo filtro per i suggerimenti. Se definisci più di un filtro, viene riconosciuto solo il primo filtro definito.

Registra il tuo schema

Per ricevere dati strutturati dalle query di Cloud Search, devi registrare lo schema nel servizio per gli schemi di Cloud Search. La registrazione di uno schema richiede l'ID origine dati ottenuto durante il passaggio Inizializzare un'origine dati.

Utilizza l'ID origine dati per inviare una richiesta UpdateSchema per registrare lo schema.

Come descritto in dettaglio nella pagina di riferimento UpdateSchema, invia la seguente richiesta HTTP per registrare lo schema:

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

Il corpo della richiesta deve contenere quanto segue:

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

Utilizza l'opzione validateOnly per testare la validità dello schema senza registrarlo.

Indicizza i dati

Una volta registrato lo schema, compila l'origine dati utilizzando le chiamate Index. In genere, l'indicizzazione viene eseguita all'interno del connettore di contenuti.

Utilizzando lo schema del filmato, una richiesta di indicizzazione dell'API REST per un singolo film avrebbe il seguente aspetto:

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

Nota che il valore di movie nel campo objectType corrisponde al nome di definizione dell'oggetto nello schema. Con la corrispondenza di questi due valori, Cloud Search stabilisce quale oggetto schema usare durante l'indicizzazione.

Nota inoltre che l'indicizzazione della proprietà schema releaseDate utilizza le proprietà secondarie di year, month e day, che eredita perché è definita come tipo di dati date mediante l'utilizzo di datePropertyOptions per definirla. Tuttavia, poiché year, month e day non sono definiti nello schema, non puoi eseguire query su una di queste proprietà (ad es. year) singolarmente.

Inoltre, nota come la proprietà ripetibile actorName viene indicizzata utilizzando un elenco di valori.

Nota: il nome della proprietà in una richiesta di indicizzazione deve corrispondere al caso della proprietà nello schema oppure una parte della richiesta di indicizzazione viene eliminata come proprietà non registrata.

Identificazione di potenziali problemi di indicizzazione

I due problemi più comuni relativi agli schemi e all'indicizzazione sono:

• La richiesta di indicizzazione contiene il nome di una proprietà o di un oggetto schema non registrato con il servizio schema. Questo problema fa sì che la proprietà o l'oggetto venga ignorato.

• La tua richiesta di indicizzazione ha una proprietà con un valore del tipo diverso da quello registrato nello schema. Questo problema fa sì che Cloud Search restituisca un errore al momento dell'indicizzazione.

Testa lo schema con diversi tipi di query

Prima di registrare lo schema per un repository di dati di produzione di grandi dimensioni, valuta la possibilità di eseguire i test con un repository di dati di test più piccolo. I test con un repository di test più piccolo consentono di apportare rapidamente modifiche allo schema ed eliminare i dati indicizzati, senza influire su un indice più grande o su un indice di produzione esistente. Per un repository di dati di test, crea un ACL che autorizza solo un utente di test in modo che gli altri utenti non vedano questi dati nei risultati della Ricerca.

Per creare un'interfaccia di ricerca per convalidare le query di ricerca, consulta L'interfaccia di ricerca

Questa sezione contiene diversi esempi di query che potresti utilizzare per testare lo schema di un film.

Eseguire un test con una query generica

Una query generica restituisce tutti gli elementi nell'origine dati contenenti una stringa specifica. Utilizzando un'interfaccia di ricerca, potresti eseguire una query generica sull'origine dati di un film digitando la parola "titanic" e premendo Invio. Tutti i film con la parola "titanic" dovrebbero essere restituiti nei risultati di ricerca.

Esegui il test con un operatore

L'aggiunta di un operatore alla query limita i risultati agli elementi che corrispondono al valore dell'operatore. Ad esempio, potresti voler utilizzare l'operatore actor per trovare tutti i film con un attore specifico. Utilizzando un'interfaccia di ricerca, puoi eseguire questa query con l'operatore semplicemente digitando una coppia operator=value, ad esempio "actor:Zane", e premendo Invio. Tutti i film con Zane come attore devono essere restituiti nei risultati di ricerca.

Ottimizza lo schema

Una volta che lo schema e i dati sono in uso, continua a monitorare cosa funziona e cosa no per i tuoi utenti. Ti consigliamo di modificare lo schema per le seguenti situazioni:

• Indicizzazione di un campo che non era stato precedentemente indicizzato. Ad esempio, gli utenti potrebbero cercare ripetutamente film in base al nome del regista, quindi potresti modificare lo schema in modo che supporti il nome del regista come operatore.
• Modifica dei nomi degli operatori di ricerca in base al feedback degli utenti. I nomi degli operatori devono essere facili da usare. Se i tuoi utenti "ricordano" ripetutamente il nome dell'operatore sbagliato, puoi cambiarlo.

Nota: quando lo schema viene aggiornato o eliminato, viene aggiornata anche l'applicazione di ricerca. Ad esempio, se un operatore di schema viene rinominato, viene rinominato anche nella configurazione dell'applicazione di ricerca. Se l'aggiornamento dello schema non è compatibile con l'applicazione di ricerca e non è possibile aggiornarlo, l'aggiornamento dello schema non riesce e viene inviato un errore nella risposta di aggiornamento.

Reindicizzazione dopo una modifica dello schema

La modifica di uno qualsiasi dei seguenti valori nello schema non richiede la reindicizzazione dei dati. Puoi semplicemente inviare una nuova richiesta UpdateSchema e l'indice continuerà a funzionare:

• Nomi degli operatori.
• Valori minimi e massimi interi.
• Ranking in ordine di numeri interi ed enum.
• Opzioni di aggiornamento.
• Opzioni di visualizzazione.

Per le seguenti modifiche, i dati indicizzati in precedenza continueranno a funzionare in base allo schema registrato in precedenza. Tuttavia, devi reindicizzare le voci esistenti per visualizzare le modifiche basate sullo schema aggiornato se presenta queste modifiche:

• Aggiunta o rimozione di una nuova proprietà o di un nuovo oggetto
• Modifica di isReturnable, isFacetable o isSortable da false a true.

Dovresti impostare isFacetable o isSortable su true solo se hai un caso d'uso e una necessità chiari.

Infine, quando aggiorni lo schema contrassegnando una proprietà isSuggestable, devi reindicizzare i dati, il che provoca un ritardo nell'utilizzo del completamento automatico per quella proprietà.

Modifiche alle proprietà non consentite

Alcune modifiche allo schema non sono consentite, anche se reindicizzi i dati, perché danneggeranno l'indice o produrranno risultati di ricerca scarsi o incoerenti. Sono incluse le modifiche a:

• Tipo di dati della proprietà.
• Nome proprietà.
• Impostazione exactMatchWithOperator.
• Impostazione retrievalImportance.

Tuttavia, c'è un modo per aggirare questa limitazione.

Apporta una modifica complessa allo schema

Per evitare modifiche che genererebbero risultati di ricerca scarsi o un indice di ricerca non funzionante, Cloud Search impedisce alcuni tipi di modifiche nelle richieste UpdateSchema dopo l'indicizzazione del repository. Ad esempio, non è possibile modificare il tipo di dati o il nome di una proprietà dopo la configurazione. Queste modifiche non possono essere ottenute tramite una semplice richiesta UpdateSchema, anche se reindicizzi i dati.

Nelle situazioni in cui devi apportare una modifica allo schema non consentita, spesso puoi apportare una serie di modifiche consentite che ottengono lo stesso effetto. In generale, ciò comporta prima la migrazione delle proprietà indicizzate da una definizione di oggetto precedente a una nuova e quindi l'invio di una richiesta di indicizzazione che utilizza solo la proprietà più recente.

I seguenti passaggi mostrano come modificare il tipo di dati o il nome di una proprietà:

1. Aggiungi una nuova proprietà alla definizione dell'oggetto nello schema. Utilizza un nome diverso dalla proprietà che vuoi modificare.
2. Invia la richiesta UpdateSchema con la nuova definizione. Ricordati di inviare nella richiesta l'intero schema, incluse la nuova e la vecchia proprietà.

3. Esegui il backfill dell'indice dal repository di dati. Per eseguire il backfill dell'indice, invia tutte le richieste di indicizzazione utilizzando la nuova proprietà, ma non la vecchia proprietà, poiché ciò comporterebbe un doppio conteggio delle corrispondenze delle query.

   1. Durante il backfill dell'indicizzazione, controlla la nuova proprietà e imposta la vecchia proprietà come predefinita per evitare comportamenti incoerenti.
   2. Una volta completato il backfill, esegui query di test per verificare.

4. Elimina la proprietà precedente. Invia un'altra richiesta UpdateSchema senza il vecchio nome della proprietà e interrompi l'utilizzo di questo nome nelle future richieste di indicizzazione.

5. Eseguire la migrazione dell'utilizzo della vecchia proprietà alla nuova. Ad esempio, se modifichi il nome della proprietà da autore ad autore, devi aggiornare il codice della query per utilizzare l'autore dove in precedenza faceva riferimento all'autore.

Cloud Search conserva per 30 giorni un registro di qualsiasi proprietà o oggetto eliminato, per evitare qualsiasi riutilizzo che potrebbe causare risultati di indicizzazione imprevisti. Entro questi 30 giorni, dovrai eseguire la migrazione da tutti gli utilizzi dell'oggetto o della proprietà eliminati, anche per ometterli dalle future richieste di indicizzazione. In questo modo, se in seguito decidi di reintegrare la proprietà o l'oggetto, potrai farlo in modo da mantenere l'indice corretto.

Scopri i limiti delle dimensioni

Cloud Search impone dei limiti alle dimensioni degli oggetti di dati strutturati e degli schemi. Questi limiti sono:

• Il numero massimo di oggetti di primo livello è 10 oggetti.
• La profondità massima di una gerarchia di dati strutturati è 10 livelli.
• Il numero totale di campi in un oggetto è limitato a 1000, che include il numero di campi primitivi più la somma del numero di campi in ogni oggetto nidificato.

Passaggi successivi

Di seguito sono riportati alcuni passaggi che puoi eseguire:

1. Crea un'interfaccia di ricerca per testare lo schema.

2. Ottimizza lo schema per migliorare la qualità della ricerca.

3. Struttura uno schema per un'interpretazione ottimale delle query.

4. Scopri come sfruttare lo schema _dictionaryEntry per definire i sinonimi dei termini comunemente utilizzati nella tua azienda. Per utilizzare lo schema _dictionaryEntry, consulta Definire i sinonimi.

5. Crea un connettore.