Nota:questa documentazione si applica alle versioni Standard, Plus e Frontline di Gemini Enterprise. Per informazioni sulla versione Business, consulta il Centro assistenza Gemini Enterprise - Business edition.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Aggiornare uno schema

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

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

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 Google Cloud console o utilizzando l'API.

Console

Per aggiornare uno schema nella Google Cloud console:

Esamina la sezione Requisiti e limitazioni per verificare che l'aggiornamento dello schema sia valido.
Se stai aggiornando le annotazioni dei campi (impostando i campi come indicizzabili, recuperabili, con suddivisione in facet dinamica, ricercabili o completabili), consulta Configurare le impostazioni dei campi per conoscere le limitazioni e i requisiti di ogni tipo di annotazione.
Verifica di aver completato importazione dati. In caso contrario, lo schema potrebbe non essere ancora disponibile per la modifica.
Nella Google Cloud console, 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 che vuoi aggiornare.
Fai clic sulla scheda Schema per visualizzare lo schema dei dati.

Questa scheda potrebbe essere vuota se è la prima volta che modifichi i campi.
Fai clic sul pulsante Modifica.
Aggiorna lo schema:
- Mappa le proprietà della chiave:nella colonna Proprietà della chiave dello schema, seleziona una proprietà della chiave a cui mappare un campo. Ad esempio, se un campo denominato details contiene sempre la descrizione di un documento, mappalo alla proprietà della chiave Descrizione.
- Aggiorna il numero di dimensioni (avanzato): puoi aggiornare questa impostazione se utilizzi incorporamenti di vettori personalizzati con Gemini Enterprise. Consulta Utilizzare gli incorporamenti personalizzati in nella documentazione di Vertex AI Search.
- Aggiorna le annotazioni dei campi: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 hanno limitazioni. Consulta Configurare le impostazioni dei campi per le descrizioni e i requisiti di 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 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 dei 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 suddivisione in facet dinamica o ricercabili), consulta Configurare le impostazioni dei campi per conoscere le limitazioni e i requisiti di ogni tipo di annotazione.
Se stai modificando uno schema rilevato automaticamente, assicurati di aver completato importazione dati. In caso contrario, lo schema potrebbe non essere ancora disponibile per la modifica.
Trova l'ID del datastore. Se hai già l'ID del datastore, vai al passaggio successivo.
1. Nella Google Cloud console, vai alla pagina Gemini Enterprise e nel menu di navigazione, fai clic su Datastore.
  
  Vai alla pagina Datastore
2. Fai clic sul nome del tuo datastore.
3. Nella pagina Dati del datastore, recupera l'ID del datastore.

Utilizza il schemas.patch metodo API 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 C# di Gemini Enterprise.

Per eseguire l'autenticazione in Gemini Enterprise, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 Godi Gemini Enterprise.


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 Java nella guida rapida di Gemini Enterprise per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'Java API di Gemini Enterprise.

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 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 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 Ruby di Gemini Enterprise.

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 compatibile con le versioni precedenti dello schema 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 creare un nuovo schema.

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 quanto segue:

Modifica del tipo di campo. Un aggiornamento dello schema non supporta la modifica del tipo di campo. Ad esempio, un campo mappato a integer non può essere modificato in string.
Rimozione di 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 limitazioni (solo REST)

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

{
  "$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à della 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 dello schema di esempio non sono supportati.

Modifica del tipo di campo. In questo esempio, il campo title ha avuto il tipo modificato da stringa a numero. Questa operazione 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"
        }
      }
    }
  }

Rimozione di un campo. In questo esempio, il campo title è stato rimosso. Questa operazione 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"
        }
      }
    }
  }