Nomes de atributos de expressão no DynamoDB

Um nome de atributo de expressão é um espaço reservado usado em uma expressão do Amazon DynamoDB como alternativa ao nome de atributo real. Um nome de atributo de expressão deve começar com um sinal de cerquilha (#) seguido de um ou mais caracteres alfanuméricos e do caractere sublinhado (_).

Esta seção descreve várias situações em que você precisa usar nomes de atributos de expressão.

nota

Os exemplos nesta seção usam o AWS Command Line Interface (AWS CLI). Para ver exemplos de código específicos de linguagem de programação, consulte Conceitos básicos do DynamoDB e dos SDKs da AWS.

Palavras reservadas

Algumas vezes, pode ser necessário escrever uma expressão que contém um nome de atributo que está em conflito com uma palavra reservada do DynamoDB. (Para obter uma lista completa de palavras reservadas, consulte Palavras reservadas no DynamoDB.)

Por exemplo, o AWS CLI exemplo a seguir falharia porque COMMENT é uma palavra reservada.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"123"}}' \
    --projection-expression "Comment"

Para resolver esse problema, substitua Comment por um nome de atributo de expressão, como #c. A # (cerquilha) é obrigatória e indica que esse é um espaço reservado para um nome de atributo. O AWS CLI exemplo agora teria a seguinte aparência.

aws dynamodb get-item \
     --table-name ProductCatalog \
     --key '{"Id":{"N":"123"}}' \
     --projection-expression "#c" \
     --expression-attribute-names '{"#c":"Comment"}'

nota

Se o nome de um atributo começar com um número, contiver um espaço ou incluir uma palavra reservada, você deverá usar um nome de atributo de expressão para substituir esse nome de atributo na expressão.

Nomes de atributos com caracteres especiais

Em uma expressão, um ponto (“.”) é interpretado como um caractere de separação em um caminho de documento. No entanto, o DynamoDB também permite que você use um ponto e outros caracteres especiais, como um hífen (“-”) como parte do nome de um atributo. Isso pode ser ambíguo em alguns casos. Para ilustrar, vamos supor que você queira recuperar o atributo Safety.Warning de um item do ProductCatalog (consulte Especificar atributos de item ao usar expressões).

Suponha que você queira acessar Safety.Warning usando uma expressão de projeção.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"123"}}' \
    --projection-expression "Safety.Warning"

O DynamoDB retorna um resultado vazio, em vez da string esperada (“Always wear a helmet”). Isso ocorre porque o DynamoDB interpreta um ponto em uma expressão como um separador de caminho de documento. Neste caso, defina um nome de atributo de expressão (por exemplo, #sw) como um substituto para Safety.Warning. Você poderia usar a seguinte expressão de projeção.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"123"}}' \
    --projection-expression "#sw" \
    --expression-attribute-names '{"#sw":"Safety.Warning"}'

Em seguida, o DynamoDB deverá retornar o resultado correto.

nota

Se o nome de um atributo contiver um ponto (“.”) ou um hífen (“-”), você deverá usar um nome de atributo de expressão para substituir o nome desse atributo na expressão.

Atributos aninhados

Suponha que você queira acessar o atributo aninhado ProductReviews.OneStar usando a seguinte expressão de projeção.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"123"}}' \
    --projection-expression "ProductReviews.OneStar"

O resultado deveria conter todas as avaliações de produto de uma estrela, que é o esperado.

Mas e se você decidiu usar um nome de atributo de expressão em vez disso? Por exemplo, o que aconteceria se você definisse #pr1star como um substituto para ProductReviews.OneStar?

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"123"}}' \
    --projection-expression "#pr1star"  \
    --expression-attribute-names '{"#pr1star":"ProductReviews.OneStar"}'

O DynamoDB retornaria um resultado vazio, em vez do mapa esperado de revisões de uma estrela. Isso ocorre porque o DynamoDB interpreta um ponto no nome de atributo de expressão como um caractere no nome de um atributo. Quando o DynamoDB avalia o nome de atributo de expressão #pr1star, ele determina que ProductReviews.OneStar se refere a um atributo escalar, o que não era pretendido.

A abordagem correta seria definir um nome de atributo de expressão para cada elemento no caminho do documento:

• #pr — ProductReviews

• #1star — OneStar

Você poderia usar #pr.#1star para a expressão de projeção.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"123"}}' \
    --projection-expression "#pr.#1star"  \
    --expression-attribute-names '{"#pr":"ProductReviews", "#1star":"OneStar"}'

Em seguida, o DynamoDB deverá retornar o resultado correto.

Nomes de atributo repetidos

Os nomes de atributo de expressão são úteis quando você precisa consultar o mesmo nome de atributo repetidamente. Por exemplo, considere a seguinte expressão para recuperar algumas das revisões de um item do ProductCatalog.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"123"}}' \
    --projection-expression "ProductReviews.FiveStar, ProductReviews.ThreeStar, ProductReviews.OneStar"

Para tornar isso mais conciso, você pode substituir ProductReviews por um nome de atributo de expressão, como #pr. A expressão revisada agora teria a seguinte aparência.

• #pr.FiveStar, #pr.ThreeStar, #pr.OneStar

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"123"}}' \
    --projection-expression "#pr.FiveStar, #pr.ThreeStar, #pr.OneStar" \
    --expression-attribute-names '{"#pr":"ProductReviews"}'

Caso defina um nome de atributo de expressão, você deverá usá-lo de forma consistente na expressão inteira. Além disso, não é possível omitir o símbolo #.