Esta página foi traduzida pela API Cloud Translation.

Atualize um esquema

Pode atualizar o esquema de quaisquer dados que contenham dados que suportem um esquema, como dados estruturados, dados do Website com dados estruturados ou outros dados não estruturados com metadados.

Pode atualizar o esquema na Google Cloud consola ou através do método da API schemas.patch. A atualização do esquema de um Website só é suportada através da API REST.

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

Atualize o seu esquema

Pode atualizar o seu esquema na Google Cloud consola ou através da API.

Consola

Para atualizar um esquema na Google Cloud consola, siga estes passos:

Reveja a secção Requisitos e limitações para verificar se a atualização do esquema é válida.
Se estiver a atualizar anotações de campos (definindo campos como indexáveis, recuperáveis, dinamicamente segmentáveis, pesquisáveis ou preenchíveis), reveja o artigo Configurar definições de campos para conhecer as limitações e os requisitos de cada tipo de anotação.
Verifique se concluiu o carregamento de dados. Caso contrário, o esquema pode ainda não estar disponível para edição.
Na Google Cloud consola, aceda à página Aplicações de IA.

Aplicações de IA
No menu de navegação, clique em Armazenamentos de dados.
Na coluna Nome, clique no arquivo de dados com o esquema que quer atualizar.
Clique no separador Esquema para ver o esquema dos seus dados.

Este separador pode estar vazio se for a primeira vez que edita os campos.
Clique no botão Editar.
Atualize o seu esquema:
- Mapeie propriedades principais: na coluna Propriedades principais do seu esquema, selecione uma propriedade principal para mapear um campo. Por exemplo, se um campo denominado details contiver sempre a descrição de um documento, mapeie esse campo para a propriedade chave Description.
- Atualizar o número de dimensões (avançado): pode atualizar esta definição se estiver a usar incorporações de vetores personalizadas com a Vertex AI Search. Consulte a secção Avançado: use incorporações personalizadas.
- Atualizar anotações de campos: para atualizar as anotações de um campo, selecione ou desmarque a definição de anotação de um campo. As anotações disponíveis são Retrievable, Indexable, Dynamic Facetable, Searchable e Completable. Algumas definições de campos têm limitações. Consulte o artigo Configure as definições dos campos para ver descrições e requisitos para cada tipo de anotação.
- Adicione um novo campo: adicionar novos campos ao seu esquema antes de importar novos documentos com esses campos pode reduzir o tempo que o Vertex AI Search demora a reindexar os seus dados após a importação.
  1. Clique em Adicionar novos campos para expandir essa secção.
  2. Clique em add_box Adicionar nó e especifique as definições do novo campo.
    
    Para indicar uma matriz, defina Array como Yes. Por exemplo, para adicionar uma matriz de strings, defina type como string e Array como Yes.
    
    Para um índice da loja de dados de um Website, todos os campos que adicionar são matrizes por predefinição.
Clique em Guardar para aplicar as alterações ao esquema.

A alteração do esquema aciona a reindexação. Para grandes armazenamentos de dados, a reindexação pode demorar horas.

REST

Para usar a API para atualizar o seu esquema, siga estes passos:

Reveja as secções Requisitos e limitações e Exemplos de limitações (apenas REST) para verificar se as alterações ao esquema são válidas.

Para atualizar o esquema de arquivos de dados com Websites ou dados não estruturados com metadados, avance para o passo 5 para chamar o método schema.patch.
Se estiver a atualizar anotações de campos (definindo campos como indexáveis, recuperáveis, dinamicamente segmentáveis ou pesquisáveis), reveja o artigo Configurar definições de campos para conhecer as limitações e os requisitos de cada tipo de anotação.
Se estiver a editar um esquema detetado automaticamente, certifique-se de que concluiu a carregamento de dados. Caso contrário, o esquema pode ainda não estar disponível para edição.
Encontre o ID da loja de dados. Se já tiver o ID da loja de dados, avance para o passo seguinte.
1. Na Google Cloud consola, aceda à página Aplicações de IA e, no menu de navegação, clique em Armazenamentos de dados.
  
  Aceda à página Armazenamentos de dados
2. Clique no nome do arquivo de dados.
3. Na página Dados da sua loja de dados, obtenha o ID da loja de dados.

Use o método da 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 o seguinte:

PROJECT_ID: o ID do seu projeto Google Cloud .
DATA_STORE_ID: o ID do arquivo de dados do Vertex AI Search.

JSON_SCHEMA_OBJECT: o novo esquema JSON como um objeto JSON. Por 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"
}
}

Opcional: reveja o esquema seguindo o procedimento Veja uma definição de esquema.

C#

Para mais informações, consulte a documentação de referência da API C#Vertex AI Search.

Para se autenticar no Vertex AI Search, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

Para mais informações, consulte a documentação de referência da API GoVertex AI Search.


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

Para mais informações, consulte a documentação de referência da API JavaVertex AI Search.

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

Para mais informações, consulte a documentação de referência da API PythonVertex AI Search.

# 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

Para mais informações, consulte a documentação de referência da API RubyVertex AI Search.

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

Quando atualizar um esquema, certifique-se de que o novo esquema é retrocompatível com o esquema que está a atualizar. Para atualizar um esquema com um novo esquema que não seja retrocompatível, tem de eliminar todos os documentos no repositório de dados, eliminar o esquema e criar um novo esquema.

A atualização de um esquema aciona a reindexação de todos os documentos. Isto pode demorar algum tempo e incorrer em custos adicionais:

Hora. A reindexação de um grande repositório de dados pode demorar horas ou dias.
Despesa. A reindexação pode incorrer em custos, dependendo do analisador. Por exemplo, a reindexação de arquivos de dados que usam o analisador de OCR ou o analisador de esquemas incorre em custos. Para mais informações, consulte os preços das funcionalidades da IA Documentos.

As atualizações de esquemas não suportam o seguinte:

Alterar um tipo de campo. Uma atualização do esquema não suporta a alteração do tipo do campo. Por exemplo, não é possível alterar um campo mapeado para integer para string.
Remover um campo. Depois de definido, não é possível remover um campo. Pode continuar a adicionar novos campos, mas não pode remover um campo existente.

Exemplos de limitações (apenas REST)

Esta secção mostra exemplos de tipos de atualizações de esquemas válidos e inválidos. Estes exemplos usam o seguinte esquema JSON de exemplo:

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

São suportadas as seguintes atualizações ao esquema de exemplo.

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 propriedades principais 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 esquemas inválidas

As seguintes atualizações ao esquema de exemplo não são suportadas.

Alterar um tipo de campo. Neste exemplo, o tipo do campo title foi alterado de string para número. Esta opção não é suportada.

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

Remover um campo. Neste exemplo, o campo title foi removido. Esta opção não é suportada.

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