Gerenciamento de índices

Esta seção descreve como criar, descrever e eliminar índices no Amazon QLDB. A cota para o número de índices por tabela que você pode criar é definida em Cotas e limites no Amazon QLDB.

Criar índices

Conforme também descrito em Criar tabelas e índices, você pode usar a instrução CREATE INDEX para criar um índice em uma tabela para um campo de nível superior especificado, da seguinte maneira. O nome da tabela e o nome do campo indexado diferenciam maiúsculas de minúsculas.

CREATE INDEX ON VehicleRegistration (VIN)

CREATE INDEX ON VehicleRegistration (LicensePlateNumber)

Cada índice que você cria em um ledger do Amazon QLDB tem uma ID exclusiva atribuída pelo sistema. Para encontrar esse ID de índice, consulte a seção Descrever índices a seguir.

Importante

O QLDB requer um índice para pesquisar um documento com eficiência. Sem um índice, o QLDB precisa fazer uma verificação da tabela completa ao ler documentos. Isso pode causar problemas de desempenho em tabelas grandes, incluindo conflitos de simultaneidade e tempos limite de transação.

Para evitar verificações de tabelas, você deve executar instruções com uma cláusula de predicado WHERE usando um operador de igualdade (= ou IN) em um campo indexado ou em uma ID de documento. Para obter mais informações, consulte Otimizar a performance da consulta.

Observe as seguintes restrições ao criar índices:

• Um índice só pode ser criado em um único campo de nível superior. Não há suporte para índices compostos, aninhados, exclusivos e baseados em funções.

• Você pode criar um índice em qualquer tipo de dados Ion, incluindo list e struct. No entanto, você só pode fazer a pesquisa indexada pela igualdade de todo o valor de Ion, independentemente do tipo de Ion. Por exemplo, ao usar um tipo list como índice, você não pode fazer uma pesquisa indexada por um item dentro da lista.

• O desempenho da consulta é aprimorado somente quando você usa um predicado de igualdade; por exemplo, WHERE indexedField = 123 ou WHERE indexedField IN (456, 789).

  O QLDB não respeita as desigualdades nos predicados de consulta. Como resultado, as verificações filtradas por intervalo não são implementadas.

• Os nomes dos campos indexados diferenciam maiúsculas e minúsculas e podem ter no máximo 128 caracteres.

• A criação do índice no QLDB é assíncrona. O tempo necessário para concluir a criação de um índice em uma tabela não vazia varia dependendo do tamanho da tabela. Para obter mais informações, consulte Gerenciamento de índices.

Descrever índices

A criação do índice no QLDB é assíncrona. O tempo necessário para concluir a criação de um índice em uma tabela não vazia varia dependendo do tamanho da tabela. Para verificar o status de uma criação de índice, você pode consultar a tabela do catálogo do sistema information_schema.user_tables.

Por exemplo, a instrução a seguir consulta o catálogo do sistema para todos os índices na tabela VehicleRegistration.

SELECT VALUE indexes
FROM information_schema.user_tables info, info.indexes indexes
WHERE info.name = 'VehicleRegistration'

{
    indexId: "Djg2nt0yIs2GY0T29Kud1z",
    expr: "[VIN]",
    status: "ONLINE"
},
{
    indexId: "4tPW3fUhaVhDinRgKRLhGU",
    expr: "[LicensePlateNumber]",
    status: "FAILED",
    message: "aws.ledger.errors.InvalidEntityError: Document contains multiple values for indexed field: LicensePlateNumber"
}

campos de índice

• indexId – O ID exclusivo do índice.

• expr — O caminho do documento indexado. Esse campo é uma string no formato: [fieldName].

• status – O status atual do índice. O status de um índice pode ser um dos valores a seguir:

  • BUILDING— Está construindo ativamente o índice para a tabela.

  • FINALIZING— Concluiu a construção do índice e está começando a ativá-lo para uso.

  • ONLINE— Está ativo e pronto para uso em consultas. O QLDB não usa o índice em consultas até que o status seja online.

  • FAILED— Não é possível criar o índice devido a um erro irrecuperável. Os índices nesse estado ainda contam para sua cota de índices por tabela. Para obter mais informações, consulte Erros comuns.

  • DELETING— Está excluindo ativamente o índice depois que um usuário o excluiu.

