Atualizar um esquema

É possível atualizar os dados estruturados e não estruturados com metadados do esquema que oferecem suporte a um esquema.

É possível atualizar o esquema no Google Cloud console ou usando o schemas.patch método da API.

Para atualizar o esquema, adicione novos campos, mude as anotações indexáveis, pesquisáveis e recuperáveis de um campo ou marque um campo como uma propriedade de chave, como title, uri e description.

Importante: o Google recomenda que você atualize o esquema com mapeamentos de propriedades de chave, especialmente para title. Isso garante que os resultados sejam exibidos corretamente e ajuda o Gemini Enterprise a identificar informações importantes que permitem gerar resultados melhores.

Atualizar o esquema

É possível atualizar o esquema no Google Cloud console ou usando a API.

Observação: editar o esquema indexa o repositório de dados novamente. Para repositórios de dados grandes, a indexação pode levar várias horas.

Console

Para atualizar um esquema no Google Cloud console, siga estas etapas:

1. Revise a seção Requisitos e limitações para verificar se a atualização do esquema é válida.

2. Se você estiver atualizando anotações de campo (definindo campos como indexáveis, recuperáveis, facetáveis dinâmicos, pesquisáveis ou completáveis), revise Configurar as definições de campo para conferir as limitações e os requisitos de cada tipo de anotação.

3. Verifique se você concluiu a ingestão de dados. Caso contrário, o esquema ainda não estará disponível para edição.

4. No Google Cloud console, acesse a página Gemini Enterprise.

   Gemini Enterprise

5. No menu de navegação, selecione Repositório de dados.

6. Na coluna Nome, clique no repositório de dados com o esquema que você quer atualizar.

7. Clique na guia Esquema para conferir o esquema dos seus dados.

   Essa guia poderá estar vazia se for a primeira vez que você edita os campos.

8. Clique no botão Editar.

9. Atualize o esquema:

   • Mapear propriedades de chave:na coluna Propriedades de chave do esquema, selecione uma propriedade de chave para mapear um campo. Por exemplo, se um campo chamado details sempre contiver a descrição de um documento, mapeie esse campo para a propriedade de chave Descrição.

   • Atualizar o número de dimensões (avançado): você pode atualizar essa configuração se estiver usando embeddings de vetor personalizados com o Gemini Enterprise. Consulte Usar embeddings personalizados em a documentação da Vertex AI Search.

   • Atualizar anotações de campo: para atualizar as anotações de um campo, selecione ou desmarque a configuração de anotação de um campo. As anotações disponíveis são Recuperável, Indexável, Facetável dinâmico, Pesquisável e Completável. Algumas configurações de campo têm limitações. Consulte Configurar as definições de campo para conferir as descrições e os requisitos de cada tipo de anotação.

   • Adicionar um novo campo: adicionar novos campos ao esquema antes de importar novos documentos com esses campos pode reduzir o tempo necessário para o Gemini Enterprise reindexar seus dados após a importação.

     1. Clique em Adicionar novos campos para abrir essa seção.

     2. Clique em add_box Adicionar nó e especifique as configurações do novo campo.

        Para indicar uma matriz, defina Matriz como Sim. Por exemplo, para adicionar uma matriz de strings, defina tipo como string e Matriz como Yes.

10. Clique em Salvar para aplicar as mudanças do esquema.

    A mudança do esquema aciona a reindexação. Para repositórios de dados grandes, a reindexação pode levar horas.

REST

Para usar a API para atualizar o esquema, siga estas etapas:

1. Revise as seções Requisitos e limitações e Exemplos de limitações (somente REST) para verificar se as mudanças do esquema são válidas.

   Para atualizar o esquema de repositórios de dados não estruturados com metadados, pule para a etapa 5 para chamar o método schema.patch.

2. Se você estiver atualizando anotações de campo (definindo campos como indexáveis, recuperáveis, facetáveis dinâmicos ou pesquisáveis), revise Configurar as definições de campo para conferir as limitações e os requisitos de cada tipo de anotação.

