Questa pagina è stata tradotta dall'API Cloud Translation.

Aggiornare uno schema

Puoi aggiornare i dati strutturati e i dati non strutturati con metadati che supportano uno schema.

Puoi aggiornare lo schema nella console Google Cloud o utilizzando il metodo dell'API schemas.patch.

Per aggiornare lo schema, puoi aggiungere nuovi campi, modificare le annotazioni indicizzabili, ricercabili e recuperabili per un campo o contrassegnare un campo come proprietà della chiave, ad esempio title, uri e description.

Aggiornare lo schema

Puoi aggiornare lo schema nella console Google Cloud o utilizzando l'API.

Console

Per aggiornare uno schema nella console Google Cloud :

Esamina la sezione Requisiti e limitazioni per verificare che l'aggiornamento dello schema sia valido.
Se aggiorni le annotazioni dei campi (impostando i campi come indicizzabili, recuperabili, dinamici, ricercabili o completabili), consulta Configurare le impostazioni dei campi per i limiti e i requisiti di ogni tipo di annotazione.
Verifica di aver completato l'importazione dati. In caso contrario, lo schema potrebbe non essere ancora disponibile per la modifica.
Nella console Google Cloud , vai alla pagina Gemini Enterprise.

Gemini Enterprise
Nel menu di navigazione, fai clic su Datastore.
Nella colonna Nome, fai clic sul datastore con lo schema da aggiornare.
Fai clic sulla scheda Schema per visualizzare lo schema dei tuoi dati.

Questa scheda potrebbe essere vuota se è la prima volta che modifichi i campi.
Fai clic sul pulsante Edit (Modifica).
Aggiorna lo schema:
- Mappa le proprietà chiave:nella colonna Proprietà chiave dello schema, seleziona una proprietà chiave a cui mappare un campo. Ad esempio, se un campo denominato details contiene sempre la descrizione di un documento, mappalo alla proprietà chiave Descrizione.
- Aggiorna numero di dimensioni (avanzato): puoi aggiornare questa impostazione se utilizzi incorporamenti vettoriali personalizzati con Gemini Enterprise. Consulta Avanzate: utilizzare incorporamenti personalizzati.
- Aggiorna annotazioni campo: per aggiornare le annotazioni di un campo, seleziona o deseleziona l'impostazione di annotazione di un campo. Le annotazioni disponibili sono Recuperabile, Indicizzabile, Suddivisione in facet dinamica, Ricercabile e Completabile. Alcune impostazioni dei campi presentano limitazioni. Consulta Configurare le impostazioni dei campi per le descrizioni e i requisiti per ogni tipo di annotazione.
- Aggiungi un nuovo campo:l'aggiunta di nuovi campi allo schema prima di importare nuovi documenti con questi campi può ridurre il tempo necessario a Gemini Enterprise per reindicizzare i dati dopo l'importazione.
  1. Fai clic su Aggiungi nuovi campi per espandere la sezione.
  2. Fai clic su add_box Aggiungi nodo e specifica le impostazioni per il nuovo campo.
    
    Per indicare un array, imposta Array su Sì. Ad esempio, per aggiungere un array di stringhe, imposta type su string e Array su Yes.
Fai clic su Salva per applicare le modifiche allo schema.

La modifica dello schema attiva la reindicizzazione. Per i datastore di grandi dimensioni, la reindicizzazione può richiedere ore.

REST

Per utilizzare l'API per aggiornare lo schema:

Esamina le sezioni Requisiti e limitazioni ed Esempi di limitazioni (solo REST) per verificare che le modifiche allo schema siano valide.

Per aggiornare lo schema per i datastore con dati non strutturati con metadati, vai al passaggio 5 per chiamare il metodo schema.patch.
Se stai aggiornando le annotazioni dei campi (impostando i campi come indicizzabili, recuperabili, con sfaccettature dinamiche o ricercabili), consulta Configurare le impostazioni dei campi per i limiti e i requisiti di ogni tipo di annotazione.
Se stai modificando uno schema rilevato automaticamente, assicurati di aver completato l&#39importazione datii. In caso contrario, lo schema potrebbe non essere ancora disponibile per la modifica.
Trova l'ID datastore. Se hai già l'ID del tuodatastorei, vai al passaggio successivo.
1. Nella console Google Cloud , vai alla pagina Gemini Enterprise e fai clic su Data Stores (Datastore) nel menu di navigazione.
  
  Vai alla pagina Datastore
2. Fai clic sul nome del tuo datastore.
3. Nella pagina Dati del datastore, recupera l'ID datastore.

Utilizza il metodo API schemas.patch per fornire il nuovo schema JSON come oggetto JSON.

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/schemas/default_schema" \
-d '{
  "structSchema": JSON_SCHEMA_OBJECT
}'

Sostituisci quanto segue:

PROJECT_ID: l'ID progetto.
DATA_STORE_ID: l'ID del datastore.

JSON_SCHEMA_OBJECT: il nuovo schema JSON come oggetto JSON. Ad esempio:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    }
  }
}

Esempio di comando e risultato

curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema" -d '{
"structSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"title": {
"type": "string",
"keyPropertyMapping": "title"
},
"categories": {
"type": "array",
"items": {
"type": "string",
"keyPropertyMapping": "category"
}
},
"uri": {
"type": "string",
"keyPropertyMapping": "uri"
}
}
}
}'

{
"name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema/operations/update-schema-10569824819404198922",
"metadata": {
"@type": "type.googleapis.com/google.cloud.discoveryengine.v1.UpdateSchemaMetadata"
}
}