• message— A mensagem de erro que descreve o motivo pelo qual o índice tem um status FAILED. Esse campo só é incluído para índices com falha.

Usar o console

Você também pode usar o AWS Management Console para conferir o status de um índice.

Como verificar o status de um índice (console)

1. Faça login no AWS Management Console e abra o console do Amazon QLDB em https://console.aws.amazon.com/qldb.

2. No painel de navegação, escolha Ledgers.

3. Na lista Ledgers, escolha o nome do ledger cujos índices você deseja gerenciar.

4. Na página de detalhes do ledger, na guia Tabelas, escolha o nome da tabela cujo índice você deseja verificar.

5. Na página de detalhes da tabela, localize o cartão Campos indexados. A coluna Status do índice exibe o status atual de cada índice na tabela.

Reduzindo índices

Use a instrução DROP INDEX para eliminar um índice. Quando você descarta um índice, ele é excluído permanentemente da tabela.

Primeiro, encontre o ID da tabela em information_schema.user_tables. Por exemplo, a consulta a seguir retorna o indexId do campo LicensePlateNumber indexado na tabela VehicleRegistration.

SELECT indexes.indexId
FROM information_schema.user_tables info, info.indexes indexes
WHERE info.name = 'VehicleRegistration' and indexes.expr = '[LicensePlateNumber]'

Em seguida, use esse ID para eliminar o índice. Veja a seguir um exemplo que revela o ID do índice 4tPW3fUhaVhDinRgKRLhGU. O ID do índice é um identificador exclusivo que você coloca entre aspas duplas.

DROP INDEX "4tPW3fUhaVhDinRgKRLhGU" ON VehicleRegistration WITH (purge = true)

nota

A cláusula WITH (purge = true) é obrigatória para todas as instruções DROP INDEX e atualmente true é o único valor suportado.

A palavra-chave purge diferencia maiúsculas e minúsculas e deve ser toda em minúsculas.

Usar o console

Você também pode usar o AWS Management Console para remover um índice.

Para eliminar um índice (console)

1. Faça login no AWS Management Console e abra o console do Amazon QLDB em https://console.aws.amazon.com/qldb.

2. No painel de navegação, escolha Ledgers.

3. Na lista Ledgers, escolha o nome do ledger cujos índices você deseja gerenciar.

4. Na página de detalhes do ledger, na guia Tabelas, escolha o nome da tabela cujo índice você deseja verificar.

5. Na página de detalhes da tabela, localize o cartão Campos indexados. Selecione o índice que você deseja eliminar e escolha Eliminar índice.

Erros comuns

Esta seção descreve erros comuns que você pode encontrar ao criar índices e sugere possíveis soluções.

nota

Os índices com status de FAILED ainda contam para sua cota de índices por tabela. Um índice com falha também impede que você modifique ou exclua qualquer documento que tenha causado a falha na criação do índice na tabela.

Você deve eliminar explicitamente o índice para removê-lo da cota.

O documento contém vários valores para o campo indexado: FieldName.

O QLDB não consegue criar um índice para o nome do campo especificado porque a tabela contém um documento com vários valores para o mesmo campo (ou seja, nomes de campo duplicados).

Você deve primeiro eliminar o índice com falha. Em seguida, certifique-se de que todos os documentos na tabela tenham somente um valor para cada nome de campo antes de tentar criar o índice novamente. Você também pode criar um índice para outro campo que não tenha duplicatas.

O QLDB também retornará esse erro se você tentar inserir um documento que contém vários valores para um campo que já está indexado na tabela.

Limite de índices excedido: o tableName da tabela já tem n índices e não pode criar mais.

O QLDB impõe um limite de cinco índices por tabela, incluindo índices com falha. Você deve eliminar um índice existente antes de criar um novo.

Nenhum índice definido com identificador: indexId.

Você tentou eliminar um índice que não existe para a combinação especificada de tabela e ID de índice. Para saber como verificar os índices existentes, consulte Descrever índices.