Creare e registrare uno schema

Uno schema Google Cloud Search è una struttura JSON che definisce oggetti, proprietà e opzioni per l'indicizzazione e l'interrogazione dei dati. Il connettore di contenuti utilizza lo schema registrato per strutturare e indicizzare i dati del repository.

Per creare uno schema, fornisci un oggetto schema JSON all'API. Devi registrare uno schema per ogni repository prima di indicizzare i dati.

Nota :non è necessario uno schema per i dati non strutturati, ad esempio i sistemi di condivisione di file di base senza tipi di file predeterminati. Puoi anche utilizzare l'SDK per creare oggetti schema.

Questo documento illustra le nozioni di base sulla creazione di schemi. Per ottimizzare l'esperienza di ricerca, consulta Migliorare la qualità della ricerca.

Crea uno schema

Per creare lo schema di Cloud Search:

1. Identificare il comportamento utente previsto
2. Inizializzare un'origine dati
3. Definisci gli oggetti
4. Definire le proprietà dell'oggetto
5. Registrare lo schema
6. Indicizzare i dati
7. Testare lo schema
8. Ottimizzare lo schema

Nota: questo documento utilizza uno schema di database di film ipotetico. Per l'esempio completo, vedi schema.json.

Identificare il comportamento previsto degli utenti

Anticipare il modo in cui gli utenti effettuano le ricerche ti aiuta a definire la strategia dello schema. Per un database di film, gli utenti potrebbero cercare "film con Robert Redford". Lo schema deve supportare le query per i film con un attore specifico.

Per allineare lo schema al comportamento degli utenti:

1. Valuta diverse query di utenti diversi.
2. Identifica i set di dati logici o oggetti, ad esempio un "film".
3. Identifica le proprietà (attributi) come il titolo o la data di uscita.
4. Identifica i valori validi per le proprietà, ad esempio "I predatori dell'arca perduta".
5. Determina le esigenze di ordinamento e ranking, ad esempio l'ordine cronologico o le valutazioni del pubblico.
6. Identifica le proprietà del contesto, ad esempio il ruolo lavorativo, per migliorare i suggerimenti del completamento automatico.
7. Elenca questi oggetti, proprietà e valori di esempio. Utilizza questo elenco per definire le opzioni dell'operatore.

Inizializza l'origine dati

Un'origine dati rappresenta i dati del repository indicizzati archiviati in Google Cloud. Consulta Gestire le origini dati di terze parti. Quando un utente fa clic su un risultato, Cloud Search lo indirizza all'elemento utilizzando l'URL della richiesta di indicizzazione.

Definisci gli oggetti

L'oggetto è l'unità fondamentale di uno schema. Strutture logiche come "film" o "persona" sono oggetti. Ogni oggetto ha proprietà come titolo, durata o nome.

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

Uno schema è un elenco di definizioni di oggetti nel tag objectDefinitions.

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

Utilizza nomi univoci per ogni oggetto, ad esempio movie. Il servizio di schema utilizza questi nomi come chiavi. Vedi ObjectDefinition.

Nota: puoi ignorare operationIds restituito quando richiedi uno schema registrato; si riferiscono a operazioni in attesa.

Definisci le proprietà dell'oggetto

