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 as aplicações de IA demoram 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 de armazenamento de dados de Websites, 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 Configure as definições dos 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 do armazenamento 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 seu 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# de aplicações de IA.

Para se autenticar em aplicações de IA, 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 Go de aplicações de IA.


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 Java de aplicações de IA.

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 Python de aplicações de IA.

# 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 Ruby de aplicações de IA.

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 gerar 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 Documental.

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