Actualiza un esquema

Puedes actualizar los datos estructurados y los datos no estructurados con metadatos del esquema que admite un esquema.

Puedes actualizar el esquema en la consola de Google Cloud o con el método de la API de schemas.patch.

Para actualizar el esquema, puedes agregar campos nuevos, cambiar las anotaciones indexables, de búsqueda y recuperables de un campo, o marcar un campo como propiedad clave, como title, uri y description.

Importante: Google recomienda enfáticamente que actualices tu esquema con asignaciones de propiedades clave, en especial para title. Esto garantiza que tus resultados se muestren correctamente y ayuda a Gemini Enterprise a identificar información importante que le permite generar mejores resultados.

Actualiza tu esquema

Puedes actualizar tu esquema en la consola de Google Cloud o con la API.

Nota: Editar el esquema vuelve a indexar tu almacén de datos. En el caso de los almacenes de datos grandes, la indexación puede tardar varias horas.

Console

Para actualizar un esquema en la consola de Google Cloud , sigue estos pasos:

1. Revisa la sección Requisitos y limitaciones para verificar que la actualización del esquema sea válida.

2. Si actualizas las anotaciones de campos (estableces campos como indexables, recuperables, aptos para la categorización en facetas dinámicas, aptos para la búsqueda o aptos para la función de autocompletar), revisa Configura los parámetros de configuración de los campos para conocer las limitaciones y los requisitos de cada tipo de anotación.

3. Verifica que hayas completado la transferencia de datos. De lo contrario, es posible que el esquema aún no esté disponible para editarlo.

4. En la consola de Google Cloud , ve a la página Gemini Enterprise.

   Gemini Enterprise

5. En el menú de navegación, haz clic en Almacenes de datos.

6. En la columna Nombre, haz clic en el almacén de datos con el esquema que deseas actualizar.

7. Haz clic en la pestaña Esquema para ver el esquema de tus datos.

   Esta pestaña puede estar vacía si es la primera vez que editas los campos.

8. Haz clic en el botón Editar.

9. Actualiza tu esquema:

   • Asigna propiedades clave: En la columna Propiedades clave de tu esquema, selecciona una propiedad clave para asignar un campo. Por ejemplo, si un campo llamado details siempre contiene la descripción de un documento, asigna ese campo a la propiedad clave Description.

   • Actualizar la cantidad de dimensiones (avanzado): Puedes actualizar este parámetro de configuración si usas incorporaciones de vectores personalizadas con Gemini Enterprise. Consulta Avanzado: Usa incorporaciones personalizadas.

   • Actualiza las anotaciones de los campos: Para actualizar las anotaciones de un campo, selecciona o anula la selección de la configuración de anotación de un campo. Las anotaciones disponibles son Recuperable, Indexable, Faceta dinámica, Se puede buscar y Completable. Algunos parámetros de configuración de los campos tienen limitaciones. Consulta Configura los parámetros de configuración de los campos para obtener descripciones y requisitos de cada tipo de anotación.

   • Agregar un campo nuevo: Agregar campos nuevos a tu esquema antes de importar documentos nuevos con esos campos puede reducir el tiempo que Gemini Enterprise tarda en volver a indexar tus datos después de la importación.

     1. Haz clic en Agregar campos nuevos para expandir esa sección.

     2. Haz clic en add_box Agregar nodo y especifica la configuración del campo nuevo.

        Para indicar un array, configura Array en Yes. Por ejemplo, para agregar un array de cadenas, establece type en string y Array en Yes.

10. Haz clic en Guardar para aplicar los cambios en el esquema.

    Cambiar el esquema activa la reindexación. En el caso de los almacenes de datos grandes, la reindexación puede tardar horas.

REST

Para usar la API y actualizar tu esquema, sigue estos pasos:

1. Revisa las secciones Requisitos y limitaciones y Ejemplos de limitaciones (solo para REST) para verificar que los cambios en tu esquema sean válidos.

   Para actualizar el esquema de los almacenes de datos con datos no estructurados y metadatos, ve al paso 5 para llamar al método schema.patch.

2. Si actualizas las anotaciones de campo (estableces campos como indexables, recuperables, facetables dinámicos o aptos para la búsqueda), revisa Cómo configurar los parámetros de configuración de los campos para conocer las limitaciones y los requisitos de cada tipo de anotación.

