# 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](/documentation/connectors-and-triggers/pt-br/double-braces/overview.md) 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="/pages/iulYYuz29bvfGjceZb4e"><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="/files/4jZRK30BeZxlyRw31et7" alt=""><figcaption><p>Expressão condicional exemplo 1</p></figcaption></figure>

<figure><img src="/files/8PGr8NQDQ6TF8oLefkKZ" 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="/files/IMKx4fv16mFpAN70wF1I" alt=""><figcaption><p>Expressão condicional exemplo 3</p></figcaption></figure>

<figure><img src="/files/TNK80WlTLwo7HbNxAuQM" 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="/files/21EP87ICHuP0DoHIYNTD" alt=""><figcaption><p>Expressão condicional exemplo 5 - Sort Key Expression</p></figcaption></figure>

<figure><img src="/files/fRuFglvvnKwELpme73Tv" 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="/files/ynebW9RMQvbrFwxDNOuA" alt=""><figcaption><p>Expressão condicional exemplo 7 - Exclusive Start Key</p></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/structured-data/dynamodb.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.