# DynamoDB

O conector **DynamoDB** permite que pipelines realizem operações em tabelas DynamoDB na AWS. Atualmente, estão disponíveis as seguintes operações:

* **PutItem:** cria ou substitui um item em uma tabela DynamoDB.
* **GetItem:** busca atributos de um item existente em uma tabela DynamoDB pela chave primária.
* **UpdateItem:** edita os atributos de um item existente ou adiciona um item novo a uma tabela DynamoDB.
* **DeleteItem:** remove um único item em uma tabela pela chave primária.
* **Query:** busca todos os itens com a mesma chave de partição (*partition key*) de uma tabela ou índice (secundário local ou secundário global).
* **Scan:** busca todos os itens de uma tabela ou índice (secundário local ou secundário global). Uma expressão de filtro pode ser aplicada para limitar o número de itens retornados.

## Parâmetros

Os parâmetros disponíveis estão divididos em quatro abas e podem variar de acordo com a operação selecionada. Parâmetros suportados por [expressões Double Braces](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/overview) estão marcados com `(DB)`.

### **Aba General**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Fail On Error</strong></td><td>Se a opção estiver ativada, a execução do pipeline com um erro será interrompida. Do contrário, a execução do pipeline será mantida, mas o resultado mostrará um valor falso para a propriedade <code>"success"</code>.</td><td>False</td><td>Booleano</td></tr></tbody></table>

### **Aba Authentication**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Account Type</strong></td><td>Especifica o tipo de conta da conta principal usada para a conexão. Tipos suportados: <strong>AWS V4</strong> e <strong>Basic</strong>.</td><td>Basic</td><td>String</td></tr><tr><td><strong>Use Dynamic Account</strong></td><td>Quando ativo, o conector usará a conta dinamicamente. Caso contrário, usará a conta de forma estática.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Scoped</strong></td><td><p>Quando ativo, a conta armazenada fica isolada de outros subprocessos. Nesse caso, os subprocessos veem sua própria versão dos dados da conta armazenada. </p><p>Este parâmetro fica disponível apenas se o parâmetro <strong>Use Dynamic Account</strong> estiver ativo.</p></td><td>False</td><td>Booleano</td></tr><tr><td><strong>Account</strong></td><td><p>A conta usada para conectar o conector à tabela alvo do DynamoDB. </p><p>Este parâmetro fica disponível apenas se o parâmetro <strong>Use Dynamic Account</strong> estiver inativo.</p></td><td>NULL</td><td>BASIC, AWS-V4</td></tr><tr><td><strong>Account Name</strong> <code>(DB)</code></td><td><p>O nome da conta dinâmica usada para conectar o conector à tabela alvo do DynamoDB. Esta conta deve ter sido previamente configurada em um conector <a href="../tools/store-account"><strong>Store Account</strong></a> no pipeline para que este processo tenha efeito. </p><p>Este parâmetro fica disponível apenas se o parâmetro <strong>Use Dynamic Account</strong> estiver ativo.</p></td><td>Vazio</td><td>String</td></tr><tr><td><strong>AWS Region</strong></td><td><p>A região da AWS onde a tabela alvo está disponível. </p><p>É usada apenas quando o tipo de conta está configurado como <strong>Basic</strong>.</p></td><td>us-east-1</td><td>String</td></tr><tr><td><strong>Use Assume Role</strong></td><td><p>Quando ativo, permite o uso de uma conta <strong>AWS Role</strong> a ser assumida pela <strong>Account</strong>. </p><p>Só pode ser usado se o tipo de conta estiver configurado como <strong>AWS V4</strong>.</p></td><td><em>False</em></td><td>Booleano</td></tr><tr><td><strong>AWS Role Account</strong></td><td>A conta usada para delegar permissões temporárias à <strong>Account</strong> por meio da operação <strong>Assume Role</strong>.</td><td>NULL</td><td>AWS-ROLE</td></tr><tr><td><strong>AWS Role Account Name</strong> <code>(DB)</code></td><td><p>O nome da conta dinâmica usada para delegar permissões temporárias à conta referenciada no campo <strong>Account Name</strong> por meio da operação <strong>Assume Role</strong>. </p><p>Este parâmetro fica disponível apenas se o parâmetro <strong>Use Dynamic Account</strong> estiver ativo.</p></td><td>Vazio</td><td>String</td></tr></tbody></table>