3. Se você estiver editando um esquema detectado automaticamente, verifique se concluiu a ingestão de dados. Caso contrário, o esquema ainda não estará disponível para edição.

4. Encontre o ID do repositório de dados. Se você já tiver o ID do repositório de dados, pule para a próxima etapa.

   1. No Google Cloud console, acesse a página Gemini Enterprise e no menu de navegação, clique em Repositórios de dados.

      Acessar a página Repositórios de dados

   2. Clique no nome do seu repositório de dados.

   3. Na página Dados do seu repositório de dados, encontre o ID do repositório.

5. Use o método da API schemas.patch para fornecer seu novo esquema JSON como um 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
   }'
   

   Substitua:

   • PROJECT_ID: ID do projeto.
   • DATA_STORE_ID: ID do repositório de dados.

   • JSON_SCHEMA_OBJECT: seu novo esquema JSON como um objeto JSON. Exemplo:

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

     Exemplo de comando e 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: revise o esquema seguindo o procedimento Conferir uma definição de esquema.

C#

Antes de testar este exemplo, siga as instruções de configuração do C# no guia de início rápido do Gemini Enterprise: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Gemini Enterprise.C#

Para autenticar no Gemini Enterprise, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 testar este exemplo, siga as instruções de configuração do Go no guia de início rápido do Gemini Enterprise: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Gemini Enterprise.Go

Para autenticar no Gemini Enterprise, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 testar este exemplo, siga as instruções de configuração Java no guia de início rápido do Gemini Enterprise: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java do Gemini Enterprise.

Para autenticar no Gemini Enterprise, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 testar este exemplo, siga as instruções de configuração Python no guia de início rápido do Gemini Enterprise: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Python do Gemini Enterprise.

Para autenticar no Gemini Enterprise, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 testar este exemplo, siga as instruções de configuração do Ruby no guia de início rápido do Gemini Enterprise: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Gemini Enterprise Ruby.

Para autenticar no Gemini Enterprise, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 e limitações

Ao atualizar um esquema, verifique se o novo esquema é compatível com versões anteriores do que você está atualizando. Para atualizar um esquema com um novo esquema que não seja compatível com versões anteriores, é necessário excluir todos os documentos no repositório de dados, excluir o esquema e criar um novo.

A atualização de um esquema aciona a reindexação de todos os documentos. A reindexação de um repositório de dados grande pode levar horas ou dias.

As atualizações de esquema não oferecem suporte ao seguinte:

• Mudança de um tipo de campo. Uma atualização de esquema não oferece suporte à mudança do tipo de campo. Por exemplo, um campo mapeado para integer não pode ser alterado para string.
• Remoção de um campo. Depois de definido, um campo não pode ser removido. É possível continuar adicionando novos campos, mas não é possível remover um campo atual.

Exemplos de limitações (somente REST)

Esta seção mostra exemplos de tipos válidos e inválidos de atualizações de esquema. Esses exemplos usam o seguinte esquema JSON:

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

Exemplos de atualizações com suporte

As seguintes atualizações do esquema de exemplo são aceitas.

• Adicionar um campo. Neste exemplo, o campo properties.uri foi adicionado ao 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"
        }
      }
    }
  }
  

• Adicionar ou remover anotações de propriedade de chave para title, description ou uri. Neste exemplo, keyPropertyMapping foi adicionado ao 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"
        }
      }
    }
  }
  

Exemplos de atualizações de esquema inválidas

As seguintes atualizações do esquema de exemplo não são aceitas.

• Mudança de um tipo de campo. Neste exemplo, o tipo do campo title foi alterado de string para número. Isso não é aceito.

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

• Remoção de um campo. Neste exemplo, o campo title foi removido. Isso não é aceito.

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

A seguir

• Conferir a definição de esquema para dados estruturados
• Excluir um esquema para dados estruturados
• Visualizar os resultados da pesquisa