Atualizar um esquema

É possível atualizar os dados estruturados e os dados não estruturados com metadados que são compatíveis com um esquema.

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

Para atualizar o esquema, é possível adicionar novos campos, mudar as anotações indexáveis, pesquisáveis e recuperáveis de um campo ou marcar um campo como uma propriedade de chave, como title, uri e description.

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

Atualizar o esquema

É possível atualizar o esquema no console do Google Cloud 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 console do Google Cloud , siga estas etapas:

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

2. Se você estiver atualizando as anotações de campo (definindo campos como indexáveis, recuperáveis, com tabelas dinâmicas, pesquisáveis ou completáveis), consulte Definir configurações de campo para saber 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, talvez o esquema ainda não esteja disponível para edição.

4. No console Google Cloud , 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 pode 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 tiver 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): é possível atualizar essa configuração se você estiver usando embeddings de vetor personalizados com o Gemini Enterprise. Consulte Usar embeddings personalizados na documentação do Agent Search.

   • Atualizar as anotações de campo: para atualizar as anotações de um campo, marque ou desmarque a configuração de anotação de um campo. As anotações disponíveis são Recuperável, Indexável, Tabela dinâmica, Pesquisável e Concluível. Algumas configurações de campo têm limitações. Consulte Definir as configurações de campo para ver 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 que o Gemini Enterprise leva para reindexar seus dados após a importação.

     1. Clique em Adicionar novos campos para abrir a 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 type como string e Array como Yes.

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

    A alteração 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 seu esquema, siga estas etapas:

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

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

2. Se você estiver atualizando as anotações de campo (definindo campos como indexáveis, recuperáveis, pesquisáveis ou com tabelas dinâmicas), consulte Definir configurações de campo para ver 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, talvez o esquema ainda não esteja disponível para edição.

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

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

      Acesse a página Repositório 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 de API schemas.patch para fornecer o 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: o ID do repositório de dados.

   • JSON_SCHEMA_OBJECT: o 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 Ver 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 Gemini Enterprise C#.

Para se autenticar no Gemini Enterprise, configure o Application Default Credentials. Para 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 Gemini Enterprise Go.

Para se autenticar no Gemini Enterprise, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

//go:build examples

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 do 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 Gemini Enterprise Java.

Para se autenticar no Gemini Enterprise, configure o Application Default Credentials. Para 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 do 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 Gemini Enterprise Python.

Para se autenticar no Gemini Enterprise, configure o Application Default Credentials. Para 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 se autenticar no Gemini Enterprise, configure o Application Default Credentials. Para 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, exclua todos os documentos no repositório de dados, exclua o esquema e crie 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 são compatíveis com o seguinte:

• Mudança de um tipo de campo. Uma atualização de esquema não permite alterar o tipo do campo. Por exemplo, um campo associado a integer não pode ser alterado para string.
• Remoção de um campo. Depois de definido, um campo não pode ser removido. Você pode continuar adicionando novos campos, mas não pode remover um atual.

Exemplos de limitação (somente REST)

Nesta seção, mostramos exemplos de tipos válidos e inválidos de atualizações de esquema. Estes exemplos usam o seguinte exemplo de 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 aceitas

As seguintes atualizações no esquema de exemplo são compatíveis.

• 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 atualizações a seguir no esquema de exemplo não são compatíveis.

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

    {
      "$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. Essa opção não é aceita.

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

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