### **Aba Operation Settings**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Operation</strong></td><td>Operação a ser realizada.</td><td>PutItem</td><td>String</td></tr><tr><td><strong>Table Name</strong></td><td>Nome da tabela na qual a operação será realizada.</td><td>NULL</td><td>String</td></tr></tbody></table>

#### **Parâmetros da operação PutItem**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Upsert</strong></td><td>Quando ativado, o parâmetro substitui completamente um item existente com a mesma chave primária. Do contrário, a operação irá falhar quando um item com a chave primária especificada já existir.</td><td>True</td><td>Booleano</td></tr><tr><td><strong>Body</strong> <code>(DB)</code></td><td><p>Objeto JSON a ser usado pela operação.</p><p><em>Arrays</em> JSON e outras definições válidas de JSON não são permitidas.</p></td><td>{{ message.$ }}</td><td>JSON</td></tr></tbody></table>

#### **Parâmetros da operação GetItem**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Partition Key Value</strong> <code>(DB)</code></td><td>Valor da chave de partição (<em>partition key</em>) do item de destino. Este parâmetro é obrigatório.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Sort Key Value</strong> <code>(DB)</code></td><td>Valor da chave de classificação (<em>sort key</em>) do item de destino. É necessária somente quando a tabela de destino usa uma chave primária composta (chave de partição + chave de classificação).</td><td>NULL</td><td>String</td></tr><tr><td><strong>Attributes to Return</strong> <code>(DB)</code></td><td>Lista de nomes de atributos separados por vírgula a serem retornados pela operação.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Consistent Read</strong></td><td>Este parâmetro se sobrepõe ao comportamento padrão de consistência eventual do DynamoDB quando ativado.</td><td>False</td><td>Booleano</td></tr></tbody></table>

#### **Parâmetros da operação UpdateItem**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Partition Key Value</strong> <code>(DB)</code></td><td>Valor da chave de partição do item de destino. Este parâmetro é obrigatório.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Sort Key Value</strong> <code>(DB)</code></td><td>Valor da chave de classificação do item de destino. É necessária somente quando a tabela de destino usa uma chave primária composta (chave de partição + chave de classificação).</td><td>NULL</td><td>String</td></tr><tr><td><strong>Return Values</strong></td><td><p>Lista de opções para obter os valores dos atributos, antes ou depois da operação de atualização ser realizada.</p><p></p><p>As opções são: ALL NEW (Retorna todos os valores como estão, após atualizar), ALL OLD (Todos os valores como estavam antes de atualizar), NONE (Nada é retornado),  UPDATED NEW (Somente valores atualizados são retornados como estão após atualizar), e UPDATED OLD (Somente valores atualizados como estavam antes de atualizar).</p></td><td>NONE</td><td>String</td></tr><tr><td><strong>Body</strong> <code>(DB)</code></td><td><p>Objeto JSON a ser usado pela operação.</p><p>Arrays JSON e outras definições válidas de JSON não são permitidas.</p></td><td>{{ message.$ }}</td><td>JSON</td></tr></tbody></table>

#### **Parâmetros da operação DeleteItem**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Partition Key Value</strong> <code>(DB)</code></td><td>Valor da chave de partição do item de destino. Este parâmetro é obrigatório.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Sort Key Value</strong> <code>(DB)</code></td><td>Valor da chave de classificação do item de destino. É necessária somente quando a tabela de destino usa uma chave primária composta (chave de partição + chave de classificação).</td><td>NULL</td><td>String</td></tr></tbody></table>