(Facoltativo) Esamina lo schema seguendo la procedura Visualizzare una definizione dello schema.

C#

Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida di Gemini Enterprise per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Gemini Enterprise per C#.

Per eseguire l'autenticazione in Gemini Enterprise, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

using Google.Cloud.DiscoveryEngine.V1;
using Google.LongRunning;

public sealed partial class GeneratedSchemaServiceClientSnippets
{
    /// <summary>Snippet for UpdateSchema</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void UpdateSchemaRequestObject()
    {
        // Create client
        SchemaServiceClient schemaServiceClient = SchemaServiceClient.Create();
        // Initialize request argument(s)
        UpdateSchemaRequest request = new UpdateSchemaRequest
        {
            Schema = new Schema(),
            AllowMissing = false,
        };
        // Make the request
        Operation<Schema, UpdateSchemaMetadata> response = schemaServiceClient.UpdateSchema(request);

        // Poll until the returned long-running operation is complete
        Operation<Schema, UpdateSchemaMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        Schema result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<Schema, UpdateSchemaMetadata> retrievedResponse = schemaServiceClient.PollOnceUpdateSchema(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            Schema retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di Gemini Enterprise per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Gemini Enterprise per Go.


package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewSchemaClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.UpdateSchemaRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#UpdateSchemaRequest.
	}
	op, err := c.UpdateSchema(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Gemini Enterprise per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Gemini Enterprise per Java.

import com.google.cloud.discoveryengine.v1.Schema;
import com.google.cloud.discoveryengine.v1.SchemaServiceClient;
import com.google.cloud.discoveryengine.v1.UpdateSchemaRequest;

public class SyncUpdateSchema {

  public static void main(String[] args) throws Exception {
    syncUpdateSchema();
  }

  public static void syncUpdateSchema() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (SchemaServiceClient schemaServiceClient = SchemaServiceClient.create()) {
      UpdateSchemaRequest request =
          UpdateSchemaRequest.newBuilder()
              .setSchema(Schema.newBuilder().build())
              .setAllowMissing(true)
              .build();
      Schema response = schemaServiceClient.updateSchemaAsync(request).get();
    }
  }
}

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Gemini Enterprise per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Gemini Enterprise per Python.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1


def sample_update_schema():
    # Create a client
    client = discoveryengine_v1.SchemaServiceClient()

    # Initialize request argument(s)
    request = discoveryengine_v1.UpdateSchemaRequest(
    )

    # Make the request
    operation = client.update_schema(request=request)

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)

Ruby

Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida di Gemini Enterprise per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Gemini Enterprise per Ruby.

require "google/cloud/discovery_engine/v1"

##
# Snippet for the update_schema call in the SchemaService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1::SchemaService::Client#update_schema.
#
def update_schema
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::SchemaService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::UpdateSchemaRequest.new

  # Call the update_schema method.
  result = client.update_schema request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

Requisiti e limitazioni

Quando aggiorni uno schema, assicurati che il nuovo schema sia retrocompatibile con quello che stai aggiornando. Per aggiornare uno schema con un nuovo schema non compatibile con le versioni precedenti, devi eliminare tutti i documenti nel datastore, eliminare lo schema e crearne uno nuovo.

L'aggiornamento di uno schema attiva la reindicizzazione di tutti i documenti. La reindicizzazione di un datastore di grandi dimensioni può richiedere ore o giorni.

Gli aggiornamenti dello schema non supportano:

Modifica di un tipo di campo. Un aggiornamento dello schema non supporta la modifica del tipo del campo. Ad esempio, un campo mappato su integer non può essere modificato in string.
Rimuovere un campo. Una volta definito, un campo non può essere rimosso. Puoi continuare ad aggiungere nuovi campi, ma non puoi rimuovere un campo esistente.

Esempi di limitazione (solo REST)

Questa sezione mostra esempi di tipi di aggiornamenti dello schema validi e non validi. Questi esempi utilizzano lo schema JSON di esempio seguente:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    }
  }
}

Esempi di aggiornamenti supportati

Sono supportati i seguenti aggiornamenti dello schema di esempio.

Aggiunta di un campo. In questo esempio, il campo properties.uri è stato aggiunto allo schema.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "uri": { // Added field. This is supported.
      "type": "string",
      "keyPropertyMapping": "uri"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    }
  }
}

Aggiunta o rimozione di annotazioni delle proprietà chiave per title, description o uri. In questo esempio, keyPropertyMapping è stato aggiunto al campo title.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title" // Added "keyPropertyMapping". This is supported.
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    }
  }
}

Esempi di aggiornamenti dello schema non validi

I seguenti aggiornamenti allo schema di esempio non sono supportati.

Modifica di un tipo di campo. In questo esempio, il tipo del campo title è stato modificato da stringa a numero. Questa opzione non è supportata.

  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "title": {
        "type": "number" // Changed from string. Not allowed.
      },
      "description": {
        "type": "string",
        "keyPropertyMapping": "description"
      },
      "categories": {
        "type": "array",
        "items": {
          "type": "string",
          "keyPropertyMapping": "category"
        }
      }
    }
  }

Rimuovere un campo. In questo esempio, il campo title è stato rimosso. Questa opzione non è supportata.

  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      // "title" is removed. Not allowed.
      "description": {
        "type": "string",
        "keyPropertyMapping": "description"
      },
      "uri": {
        "type": "string",
        "keyPropertyMapping": "uri"
      },
      "categories": {
        "type": "array",
        "items": {
          "type": "string",
          "keyPropertyMapping": "category"
        }
      }
    }
  }