3. Si editas un esquema detectado automáticamente, asegúrate de haber completado la transferencia de datos. De lo contrario, es posible que el esquema aún no esté disponible para editarlo.

4. Busca el ID de tu almacén de datos. Si ya tienes el ID del almacén de datos, ve al siguiente paso.

   1. En la consola de Google Cloud , ve a la página Gemini Enterprise y, en el menú de navegación, haz clic en Almacenes de datos.

      Ve a la página Almacenes de datos.

   2. Haz clic en el nombre de tu almacén de datos.

   3. En la página Datos de tu almacén de datos, obtén el ID del almacén de datos.

5. Usa el método de la API de schemas.patch para proporcionar tu nuevo esquema JSON como un objeto 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
   }'
   

   Reemplaza lo siguiente:

   • PROJECT_ID: el ID de tu proyecto.
   • DATA_STORE_ID: Es el ID del almacén de datos.

   • JSON_SCHEMA_OBJECT: Tu nuevo esquema JSON como un objeto JSON. Por ejemplo:

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

     Ejemplo de comando y resultado

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

6. Opcional: Revisa el esquema siguiendo el procedimiento Cómo ver una definición de esquema.

C#

Antes de probar este ejemplo, sigue las instrucciones de configuración para C# que encontrarás en la guía de inicio rápido de Gemini Enterprise sobre las bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Gemini Enterprise C#.

Para autenticarte en Gemini Enterprise, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

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

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que encontrarás en la guía de inicio rápido de Gemini Enterprise sobre las bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Gemini Enterprise Go.

Para autenticarte en Gemini Enterprise, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

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

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java que encontrarás en la guía de inicio rápido de Gemini Enterprise sobre las bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Gemini Enterprise Java.

Para autenticarte en Gemini Enterprise, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

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

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python que encontrarás en la guía de inicio rápido de Gemini Enterprise sobre las bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Gemini Enterprise Python.

Para autenticarte en Gemini Enterprise, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

# 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

Antes de probar este ejemplo, sigue las instrucciones de configuración para Ruby que encontrarás en la guía de inicio rápido de Gemini Enterprise sobre las bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Gemini Enterprise Ruby.

Para autenticarte en Gemini Enterprise, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

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

Requisitos y limitaciones

Cuando actualices un esquema, asegúrate de que el esquema nuevo sea retrocompatible con el esquema que estás actualizando. Para actualizar un esquema con uno nuevo que no sea retrocompatible, debes borrar todos los documentos del almacén de datos, borrar el esquema y crear uno nuevo.

La actualización de un esquema activa la reindexación de todos los documentos. La reindexación de un almacén de datos grande puede tardar horas o días.

Las actualizaciones del esquema no admiten lo siguiente:

• Cambiar el tipo de un campo Una actualización del esquema no admite el cambio del tipo de campo. Por ejemplo, un campo asociado a integer no se puede cambiar a string.
• Cómo quitar un campo Una vez que se define, no se puede quitar un campo. Puedes seguir agregando campos nuevos, pero no puedes quitar un campo existente.

Ejemplos de limitaciones (solo para REST)

En esta sección, se muestran ejemplos de tipos de actualizaciones de esquema válidos y no válidos. En estos ejemplos, se usa el siguiente esquema JSON de ejemplo:

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

Ejemplos de actualizaciones admitidas

Se admiten las siguientes actualizaciones del esquema de ejemplo.

• Se agrega un campo. En este ejemplo, se agregó el campo properties.uri al esquema.

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

• Agregar o quitar anotaciones de propiedad clave para title, description o uri En este ejemplo, se agregó keyPropertyMapping 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"
        }
      }
    }
  }
  

Ejemplos de actualizaciones de esquema no válidas

No se admiten las siguientes actualizaciones del esquema de ejemplo.

• Cambiar el tipo de un campo En este ejemplo, el tipo del campo title se cambió de cadena a número. Esta opción no es compatible.

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

• Cómo quitar un campo En este ejemplo, se quitó el campo title. Esta opción no es compatible.

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

¿Qué sigue?

• Cómo ver la definición del esquema para los datos estructurados
• Cómo borrar un esquema de datos estructurados
• Obtener una vista previa de los resultados de la búsqueda