#### **Parâmetros da operação Query**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Index Name</strong></td><td>Nome do índice a ser usado nesta operação. O índice deve pertencer à tabela especificada no campo <strong>Table Name</strong>.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Partition Key Value</strong> <code>(DB)</code></td><td>Valor da chave de partição do item de destino. Este valor irá se referir a um índice da chave de partição (<em>Index Partition Key</em>), se o campo <strong>Index Name</strong> estiver especificado. Este parâmetro é obrigatório.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Sort Key Expression</strong> <code>(DB)</code></td><td>Uma expressão condicional a ser aplicada ao atributo da chave de classicação. A expressão irá se referir a um índice da chave de classificação (<em>Index Sort Key</em>), se o campo <strong>Index Name</strong> estiver especificado.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Attributes to Return</strong> <code>(DB)</code></td><td>Lista de nomes de atributos a serem retornados pela operação.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Consistent Read</strong></td><td>Este parâmetro se sobrepõe ao comportamento padrão de consistência eventual do DynamoDB quando ativado. Não pode ser usado quando a operação <strong>Query</strong> é usada contra um índice secundário global (GSI).</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Filter Expression</strong> <code>(DB)</code></td><td>Uma <em>string</em> que contém condições que o DynamoDB aplica após a operação <strong>Query</strong>, mas antes dos dados serem retornados para você.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Exclusive Start Partition Key Value</strong> <code>(DB)</code></td><td>A chave de partição do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Exclusive Start Sort Key Value</strong> <code>(DB)</code></td><td>A chave de classiicação do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Exclusive Start Index Partition Key Value</strong> <code>(DB)</code></td><td>A chave de partição do índice do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados de um índice.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Exclusive Start Index Sort Key Value</strong> <code>(DB)</code></td><td>A chave de classificação do índice do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados de um índice.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Limit</strong></td><td>O número máximo de itens a serem retornados pela operação. O valor mínimo permitido é 1 e o máximo é 1000.</td><td>1000</td><td>Inteiro</td></tr><tr><td><strong>Automatic Pagination</strong></td><td>Se ativo, este parâmetro irá buscar automaticamente todas as páginas quando o DynamoDB retornar respostas paginadas.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Scan Forward</strong></td><td>Se ativo, este parâmetro retorna o resultado em sua ordem original (baseado na chave de classificação). Do contrário, a ordem é invertida.</td><td>True</td><td>Booleano</td></tr><tr><td><strong>Expression Attribute Values</strong> <code>(DB)</code></td><td>Uma lista de valores de atributos usados nos campos de expressão condicional (<strong>Sort Key Expression</strong> e <strong>Filter Expression</strong>). Cada valor de atributo deve especificar o <em>placeholder</em> usado (<strong>Placeholder</strong>), o tipo de dado (<strong>Type</strong>) e o valor (<strong>Value</strong>) para substituir o <em>placeholder</em>.</td><td>Vazio</td><td>Lista de valores de atributos</td></tr></tbody></table>