Definisci le proprietà, come il titolo e la data di uscita, nella sezione propertyDefinitions. Utilizza options per freshnessOptions (classifica) e displayOptions (etichette dell'interfaccia utente).

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

Nota: i nomi delle proprietà all'interno di un oggetto devono essere univoci indipendentemente dalla distinzione tra maiuscole e minuscole.

Una PropertyDefinition include:

• Una stringa name.
• Opzioni indipendenti dal tipo (ad es. isReturnable).
• Un tipo e opzioni specifiche per il tipo (ad es. textPropertyOptions).
• operatorOptions per gli operatori di ricerca.
• displayOptions per le etichette dell'interfaccia utente.

Puoi riutilizzare i nomi delle proprietà in oggetti diversi. Ad esempio, movieTitle può apparire sia in un oggetto movie sia nella filmografia di un oggetto person.

Nota: Cloud Search scarta i campi non registrati durante l'indicizzazione e rifiuta le richieste con tipi di dati errati.

Aggiungere opzioni indipendenti dal tipo

PropertyDefinition include opzioni booleane per configurare la funzionalità di ricerca per una proprietà, indipendentemente dal tipo. Queste opzioni sono impostate per impostazione predefinita su false e devono essere impostate su true per essere utilizzate.

• isReturnable: impostato su true se i dati della proprietà devono essere restituiti nei risultati di ricerca utilizzando l'API Query. Le proprietà non restituibili possono essere utilizzate per la ricerca o la classificazione senza essere visualizzate nei risultati.
• isRepeatable: imposta su true se la proprietà può avere più valori. Ad esempio, un film ha una data di uscita, ma più attori.
• isSortable: imposta su true se la proprietà può essere utilizzata per l'ordinamento. Non può essere true se isRepeatable è true o se la proprietà si trova all'interno di un sotto-oggetto ripetibile.
• isFacetable: impostalo su true se la proprietà può essere utilizzata per generare sfaccettature (attributi utilizzati per perfezionare i risultati di ricerca).
  • Richiede che isReturnable sia true.
  • Supportato solo per le proprietà enum, booleane e di testo.
• isWildcardSearchable: impostato su true per consentire agli utenti di eseguire ricerche con caratteri jolly su questa proprietà. Questa opzione è disponibile solo per le proprietà di testo e il suo comportamento dipende dall'impostazione exactMatchWithOperator:
  • Se exactMatchWithOperator è true: il valore di testo viene trattato come un singolo token. Una query come science-* corrisponde al valore science-fiction.
  • Se exactMatchWithOperator è false: il valore di testo viene tokenizzato. Una query come sci* o fi* corrisponde a science-fiction, ma science-* no.

Definisci tipo

Imposta il tipo di dati definendo l'oggetto delle opzioni della proprietà appropriato (ad es. textPropertyOptions). Utilizza le enumerazioni (enumPropertyOptions) se conosci tutti i valori possibili. Una proprietà può avere un solo tipo di dati.

Definisci le opzioni dell'operatore

operatorOptions descrivere come una proprietà funziona come operatore di ricerca.

Avviso: imposta retrievalImportance su DEFAULT, a meno che tu non sia sicuro che una proprietà richieda un ranking più elevato. Non potrai modificare questa impostazione in un secondo momento.

Ogni operatorOptions ha bisogno di un operatorName (ad es. title). Questo è il parametro che gli utenti digitano nelle query (ad es. title:titanic). Utilizza nomi intuitivi e mostrali agli utenti.

Puoi condividere un operatorName tra proprietà dello stesso tipo. Le query che utilizzano questo nome recuperano i risultati di tutte le proprietà corrispondenti.

Le proprietà ordinabili possono includere lessThanOperatorName e greaterThanOperatorName per le query di confronto. Le proprietà di testo possono utilizzare exactMatchWithOperator per considerare l'intero valore come un singolo token.

Aggiungere opzioni di visualizzazione

La sezione facoltativa displayOptions contiene un displayLabel. Si tratta di un'etichetta facile da usare mostrata nei risultati di ricerca.

Aggiungere operatori di filtro dei suggerimenti

Utilizza suggestionFilteringOperators[] per definire una proprietà che filtra i suggerimenti di completamento automatico (ad es. filtrare i suggerimenti di film in base al genere preferito di un utente). Puoi definire un solo filtro per i suggerimenti.

Registra lo schema

Registra lo schema con il servizio di schema utilizzando l'ID origine dati. Emetti una richiesta UpdateSchema:

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

Utilizza validateOnly: true per testare lo schema senza registrarlo.

Indicizzare i dati

Dopo la registrazione, compila l'origine dati utilizzando le chiamate Index, in genere con un connettore.

Esempio di richiesta di indicizzazione:

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

Nota: objectType deve corrispondere al nome dell'oggetto schema. I nomi delle proprietà nella richiesta devono corrispondere alla distinzione tra maiuscole e minuscole dello schema.

Testare lo schema

Esegui il test con un piccolo repository prima della produzione. Crea un elenco di controllo degli accessi che limiti i risultati a un utente di test.

• Query generica: cerca una stringa (ad es. "titanic") per visualizzare tutti gli elementi corrispondenti.
• Query con operatore: utilizza un operatore (ad es. actor:Zane) per limitare i risultati.

Ottimizzare lo schema

Monitora il feedback degli utenti e modifica lo schema. Potresti indicizzare nuovi campi o rinominare gli operatori per renderli più intuitivi.

Reindicizzare dopo una modifica dello schema

Non è necessario reindicizzare per le modifiche a:

• Nomi degli operatori.
• Limiti numerici.
• Ranking ordinato.
• Opzioni di aggiornamento o visualizzazione.

Devi reindicizzare per:

• Aggiunta o rimozione di proprietà o oggetti.
• Modifica di isReturnable, isFacetable o isSortable in true.
• Contrassegnare una proprietà isSuggestable.

Modifiche alle proprietà non consentite

Non sono consentite modifiche che danneggiano l'indice o causano risultati incoerenti, tra cui:

• Tipo o nome dei dati della proprietà.
• Impostazioni di exactMatchWithOperator o retrievalImportance.

Eseguire una modifica complessa dello schema

Per apportare una modifica non consentita, esegui la migrazione delle proprietà da una vecchia definizione a una nuova:

1. Aggiungi una nuova proprietà con un nome diverso allo schema.
2. Registra lo schema con le proprietà nuove e quelle precedenti.
3. Esegui il backfill dell'indice utilizzando solo la nuova proprietà.
4. Elimina la vecchia proprietà dallo schema.
5. Aggiorna il codice della query per utilizzare il nuovo nome della proprietà.

Cloud Search registra gli elementi eliminati per 30 giorni per evitare problemi di riutilizzo.

Limitazioni delle dimensioni

• Massimo 10 oggetti di primo livello.
• Profondità massima di 10 livelli.
• Massimo 1000 campi per oggetto (inclusi i campi nidificati).

Passaggi successivi

1. Crea un'interfaccia di ricerca.
2. Migliorare la qualità della ricerca.
3. Struttura uno schema per un'interpretazione ottimale delle query.
4. Definisci i sinonimi.