#### **Parâmetros da operação Scan**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Index Name</strong></td><td>Nome do índice a ser usado nesta operação. O índice deve pertencer à tabela especificada no campo <strong>Table Name</strong>.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Attributes to Return</strong> <code>(DB)</code></td><td>Lista de nomes de atributos a serem retornados pela operação.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Consistent Read</strong></td><td>Este parâmetro se sobrepõe ao comportamento padrão de consistência eventual do DynamoDB quando ativado. Não pode ser usado quando a operação <strong>Scan</strong> é usada contra um índice secundário global (GSI).</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Filter Expression</strong> <code>(DB)</code></td><td>Uma <em>string</em> que contém condições que o DynamoDB aplica após a operação <strong>Scan</strong>, mas antes dos dados serem retornados para você.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Exclusive Start Partition Key Value</strong> <code>(DB)</code></td><td>A chave de partição do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Exclusive Start Sort Key Value</strong> <code>(DB)</code></td><td>A chave de classiicação do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Exclusive Start Index Partition Key Value</strong> <code>(DB)</code></td><td>A chave de partição do índice do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados de um índice.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Exclusive Start Index Sort Key Value</strong> <code>(DB)</code></td><td>A chave de classificação do índice do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados de um índice.</td><td>NULL</td><td>String</td></tr><tr><td><strong>Limit</strong></td><td>O número máximo de itens a serem retornados pela operação. O valor mínimo permitido é 1 e o máximo é 1000.</td><td>1000</td><td>Inteiro</td></tr><tr><td><strong>Automatic Pagination</strong></td><td>Se ativo, este parâmetro irá buscar automaticamente todas as páginas quando o DynamoDB retornar respostas paginadas.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Scan Forward</strong></td><td>Se ativo, este parâmetro retorna o resultado em sua ordem original (baseado na chave de classificação). Do contrário, a ordem é invertida.</td><td>True</td><td>Booleano</td></tr><tr><td><strong>Expression Attribute Values</strong> <code>(DB)</code></td><td>Uma lista de valores de atributos usados nos campos de expressão condicional (<strong>Filter Expression</strong>). Cada valor de atributo deve especificar o <em>placeholder</em> usado (<strong>Placeholder</strong>), o tipo de dado (<strong>Type</strong>) e o valor (<strong>Value</strong>) para substituir o <em>placeholder</em>.</td><td>Vazio</td><td>Lista de valores de atributos</td></tr></tbody></table>

## Saída

Todas as operações retornam:

* Um atributo booleano `"success"` para indicar se a operação foi realizada com sucesso (true) ou se falhou (false).
* Um atributo de contagem, indicando quantos itens foram afetados pela operação. Este parâmetro recebe o nome da operação no seguinte formato: `operation's name + Count`.
* Um atributo `"data"` contendo um array de registros de itens retornados. Isto é restrito às operações que retornam algum resultado.

### **Exemplo GetItem**

```
{
	"success": true,
	"getItemCount": 1,
	"data": [
		{
	"Age": 8,
	"Colors": [
		"White", 
		"Brown",
		"Black"
],
"Name": "Fido",
"Vaccinations": {
	"Rabies": [
		"2009-03-17",
		"2011-09-21",
		"2014-07-08"
	],
	"Distemper": "2015-10-13"
},
"Breed": "Beagle",
"AnimalType": "Dog"
}
	]
}

```

## Query e Scan - detalhes adicionais

### Expressões condicionais

Ao usar as operações **Query** e **Scan**, você pode usar expressões condicionais para filtrar os resultados retornados. As expressões condicionais podem ser definidas nos campos **Sort Key Expression** (disponível apenas na operação **Query**) e **Filter Expression** (disponível nas operações **Query** e **Scan**).

Estas expressões são similares às opções de filtro em uma query SQL, como pode ser visto nos exemplos a seguir:

<figure><img src="https://content.gitbook.com/content/SKBJ6ZiEWBU93x170HH4/blobs/4tE2JhZAzaC0HZSBHXbn/dynamodb-doc-img-01.png" alt=""><figcaption><p>Expressão condicional exemplo 1</p></figcaption></figure>

<figure><img src="https://content.gitbook.com/content/SKBJ6ZiEWBU93x170HH4/blobs/nSThj7sLnJgVh4byAnWK/dynamodb-doc-img-02.png" alt=""><figcaption><p>Expressão condicional exemplo 2</p></figcaption></figure>

Perceba que os valores reais a serem usados nas condições não podem ser colocados diretamente nas expressões. Como alternativa, um placeholder no formato "dois pontos + nome" deve ser usado, e o valor é então passado pelo campo **Expression Attribute Values** field. No exemplo acima, os seguintes valores de atributos teriam que ser especificados:

<figure><img src="https://content.gitbook.com/content/SKBJ6ZiEWBU93x170HH4/blobs/A97aOsCflc3zO9ZFIDJ7/dynamodb-doc-img-03.png" alt=""><figcaption><p>Expressão condicional exemplo 3</p></figcaption></figure>

<figure><img src="https://content.gitbook.com/content/SKBJ6ZiEWBU93x170HH4/blobs/U8ZCOxMD2oRFZtX81q77/dynamodb-doc-img-04.png" alt=""><figcaption><p>Expressão condicional exemplo 4 - detalhe Placeholder</p></figcaption></figure>

Observe que o valor do campo **Placeholder** deve corresponder exataente aos nomes usados nas expressões condicionais, incluíndo as vírgulas.

### Double Braces em expressões condicionais

Ao usar expressões Double Braces dentro de expressões condicionais, não há necessidade de especificar os valores correspondentes pelo campo **Expression Attribute Values**. O mesmo exemplo acima poderia ter sido especificado desta forma:&#x20;

<figure><img src="https://content.gitbook.com/content/SKBJ6ZiEWBU93x170HH4/blobs/ZpH4diH7x9U8J1yZkeS6/dynamodb-doc-img-05.png" alt=""><figcaption><p>Expressão condicional exemplo 5 - Sort Key Expression</p></figcaption></figure>

<figure><img src="https://content.gitbook.com/content/SKBJ6ZiEWBU93x170HH4/blobs/ypnqlJOaSgdKhZC4txSm/dynamodb-doc-img-06.png" alt=""><figcaption><p>Expressão condicional exemplo 6 - Filter Expression</p></figcaption></figure>

Neste caso, o conector infere os tipos de dados e valores da mensagem de entrada JSON. Os placeholders são gerados automaticamente pelo conector usando números sequenciais. Nesta situação, seria esperada uma mensagem de entrada como no exemplo a seguir:

```
{
	"skMinValue": 8965,
	"skMaxValue": 9165,
	"createdAtBottom": "2024-03-25T16:11:22Z",
	"deletedVal": false
}

```

[Leia a documentação da AWS para mais detalhes sobre expressões condicionais](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Syntax).

### Resultados paginados

O **DynamoDB** pode paginar os resultados de uma operação **Query** ou **Scan** operation em duas situações:

* O número de itens buscados é maior do que o número estabelecido no parâmetro **Limit**.
* O tamanho total da resposta supera 1MB.

Em situações onde uma resposta paginada é retornada, um campo extra `lastEvaluatedKey` será adicionado à saída, contendo as chaves primárias do último item retornado. Estas chaves retornadas podem então ser usadas em operações subsequentes **Query** ou **Scan** ao aplicá-las nos campos **Exclusive Start Key**.

Na sequência, temos um exemplo de saída paginada:

```
{
	"success": true,
       	"data":[
		{...},
		{...},
		{...},
		...
	],
	"queryCount": 1000,
	"lastEvaluatedKey": {
		"partitionKeyName": 12,
		"sortKeyName" "abc",
		"indexPartitionKeyName": 123,
		"indexSortKeyName": "index-abc"
	}
}

```

Perceba que nesse caso, temos uma mapa entre os campos com nomes de chaves e seus respectivos valores. Os campos-chave de índice são omitidos se a operação não tiver o campo **Index Name** especificado.

Os campos **Exclusive Start Key** teriam que estar especificados conforme a imagem a seguir para a seguinte iteração de página:

<figure><img src="https://content.gitbook.com/content/SKBJ6ZiEWBU93x170HH4/blobs/dEdJRamVGJ42grK6bhix/dynamodb-doc-img-07.png" alt=""><figcaption><p>Expressão condicional exemplo 7 - Exclusive Start Key</p></figcaption></figure>