kvp in attributeList)
{
string attributeName = kvp.Key;
AttributeValue value = kvp.Value;
Console.WriteLine(
attributeName + " " +
(value.S == null ? "" : "S=[" + value.S + "]") +
(value.N == null ? "" : "N=[" + value.N + "]") +
(value.SS == null ? "" : "SS=[" + string.Join(",", value.SS.ToArray()) + "]") +
(value.NS == null ? "" : "NS=[" + string.Join(",", value.NS.ToArray()) + "]") +
(value.B == null ? "" : "B=[" + FromGzipMemoryStream(value.B) + "]")
);
}
Console.WriteLine("************************************************");
}
private static MemoryStream ToGzipMemoryStream(string value)
{
MemoryStream output = new MemoryStream();
using (GZipStream zipStream = new GZipStream(output, CompressionMode.Compress, true))
using (StreamWriter writer = new StreamWriter(zipStream))
{
writer.Write(value);
}
return output;
}
private static string FromGzipMemoryStream(MemoryStream stream)
{
using (GZipStream zipStream = new GZipStream(stream, CompressionMode.Decompress))
using (StreamReader reader = new StreamReader(zipStream))
{
return reader.ReadToEnd();
}
}
}
}
```
# Mejora del acceso con índices secundarios en DynamoDB
Amazon DynamoDB proporciona un acceso rápido a los elementos de una tabla especificando sus valores de clave principal. Sin embargo, muchas aplicaciones podrían beneficiarse de disponer de una o varias claves secundarias (o alternativas) para permitir un acceso eficiente a datos con otros atributos aparte de la clave principal. Para responder a esta necesidad, puede crear uno o varios índices secundarios en una tabla y emitir solicitudes `Query` o `Scan` para estos índices.
Un *índice secundario* es una estructura de datos que contiene un subconjunto de atributos de una tabla, además de una clave alternativa para admitir las operaciones `Query`. Puede recuperar datos del índice usando una operación `Query` prácticamente de la misma forma que `Query` se usa en una tabla. Una tabla puede tener varios índices secundarios, lo que permite a las aplicaciones obtener acceso a distintos patrones de consulta.
**nota**
También se pueden utilizar operaciones `Scan` en los índices, de un modo bastante similar a como `Scan` se usaría en una tabla.
Las políticas [basadas en recursos](access-control-resource-based.md) no admiten actualmente el acceso entre cuentas para operaciones de análisis de índices secundarios.
Cada índice secundario está asociado exactamente con una tabla de la que obtiene sus datos. Esta se denomina *tabla base* del índice. Al crear un índice, se define una clave alternativa para él (clave de partición y clave de ordenación). También se definen los atributos de la tabla base que se desea *proyectar*, o copiar, en el índice. DynamoDB copia estos atributos en el índice, junto con los atributos de clave principal de la tabla base. A partir de ese momento, puede consultar o examinar el índice exactamente igual que una tabla.
DynamoDB mantiene automáticamente cada índice secundario. Cuando se agregan, modifican o eliminan elementos en la tabla base, los índices basados en esa tabla se actualizan también para reflejar estos cambios.
DynamoDB admite dos tipos de índices secundarios:
+ **[Índice secundario global](GSI.html):** índice con una clave de partición y una clave de ordenación que pueden diferir de las claves de la tabla base. Un índice secundario global se considera "global" porque las consultas que se realizan en el índice pueden abarcar todos los datos de la tabla base y todas las particiones. Un índice secundario global se almacena en su propio espacio de partición lejos de la tabla base y se escala por separado de la tabla base.
+ **[Índice secundario local](LSI.html):** índice que tiene la misma clave de partición que la tabla base, pero una clave de ordenación distinta. Un índice secundario local se considera "local" en el sentido de que el ámbito de todas sus particiones se corresponde con una partición de la tabla base que tiene el mismo valor de clave de partición.
Para ver una comparación de los índices secundarios globales y los índices secundarios locales, consulte este vídeo.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/BkEu7zBWge8)
**Topics**
+ [Uso de índices secundarios globales en DynamoDB](GSI.md)
+ [Índices secundarios locales](LSI.md)
Debe tener en cuenta los requisitos de la aplicación al determinar qué tipo de índice va a utilizar. En la siguiente tabla se muestran las principales diferencias entre un índice secundario global y un índice secundario local.
****
| Característica | Índice secundario global | Índice secundario local |
| --- | --- | --- |
| Esquema de claves | La clave principal de un índice secundario global puede ser simple (clave de partición) o compuesta (clave de partición y clave de ordenación). | La clave principal de un índice secundario local debe ser compuesta (clave de partición y clave de ordenación). |
| Atributos de clave | La clave de partición y la clave de ordenación (si procede) del índice pueden ser cualesquiera atributos de tipo String, Number o Binary de la tabla base. | La clave de partición del índice es el mismo atributo que la clave de partición de la tabla base. La clave de ordenación puede ser cualquier atributo de tipo String, Number o Binary de la tabla base. |
| Restricciones de tamaño por valor de clave de partición | No hay restricciones de tamaño para los índices secundarios globales. | Para cada valor de clave de partición, el tamaño total de todos los elementos indexados debe ser de 10 GB o menos. |
| Operaciones online con índices | Los índices secundarios globales se pueden crear al mismo tiempo que se crea una tabla. También puede agregar un nuevo índice secundario global a una tabla existente o eliminar un índice secundario global existente. Para obtener más información, consulte [Administración de índices secundarios globales en DynamoDB](GSI.OnlineOps.md). | Los índices secundarios locales se crean a la vez que se crea la tabla. No se puede agregar un índice secundario local a una tabla existente, ni tampoco se puede eliminar ningún índice secundario local que ya exista. |
| Consultas y particiones | Un índice secundario global permite realizar consultas en toda la tabla y en todas las particiones. | Un índice secundario local permite consultar una sola partición, según lo especificado por el valor de clave de partición de la consulta. |
| Consistencia de lectura | Las consultas a los índices secundarios globales solo admiten la consistencia final. | Cuando se realiza una consulta en un índice secundario local, se puede elegir entre la consistencia final o alta. |
| Consumo de desempeño provisionado | Cada índice secundario global tiene su propia configuración de rendimiento aprovisionado para la actividad de lectura y escritura. Las consultas o exámenes de un índice secundario global consumen unidades de capacidad del índice, no de la tabla base. Esto mismo sucede con las actualizaciones de los índices secundarios globales debidas a escrituras en la tabla. Un índice secundario global asociado a las tablas globales consume unidades de capacidad de escritura. | Las consultas o análisis de un índice secundario local consumen unidades de capacidad de lectura de la tabla base. Al escribir en una tabla, sus índices secundarios locales también se actualizan y estas actualizaciones consumen unidades de capacidad de escritura de la tabla base. Un índice secundario local asociado a las tablas globales consume unidades de capacidad de escritura replicadas. |
| Atributos proyectados | Cuando se consulta o analiza un índice secundario global, solo se pueden solicitar los atributos que se han proyectado en él. DynamoDB no recupera ningún atributo de la tabla. | Cuando se consulta o analiza un índice secundario local, se pueden solicitar los atributos que no se hayan proyectado en él. DynamoDB recuperará automáticamente estos atributos de la tabla. |
Si desea crear más de una tabla con índices secundarios, debe hacerlo de forma secuencial. Por ejemplo, tendría que crear la primera tabla y esperar a que su estado fuese `ACTIVE`, luego la siguiente tabla y esperar a que adquiriese el estado `ACTIVE`, y así sucesivamente. Si intenta crear simultáneamente más de una tabla con un índice secundario, DynamoDB devuelve una excepción `LimitExceededException`.
Cada índice secundario usa la misma [clase de tabla](HowItWorks.TableClasses.html) y el mismo [modo de capacidad](capacity-mode.md) que la tabla base a la que está asociado. Para cada índice secundario debe especificar lo siguiente:
+ Tipo de índice que se va a crear, ya sea un índice secundario global o un índice secundario local.
+ El nombre del índice. Las reglas de nomenclatura de los índices son las mismas que para las tablas, como se indica en [Cuotas en Amazon DynamoDB](ServiceQuotas.md). El nombre debe ser único para la tabla base al que está asociado, pero puede utilizar el mismo nombre para índices que estén asociados a tablas base distintas.
+ El esquema de claves del índice. Cada atributo del esquema de claves del índice debe ser un atributo de nivel superior debe de tipo `String`, `Number` y `Binary`. No se permiten otros tipos de datos, como los documentos y los conjuntos. Los demás requisitos del esquema de claves dependen del tipo de índice:
+ Si se trata de un índice secundario global, la clave de partición puede ser cualquier atributo escalar de la tabla base. La clave de ordenación es opcional y también puede ser cualquier atributo escalar de la tabla base.
+ Si se trata de un índice secundario local, la clave de partición debe ser igual que la tabla de partición de la tabla base y la clave de ordenación debe ser un atributo sin clave de la tabla base.
+ Los atributos adicionales, si los hay, de la tabla base que se proyectarán en el índice. Estos atributos se agregan a los atributos de clave de la tabla, que se proyectan de forma automática en cada índice. Puede proyectar atributos de cualquier tipo de datos, incluidos escalares, documentos y conjuntos.
+ Los ajustes de desempeño provisionado del índice, si es preciso:
+ Para un índice secundario global, debe especificar los ajustes de unidades de capacidad de lectura y escritura. Estos ajustes de desempeño provisionado son independientes de los ajustes de la tabla base.
+ Para un índice secundario local, no es preciso especificar los ajustes de unidades de capacidad de lectura y escritura. Todas las operaciones de lectura y escritura en un índice secundario local consumen el rendimiento aprovisionado configurado para su tabla base.
Para disfrutar de la máxima flexibilidad en las consultas, puede crear hasta 20 índices secundarios globales (cuota predeterminada) y hasta 5 índices secundarios locales por tabla.
Para obtener un listado detallado de índices secundarios en una tabla, utilice la operación `DescribeTable`. `DescribeTable` devuelve el nombre, el tamaño de almacenamiento y el recuento de elementos de cada índice secundario de la tabla. Estos valores no se actualizan en tiempo real, sino aproximadamente cada seis horas.
Para obtener acceso a los datos de un índice secundario, utilice las operaciones `Query` o `Scan`. Debe especificar el nombre de la tabla base y el nombre del índice que se desea utilizar, los atributos que se devolverán en los resultados y las expresiones de condición o filtros que se van a aplicar. DynamoDB puede devolver los resultados en orden ascendente o descendente.
Al eliminar una tabla, todos los índices asociados a ella se eliminan también.
Para ver las prácticas recomendadas, consulte [Prácticas recomendadas para utilizar índices secundarios en DynamoDB](bp-indexes.md).
# Uso de índices secundarios globales en DynamoDB
Algunas aplicaciones pueden necesitar llevar a cabo muy diversos tipos de consultas en las que se usen distintos atributos como criterios de consulta. Para responder a estos requisitos, puede crear uno o más * índices secundarios globales* y emitir solicitudes `Query` en ellos en Amazon DynamoDB.
**Topics**
+ [Situación: Uso de un índice secundario global](#GSI.scenario)
+ [Proyecciones de atributos](#GSI.Projections)
+ [Esquema de claves de varios atributos](#GSI.MultiAttributeKeys)
+ [Lectura de datos de un índice secundario global](#GSI.Reading)
+ [Sincronización de datos entre tablas e índices secundarios globales](#GSI.Writes)
+ [Clases de tabla con un índice secundario global](#GSI.tableclasses)
+ [Consideraciones sobre el rendimiento aprovisionado para los índices secundarios globales](#GSI.ThroughputConsiderations)
+ [Consideraciones sobre el almacenamiento para los índices secundarios globales](#GSI.StorageConsiderations)
+ [Patrones de diseño](GSI.DesignPatterns.md)
+ [Administración de índices secundarios globales en DynamoDB](GSI.OnlineOps.md)
+ [Detección y corrección de infracciones de la clave del índice en DynamoDB](GSI.OnlineOps.ViolationDetection.md)
+ [Trabajo con índices secundarios globales: Java](GSIJavaDocumentAPI.md)
+ [Trabajar con índices secundarios globales: .NET](GSILowLevelDotNet.md)
+ [Uso de índices secundarios globales en DynamoDB con la AWS CLI](GCICli.md)
## Situación: Uso de un índice secundario global
Por poner un ejemplo, tomemos una tabla denominada `GameScores` que realiza el seguimiento de los usuarios y las puntuaciones de una aplicación de juegos para móviles. Cada elemento en `GameScores` se identifica por una clave de partición (`UserId`) y una clave de ordenación (`GameTitle`). En el siguiente diagrama se muestra cómo se organizarían los elementos de la tabla. No se muestran todos los atributos.
![\[Tabla GameScores con una lista de ID de usuarios, nombres, puntuaciones, fechas y partidas ganadas/perdidas.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/GSI_01.png)
Ahora, supongamos que desea escribir una aplicación de clasificación para mostrar las puntuaciones máximas de cada juego. Una consulta que especifique los atributos de clave (`UserId` y `GameTitle`) sería muy eficiente. Sin embargo, si la aplicación tuviese que recuperar datos de `GameScores` solo según `GameTitle`, tendría que usar una operación `Scan`. A medida que se agregan elementos a la tabla, los exámenes de todos los datos resultarían lentos e ineficientes. En consecuencia, resultaría difícil responder a preguntas como estas:
+ ¿Cuál es la puntuación máxima que se ha registrado en el juego Meteor Blasters?
+ ¿Qué usuario ha obtenido la mejor puntuación en Galaxy Invaders?
+ ¿Cuál es la mayor proporción de partidas ganadas respecto a las perdidas?
Para agilizar las consultas de atributos sin clave, puede crear un índice secundario global. Un índice secundario global contiene una selección de atributos de la tabla base, pero están organizados por una clave principal distinta de la clave principal de la tabla. La clave de índice no requiere disponer de ninguno de los atributos de clave de la tabla. Ni siquiera necesita el mismo esquema de claves que una tabla.
Por ejemplo, puede crear un índice secundario global llamado `GameTitleIndex`, con una clave de partición de `GameTitle` y una clave de ordenación de `TopScore`. Puesto que los atributos de clave principal de la tabla base siempre se proyectan en un índice, el atributo `UserId` también está presente. En el siguiente diagrama se muestra el aspecto que tendría el índice `GameTitleIndex`.
![\[Tabla GameTitleIndex con una lista de nombres, puntuaciones e ID de usuarios.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/GSI_02.png)
Ahora, puede consultar `GameTitleIndex` y obtener fácilmente las puntuaciones de Meteor Blasters. Los resultados se ordenan según los valores de la clave de ordenación, `TopScore`. Si establece el parámetro `ScanIndexForward` en false, los resultados se devuelven en orden descendente, de modo que la puntuación máxima se devuelve en primer lugar.
Cada índice secundario global debe tener una clave de partición y puede tener una clave de ordenación opcional. El esquema de claves de índice puede ser distinto del de la tabla base. La tabla podría tener una clave principal simple (clave de partición) y, en cambio, se podría crear un índice secundario global con una clave principal compuesta (clave de partición y clave de ordenación), o viceversa. Los atributos de clave del índice pueden constar de cualquier atributo de nivel superior de tipo `String`, `Number` o `Binary` de la tabla base. No se admite ningún otro tipo de escalar, documento ni conjunto.
Puede proyectar otros atributos de la tabla base en el índice si lo desea. Cuando se consulta el índice, DynamoDB puede recuperar estos atributos proyectados de forma eficiente. Sin embargo, las consultas de índice secundario global no permiten recuperar atributos de la tabla base. Por ejemplo, si consulta `GameTitleIndex` como se muestra en el diagrama anterior, la consulta no podría obtener acceso a ningún atributo sin clave excepto a `TopScore` (aunque los atributos de clave `GameTitle` y `UserId` se proyectarían automáticamente).
En una tabla de DynamoDB, cada valor de clave debe ser único. Sin embargo, no es obligatorio que los valores de clave de un índice secundario global sean únicos. A modo de ejemplo, supongamos que un juego denominado Comet Quest es especialmente difícil, de tal forma que muchos usuarios nuevos intentan lograr una puntuación superior a cero, sin conseguirlo. A continuación se muestran algunos datos que podrían representar esta situación.
****
| UserId | GameTitle | TopScore |
| --- | --- | --- |
| 123 | Comet Quest | 0 |
| 201 | Comet Quest | 0 |
| 301 | Comet Quest | 0 |
Cuando estos datos se agregan a la tabla `GameScores`, DynamoDB los propaga a `GameTitleIndex`. Si, a continuación, consultamos el índice con el valor Comet Quest en `GameTitle` y el valor 0 en `TopScore`, se devuelven los valores siguientes.
![\[Tabla con una lista de nombres, puntuaciones máximas e ID de usuarios.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/GSI_05.png)
Solo aparecerán en la respuesta los elementos que tengan los valores de clave especificados. Dentro de ese conjunto de datos, los elementos no aparecen en ningún orden concreto.
Un índice secundario global solo realiza el seguimiento de los elementos de datos cuyos atributos de clave existen realmente. Por ejemplo, supongamos que ha agregado otro elemento nuevo a la tabla `GameScores`, pero que solo ha proporcionado los atributos de clave principal obligatorios.
****
| UserId | GameTitle |
| --- | --- |
| 400 | Comet Quest |
Al no haber especificado el atributo `TopScore`, DynamoDB no propagará este elemento a `GameTitleIndex`. Por lo tanto, si consultase `GameScores` para obtener todos los elementos de Comet Quest, obtendría los siguientes cuatro elementos.
![\[Tabla con una lista de 4 nombres, puntuaciones máximas e ID de usuarios.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/GSI_04.png)
Una consulta parecida de `GameTitleIndex` devolvería tres elementos, en lugar de cuatro. Esto se debe a que el elemento cuyo valor de `TopScore` no existe no se propaga al índice.
![\[Tabla con una lista de 3 nombres, puntuaciones máximas e ID de usuarios.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/GSI_05.png)
## Proyecciones de atributos
Una *proyección* es el conjunto de atributos que se copia de una tabla en un índice secundario. La clave de partición y la clave de ordenación de la tabla siempre se proyectan en el índice; puede proyectar otros atributos para admitir los requisitos de consulta de la aplicación. Cuando consulta un índice, Amazon DynamoDB puede acceder a cualquier atributo de la proyección como si esos atributos estuvieran en una tabla propia.
Al crear un índice secundario, debe especificar los atributos que se proyectarán en el índice. DynamoDB ofrece tres opciones diferentes para esto:
+ *KEYS\$1ONLY*: cada elemento del índice consta únicamente de los valores de la clave de partición y la clave de ordenación de la tabla, así como de los valores de las claves del índice. La opción `KEYS_ONLY` da como resultado el índice secundario más pequeño posible.
+ *INCLUDE*: además de los atributos que se describen en `KEYS_ONLY`, el índice secundario incluirá otros atributos sin clave que se especifiquen.
+ *ALL*: el índice secundario incluye todos los atributos de la tabla de origen. Debido a que todos los datos de la tabla están duplicados en el índice, un resultado de proyección `ALL` en el índice secundario más grande posible.
En el diagrama anterior, `GameTitleIndex` tiene solo un atributo proyectado: `UserId`. Por tanto, mientras una aplicación puede determinar de forma eficiente el `UserId` de los jugadores que tienen mayor puntuación en cada juego utilizando `GameTitle` y `TopScore` en las consultas, no puede determinar de manera eficiente la mayor proporción de partidas ganadas respecto a las perdidas para los jugadores con mayor puntuación. Para ello, la aplicación tendría que realizar una consulta adicional en la tabla base para recuperar las partidas ganadas y perdidas de cada uno de los jugadores con mayor puntuación. Una manera más eficiente de consultar estos datos sería proyectar estos atributos de la tabla base en el índice secundario global, tal y como se muestra en este diagrama.
![\[Representación de la proyección de atributos sin clave en un GSI para realizar consultas eficientes.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/GSI_06.png)
Dado que los atributos sin clave `Wins` y `Losses` se proyectan en el índice, una aplicación puede determinar la proporción de partidas ganadas respecto a las perdidas en cualquier juego, o para cualquier combinación de juego e identificador de usuario.
Cuando elija los atributos para proyectarlos en un índice secundario global, debe estudiar el equilibrio entre los costes de rendimiento aprovisionado y de almacenamiento:
+ Si solo necesita obtener acceso a algunos atributos con la menor latencia posible, puede ser conveniente proyectar solamente esos atributos en un índice secundario global. Cuando menor es el índice, menos cuesta almacenarlo y menos son los costes de escritura.
+ Si la aplicación va a obtener acceso con frecuencia a determinados atributos sin clave, puede ser interesante proyectarlos en un índice secundario global. Los costes del almacenamiento adicionales del índice secundario global compensarán el coste que supondrían los frecuentes exámenes de la tabla.
+ Si tiene que obtener acceso a la mayoría de los atributos sin clave con frecuencia, puede proyectar estos atributos o, incluso, toda la tabla base, en un índice secundario global. Esto le da la máxima flexibilidad. Sin embargo, el coste del almacenamiento aumentaría y podría llegar a duplicarse.
+ Si la aplicación tiene que consultar una tabla con poca frecuencia, pero tiene que realizar gran cantidad de escrituras o actualizaciones en los datos de la tabla, puede ser conveniente proyectar `KEYS_ONLY`. El índice secundario global tendrá el tamaño mínimo, pero estaría disponible siempre que se requiriese para actividades de consulta.
## Esquema de claves de varios atributos
Los índices secundarios globales admiten claves de varios atributos, lo que le permite componer claves de partición y claves de clasificación a partir de varios atributos. Con las claves de varios atributos, puede crear una clave de partición a partir de un máximo de cuatro atributos y una clave de clasificación a partir de un máximo de cuatro atributos, hasta un total de ocho atributos por esquema de clave.
Las claves de varios atributos simplifican el modelo de datos al eliminar la necesidad de concatenar manualmente los atributos en claves sintéticas. En lugar de crear cadenas compuestas como `TOURNAMENT#WINTER2024#REGION#NA-EAST`, puede utilizar directamente los atributos naturales del modelo de dominio. DynamoDB gestiona automáticamente la lógica de clave compuesta, agrupando varios atributos de clave de partición para distribuir los datos y manteniendo el orden jerárquico de varios atributos de clave de clasificación.
Por ejemplo, considere un sistema de torneos de juegos en el que desee organizar las partidas por torneo y región. Con las claves de varios atributos, puede definir la clave de partición como dos atributos independientes: `tournamentId` y `region`. Del mismo modo, puede definir la clave de clasificación mediante varios atributos como `round`, `bracket` y `matchId` para crear una jerarquía natural. Este enfoque mantiene los datos mecanografiados y el código limpio, sin manipular ni analizar las cadenas.
Al consultar un índice secundario global con claves de varios atributos, debe especificar todos los atributos de las claves de partición mediante condiciones de igualdad. Para los atributos de las claves de clasificación, puede consultarlos de izquierda a derecha en el orden en que están definidos en el esquema de claves. Esto significa que puede consultar solo el primer atributo de clave de clasificación, los dos primeros atributos juntos o todos los atributos juntos, pero no puede omitir los atributos del medio. Condiciones de desigualdad como `>`, `<`, `BETWEEN` o `begins_with()` deben ser la última condición de la consulta.
Las claves de varios atributos funcionan especialmente bien al crear índices secundarios globales en tablas existentes. Puede usar atributos que ya existen en la tabla sin rellenar los datos con claves sintéticas. Esto facilita la agregación de nuevos patrones de consulta a la aplicación mediante la creación de índices que reorganizan los datos mediante diferentes combinaciones de atributos.
Cada atributo de una clave de varios atributos puede tener su propio tipo de datos: `String` (S), `Number` (N) o `Binary` (B). Al elegir los tipos de datos, tenga en cuenta que los atributos de `Number` se ordenan numéricamente sin necesidad de rellenar ceros, mientras que los atributos de `String` se ordenan lexicográficamente. Por ejemplo, si utiliza un tipo de `Number` para un atributo de puntuación, los valores 5, 50, 500 y 1000 se ordenan en orden numérico natural. Los mismos valores que el tipo de `String` se ordenarían como “1000”, “5”, “50” o “500”, a menos que los rellene con ceros a la izquierda.
Al diseñar claves de varios atributos, ordene los atributos del más general al más específico. En el caso de las claves de partición, combine los atributos que siempre se consulten juntos y que proporcionen una buena distribución de los datos. En el caso de las claves de clasificación, coloque los atributos consultados con frecuencia en primer lugar de la jerarquía para maximizar la flexibilidad de las consultas. Este orden le permite realizar consultas en cualquier nivel de detalle que coincida con los patrones de acceso.
Consulte los ejemplos de [Claves de varios atributos](GSI.DesignPattern.MultiAttributeKeys.md) para implementación.
## Lectura de datos de un índice secundario global
Puede recuperar elementos de un índice secundario global mediante las operaciones `Query` y `Scan`. Las opreciones `GetItem` y `BatchGetItem` no se pueden usar en un índice secundario global.
### Consulta a un índice secundario global
Puede utilizar la operación `Query` para obtener acceso a uno o varios elementos de un índice secundario global. En la consulta se debe especificar el nombre de la tabla base y el nombre del índice que se desea utilizar, los atributos que se devolverán en los resultados de la consulta y las condiciones de consulta que se van a aplicar. DynamoDB puede devolver los resultados en orden ascendente o descendente.
Tomemos los datos siguientes devueltos por una operación `Query` que solicita datos de juegos para una aplicación de clasificación de juegos.
```
{
"TableName": "GameScores",
"IndexName": "GameTitleIndex",
"KeyConditionExpression": "GameTitle = :v_title",
"ExpressionAttributeValues": {
":v_title": {"S": "Meteor Blasters"}
},
"ProjectionExpression": "UserId, TopScore",
"ScanIndexForward": false
}
```
En esta consulta:
+ DynamoDB accede *GameTitleIndex* utilizando la clave de partición *GameTitle* para localizar los elementos de índice correspondientes a Meteor Blasters. Todos los elementos de índice que tienen esta clave se almacenan en posiciones adyacentes, para agilizar su recuperación.
+ En este juego, DynamoDB utiliza el índice para obtener acceso a todos los identificadores de los usuarios y a las puntuaciones máximas de este juego.
+ Los resultados se devuelven ordenados por orden descendente, porque el parámetro `ScanIndexForward` se ha establecido en false.
### Análisis de un índice secundario global
Puede usar la operación `Scan` para recuperar todos los datos de un índice secundario global. Debe proporcionar el nombre de la tabla base y el nombre del índice en la solicitud. Con una operación `Scan`, DynamoDB lee todos los datos del índice y los devuelve a la aplicación. También puede solicitar que solo se devuelvan algunos de los datos y se descarten los demás. Para ello, se utiliza el parámetro `FilterExpression` de la operación `Scan`. Para obtener más información, consulte [Expresiones de filtro para el análisis](Scan.md#Scan.FilterExpression).
## Sincronización de datos entre tablas e índices secundarios globales
DynamoDB sincroniza automáticamente cada índice secundario global con su tabla base. Cuando una aplicación escribe o elimina elementos en una tabla, cualquier índice secundario global de esa tabla se actualizan de forma asincrónica, aplicando un modelo de consistencia final. Las aplicaciones nunca escriben directamente en un índice. Sin embargo, es importante que comprenda las implicaciones de cómo DynamoDB mantiene estos índices.
Los índices secundarios globales heredan el modo de capacidad de lectura/escritura de la tabla base. Para obtener más información, consulte [Aspectos a tener en cuenta al cambiar los modos de capacidad en DynamoDB](bp-switching-capacity-modes.md).
Al crear un índice secundario global, debe especificar uno o varios atributos de clave de índice y sus tipos de datos. Esto significa que, cada vez que se escribe un elemento en la tabla base, los tipos de datos de esos atributos deben coincidir con los tipos de datos del esquema de claves de índice. En el caso de `GameTitleIndex`, el tipo de datos de la clave de partición `GameTitle` del índice es `String`. La clave de ordenación `TopScore` del índice es de tipo `Number`. Si intenta agregar un elemento a la tabla `GameScores`, pero especifica un tipo de datos distinto para `GameTitle` o `TopScore`, DynamoDB devolverá una excepción `ValidationException`, porque los tipos de datos no coinciden.
Al colocar o eliminar elementos en una tabla, sus índices secundarios globales se actualizan de forma consistente final. En condiciones normales, los cambios en los datos de la tabla se propagan a los índices secundarios globales casi al instante. No obstante, en algunos escenarios de error improbables, pueden producirse retardos de propagación más prolongados. Debido a ello, las aplicaciones deben prever y controlar las situaciones en las que una consulta de un índice secundario global devuelva resultados que no se encuentren actualizados.
Si escribe un elemento en una tabla, no tiene que especificar los atributos de ninguna clave de ordenación del índice secundario global. Si utilizamos `GameTitleIndex` a modo de ejemplo, no sería preciso especificar un valor para el atributo `TopScore` para poder escribir un nuevo elemento en la tabla `GameScores`. En este caso, DynamoDB no escribe ningún dato en el índice para este elemento concreto.
Una tabla con muchos índices secundarios globales devengará costes más elevados por la actividad de escritura que las tablas con menos índices. Para obtener más información, consulte [Consideraciones sobre el rendimiento aprovisionado para los índices secundarios globales](#GSI.ThroughputConsiderations).
## Clases de tabla con un índice secundario global
Un índice secundario global siempre utilizará la misma clase de tabla que su tabla base. Cada vez que se agrega un nuevo índice secundario global para una tabla, el nuevo índice utilizará la misma clase de tabla que su tabla base. Cuando se actualiza la clase de tabla de una tabla, también se actualizan todos los índices secundarios globales asociados.
## Consideraciones sobre el rendimiento aprovisionado para los índices secundarios globales
Al crear un índice secundario global en una tabla en modo aprovisionado, debe especificar las unidades de capacidad de lectura y escritura para la carga de trabajo prevista de ese índice. Los ajustes de rendimiento aprovisionado de un índice secundario global son independientes de los de su tabla base. Una operación `Query` en un consume unidades de capacidad de lectura del índice, no de la tabla base. Al colocar, actualizar o eliminar elementos en una tabla, sus índices secundarios globales se actualizan de forma consistente final. Estas actualizaciones de índices consumen unidades de capacidad de escritura del índice, no de la tabla base.
Por ejemplo, si realiza una operación `Query` en un índice secundario global y supera su capacidad de lectura aprovisionada, la solicitud se someterá a una limitación controlada. Si realiza una intensa actividad de escritura en la tabla, pero un índice secundario global de esa tabla no tiene suficiente capacidad de escritura, entonces la actividad de escritura de la tabla se someterá a una limitación controlada.
**importante**
Para evitar una posible limitación controlada, la capacidad de escritura provisionada para un índice secundario global debe ser igual o mayor que la capacidad de escritura de la tabla base, ya que las nuevas actualizaciones se escribirán tanto en la tabla base como en el índice secundario global.
Para modificar los ajustes de rendimiento aprovisionado de un índice secundario global, use la operación `DescribeTable`. Se devuelve información detallada sobre cada índices secundario global de la tabla.
### Unidades de capacidad de lectura
Los índices secundarios globales admiten las lecturas consistentes finales, cada una de la cuales consume la mitad de una unidad de capacidad de lectura. Esto quiere decir que una sola consulta en un índice secundario global permite recuperar hasta 2 × 4 = 8 KB por unidad de capacidad de lectura.
Para las consultas en un índce secundario global, DynamoDB calcula la actividad de lectura provisionada de la misma forma que para las consultas en una tabla. La única diferencia es que el cálculo se basa en el tamaño de las entradas del índice, no en el tamaño del elemento en la tabla base. El número de unidades de capacidad de lectura es la suma de todos los tamaños de los atributos proyectados para todos los elementos devueltos. El resultado se redondea al múltiplo de 4 KB inmediatamente superior. Para obtener más información sobre cómo calcula DynamoDB el consumo de rendimiento aprovisionado, consulte [Modo de capacidad aprovisionada de DynamoDB](provisioned-capacity-mode.md).
El tamaño máximo de los resultados que devuelve una operación `Query` es de 1 MB. Esta cifra incluye los tamaños de todos los nombres y valores de los atributos de todos los elementos devueltos.
Por ejemplo, tomemos un índice secundario global en el que cada elemento contiene 2000 bytes de datos. Ahora, supongamos que se utiliza una operación `Query` en este índice y que la consulta `KeyConditionExpression` devuelve ocho elementos. El tamaño total de los elementos coincidentes es de 2000 bytes x 8 elementos = 16 000 bytes. El resultado se redondea al múltiplo de 4 KB inmediatamente superior. Puesto que las consultas en un índice secundario global presentan consistencia final, el coste total es de 0,5 (16 KB / 4 KB), lo que equivale a 2 unidades de capacidad de lectura.
### Unidades de capacidad de escritura
Cuando se agrega, actualiza o elimina un elemento de una tabla y esto afecta a un índice secundario global, este índice secundario global consume unidades de capacidad de escritura provisionadas por esta operación. El coste total de desempeño provisionado de una escritura es la suma de las unidades de capacidad de escritura consumidas al escribir en la tabla base y aquellas consumidas al actualizar los índices secundarios globales. Si una escritura en una tabla no requiere que se actualice un índice secundario global, no se consume ninguna capacidad de escritura del índice.
Para que una escritura en una tabla se lleve a cabo correctamente, la capacidad de desempeño provisionada definida para la tabla y todos sus índices secundarios globales debe ser suficiente para admitir esa escritura. De lo contrario, la escritura en la tabla se someterá a una limitación controlada.
**importante**
Al crear un índice secundario global (GSI), las operaciones de escritura en la tabla base se pueden limitar si la actividad del GSI resultante de las escrituras en la tabla base supera la capacidad de escritura aprovisionada del GSI. Esta limitación afecta a todas las operaciones de escritura, desde el proceso de indexación hasta la posible interrupción de las cargas de trabajo de producción. Para obtener más información, consulte [Solución de problemas de limitación en Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TroubleshootingThrottling.html).
El coste de escribir un elemento en un índice secundario global depende de varios factores:
+ Si escribe un nuevo elemento en la tabla que define un atributo indexado o actualiza un elemento existente para definir un atributo indexado no definido previamente, se requiere una operación de escritura para colocar el elemento en el índice.
+ Si al actualizar la tabla se cambia el valor de un atributo de clave indexado (de A a B), se requieren dos escrituras, una para eliminar el elemento anterior del índice y otra para colocar el nuevo elemento en el índice.
+ Si ya hay un elemento en el índice, pero al escribir en la tabla se elimina el atributo indexado, se requiere una escritura para eliminar la proyección del elemento anterior del índice.
+ Si no hay ningún elemento presente en el índice antes o después de actualizar el elemento, no se devenga ningún coste de escritura adicional para el índice.
+ Si al actualizar la tabla solo se cambia el valor de los atributos proyectados en el esquema de claves del índice, pero no se cambia el valor de ningún atributo de clave indexado, se requiere una escritura para actualizar los valores de los atributos proyectados en el índice.
Al calcular las unidades de capacidad de escritura, en todos estos factores se presupone que el tamaño de cada elemento del índice es menor o igual que el tamaño de elemento de 1 KB. Las entradas de índice de mayor tamaño requieren más unidades de capacidad de escritura. Para minimizar los costos de escritura, es conveniente estudiar qué atributos tendrán que devolver las consultas y proyectar solamente esos atributos en el índice.
## Consideraciones sobre el almacenamiento para los índices secundarios globales
Cuando una aplicación escribe un elemento en una tabla, DynamoDB copia automáticamente el subconjunto de atributos correcto en todos los índices secundarios globales en los que deban aparecer esos atributos. Se aplica un cargo en su cuenta de AWS por el almacenamiento del elemento en la tabla base y también por el almacenamiento de los atributos en todos los índices secundarios globales de esa tabla.
La cantidad de espacio utilizado por un elemento de índice es la suma de lo siguiente:
+ El tamaño en bytes de la clave principal (clave de partición y clave de ordenación) de la tabla base
+ El tamaño en bytes del atributo de clave de índice
+ El tamaño en bytes de los atributos proyectados (si procede)
+ 100 bytes de gastos generales por cada elemento de índice
Para calcular los requisitos de almacenamiento de un índice secundario global, puede calcular el tamaño medio de un elemento del índice y, a continuación, multiplicarlo por el número de elementos de la tabla base que tienen atributos de clave del índice secundario global.
Si una tabla contiene un elemento en el que no se han definido atributos determinados, pero ese atributo se ha definido como clave de partición o clave de clasificación del índice, DynamoDB no escribe ningún dato para ese elemento en el índice.
# Patrones de diseño
Los patrones de diseño ofrecen soluciones probadas a los desafíos más comunes cuando se trabaja con índices secundarios globales. Estos patrones le ayudan a crear aplicaciones eficientes y escalables, ya que le muestran cómo estructurar los índices para casos de uso específicos.
Cada patrón incluye una guía de implementación completa con ejemplos de código, prácticas recomendadas y casos de uso reales que le ayudarán a aplicar el patrón a sus propias aplicaciones.
**Topics**
+ [Claves de varios atributos](GSI.DesignPattern.MultiAttributeKeys.md)
# Patrón de claves de varios atributos
## Descripción general
Las claves de varios atributos le permiten crear claves de partición y clasificación del índice secundario global (GSI) compuestas por un máximo de cuatro atributos cada una. Esto reduce el código del cliente y facilita el modelado inicial de los datos y la posterior agregación de nuevos patrones de acceso.
Pensemos en un escenario común: para crear un GSI que consulte los elementos por varios atributos jerárquicos, tradicionalmente se necesitaría crear claves sintéticas concatenando valores. Por ejemplo, en una aplicación de juegos, para consultar las partidas de un torneo por torneo, región y ronda, puede crear una clave de partición GSI sintética, como TOURNAMENT\$1WINTER2024\$1REGION\$1NA-EAST y una clave de clasificación sintética, como ROUND\$1SEMIFINALS\$1BRACKET\$1UPPER. Este enfoque funciona, pero requiere la concatenación de cadenas al escribir datos, el análisis al leer y el relleno de claves sintéticas en todos los elementos existentes si va a agregar el GSI a una tabla existente. Esto hace que el código sea más desordenado y difícil de mantener la seguridad tipográfica en los componentes clave individuales.
Las claves de varios atributos resuelven este problema para los GSI. La clave de partición de GSI se define mediante varios atributos existentes, como el tournamentId y la región. DynamoDB gestiona automáticamente la lógica de claves compuestas y las agrupa para la distribución de los datos. Los elementos se escriben con los atributos naturales del modelo de dominio y el GSI los indexa automáticamente. Sin concatenación, sin análisis, sin relleno. El código se mantiene limpio, los datos se mantienen escritos y las consultas se mantienen sencillas. Este enfoque resulta especialmente útil cuando se dispone de datos jerárquicos con agrupaciones de atributos naturales (como torneo → región → ronda u organización → departamento → equipo).
## Ejemplo de aplicación
Esta guía explica cómo crear un sistema de seguimiento de partidos de torneos para una plataforma de deportes electrónicos. La plataforma necesita consultar los partidos de manera eficiente en múltiples dimensiones: por torneo y región para administrar los grupos, por jugador para ver el historial de partidos y por fecha para programarlos.
## Modelo de datos
En este tutorial, el sistema de seguimiento de los partidos del torneo admite tres patrones de acceso principales, cada uno de los cuales requiere una estructura de clave diferente:
**Patrón de acceso 1:** busque un partido específico por su ID único
+ **Solución:** tabla base con `matchId` como clave de partición
**Patrón de acceso 2:** consulte todos los partidos de un torneo y una región específicos y, si lo prefiere, filtre por ronda, cuadro o partido
+ **Solución:** índice secundario global con clave de partición de varios atributos (`tournamentId` \$1 `region`) y clave de clasificación de varios atributos (`round` \$1 `bracket` \$1 `matchId`)
+ **Consultas de ejemplo:** “Todos los partidos de WINTER2024 en la región NA-EAST” o “Todos los partidos de SEMIFINALES en el corchete SUPERIOR para WINTER2024/NA-EAST”
**Patrón de acceso 3:** consulte el historial de partidos de un jugador o, si lo prefiere, filtre por intervalo de fechas o por ronda del torneo
+ **Solución:** índice secundario global con clave de partición única (`player1Id`) y clave de clasificación de varios atributos (`matchDate` \$1 `round`)
+ **Consultas de ejemplo:** “Todos los partidos del jugador 101” o “Los partidos del jugador 101 en enero de 2024”
La diferencia clave entre el enfoque tradicional y el de varios atributos queda clara al examinar la estructura de los elementos:
**Enfoque de índice secundario global tradicional (claves concatenadas):**
```
// Manual concatenation required for GSI keys
const item = {
matchId: 'match-001', // Base table PK
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
// Synthetic keys needed for GSI
GSI_PK: `TOURNAMENT#${tournamentId}#REGION#${region}`, // Must concatenate
GSI_SK: `${round}#${bracket}#${matchId}`, // Must concatenate
// ... other attributes
};
```
**Enfoque de índice secundario global de varios atributos (claves nativas):**
```
// Use existing attributes directly - no concatenation needed
const item = {
matchId: 'match-001', // Base table PK
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
matchDate: '2024-01-18',
// No synthetic keys needed - GSI uses existing attributes directly
// ... other attributes
};
```
Con las claves de varios atributos, los elementos se escriben una sola vez con atributos de dominio naturales. DynamoDB los indexa automáticamente en varios GSI sin necesidad de claves concatenadas sintéticas.
**Esquema de tabla base:**
+ Clave de partición: `matchId` (1 atributo)
**Esquema de índice secundario global (TournamentRegionIndex con claves de varios atributos):**
+ Clave de partición: `tournamentId`, `region` (2 atributos)
+ Clave de clasificación: `round`, `bracket`, `matchId` (3 atributos)
**Esquema de índice secundario global (PlayerMatchHistoryIndex con claves de varios atributos):**
+ Clave de partición: `player1Id` (1 atributo)
+ Clave de clasificación: `matchDate`, `round` (2 atributos)
### Tabla base: TournamentMatches
| matchId (PK) | tournamentId | region | round | soporte | player1Id | player2Id | matchDate | ganador | puntuación |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| match-001 | WINTER2024 | NA-EAST | FINALES | CAMPEONATO MUNDIAL | 101 | 103 | 2024-01-20 | 101 | 3-1 |
| match-002 | WINTER2024 | NA-EAST | SEMIFINALES | UPPER | 101 | 105 | 2024-01-18 | 101 | 3-2 |
| match-003 | WINTER2024 | NA-EAST | SEMIFINALES | UPPER | 103 | 107 | 2024-01-18 | 103 | 3-0 |
| match-004 | WINTER2024 | NA-EAST | CUARTOS DE FINAL | UPPER | 101 | 109 | 2024-01-15 | 101 | 3-1 |
| match-005 | WINTER2024 | NA-WEST | FINALES | CAMPEONATO MUNDIAL | 102 | 104 | 2024-01-20 | 102 | 3-2 |
| match-006 | WINTER2024 | NA-WEST | SEMIFINALES | UPPER | 102 | 106 | 2024-01-18 | 102 | 3-1 |
| match-007 | SPRING2024 | NA-EAST | CUARTOS DE FINAL | UPPER | 101 | 108 | 2024-03-15 | 101 | 3-0 |
| match-008 | SPRING2024 | NA-EAST | CUARTOS DE FINAL | LOWER | 103 | 110 | 2024-03-15 | 103 | 3-2 |
### GSI: TournamentRegionIndex (claves de varios atributos)
| tournamentId (PK) | región (PK) | ronda (SK) | soporte (SK) | matchId (SK) | player1Id | player2Id | matchDate | ganador | puntuación |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| WINTER2024 | NA-EAST | FINALES | CAMPEONATO MUNDIAL | match-001 | 101 | 103 | 2024-01-20 | 101 | 3-1 |
| WINTER2024 | NA-EAST | CUARTOS DE FINAL | UPPER | match-004 | 101 | 109 | 2024-01-15 | 101 | 3-1 |
| WINTER2024 | NA-EAST | SEMIFINALES | UPPER | match-002 | 101 | 105 | 2024-01-18 | 101 | 3-2 |
| WINTER2024 | NA-EAST | SEMIFINALES | UPPER | match-003 | 103 | 107 | 2024-01-18 | 103 | 3-0 |
| WINTER2024 | NA-WEST | FINALES | CAMPEONATO MUNDIAL | match-005 | 102 | 104 | 2024-01-20 | 102 | 3-2 |
| WINTER2024 | NA-WEST | SEMIFINALES | UPPER | match-006 | 102 | 106 | 2024-01-18 | 102 | 3-1 |
| SPRING2024 | NA-EAST | CUARTOS DE FINAL | LOWER | match-008 | 103 | 110 | 2024-03-15 | 103 | 3-2 |
| SPRING2024 | NA-EAST | CUARTOS DE FINAL | UPPER | match-007 | 101 | 108 | 2024-03-15 | 101 | 3-0 |
### GSI: PlayerMatchHistoryIndex (claves de varios atributos)
| player1Id (PK) | matchDate (SK) | ronda (SK) | tournamentId | region | soporte | matchId | player2Id | ganador | puntuación |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 101 | 2024-01-15 | CUARTOS DE FINAL | WINTER2024 | NA-EAST | UPPER | match-004 | 109 | 101 | 3-1 |
| 101 | 2024-01-18 | SEMIFINALES | WINTER2024 | NA-EAST | UPPER | match-002 | 105 | 101 | 3-2 |
| 101 | 2024-01-20 | FINALES | WINTER2024 | NA-EAST | CAMPEONATO MUNDIAL | match-001 | 103 | 101 | 3-1 |
| 101 | 2024-03-15 | CUARTOS DE FINAL | SPRING2024 | NA-EAST | UPPER | match-007 | 108 | 101 | 3-0 |
| 102 | 2024-01-18 | SEMIFINALES | WINTER2024 | NA-WEST | UPPER | match-006 | 106 | 102 | 3-1 |
| 102 | 2024-01-20 | FINALES | WINTER2024 | NA-WEST | CAMPEONATO MUNDIAL | match-005 | 104 | 102 | 3-2 |
| 103 | 2024-01-18 | SEMIFINALES | WINTER2024 | NA-EAST | UPPER | match-003 | 107 | 103 | 3-0 |
| 103 | 2024-03-15 | CUARTOS DE FINAL | SPRING2024 | NA-EAST | LOWER | match-008 | 110 | 103 | 3-2 |
## Requisitos previos
Antes de comenzar, asegúrese de que dispone de lo siguiente:
### Permisos y cuenta
+ Una cuenta de AWS activa ([cree una aquí](https://aws.amazon.com/free/) si es necesario)
+ Permisos de IAM para las operaciones de DynamoDB:
+ `dynamodb:CreateTable`
+ `dynamodb:DeleteTable`
+ `dynamodb:DescribeTable`
+ `dynamodb:PutItem`
+ `dynamodb:Query`
+ `dynamodb:BatchWriteItem`
**nota**
**Nota de seguridad:** para uso de producción, cree una política de IAM personalizada con solo los permisos que necesite. Para este tutorial, puede usar la política administrada de AWS `AmazonDynamoDBFullAccessV2`.
### Entorno de desarrollo
+ Node.js se ha instalado en el equipo
+ Credenciales de AWS configuradas mediante uno de estos métodos:
**Opción 1: CLI de AWS**
```
aws configure
```
**Opción 2: Variables de entorno**
```
export AWS_ACCESS_KEY_ID=your_access_key_here
export AWS_SECRET_ACCESS_KEY=your_secret_key_here
export AWS_DEFAULT_REGION=us-east-1
```
### Instalación de los paquetes obligatorios
```
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
```
## Implementación
### Paso 1: creación de una tabla con los GSI mediante claves de varios atributos
Cree una tabla con una estructura de clave básica simple y con GSI que utilicen claves de varios atributos.
#### Ejemplo de código
```
import { DynamoDBClient, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const response = await client.send(new CreateTableCommand({
TableName: 'TournamentMatches',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'matchId', KeyType: 'HASH' } // Simple PK
],
AttributeDefinitions: [
{ AttributeName: 'matchId', AttributeType: 'S' },
{ AttributeName: 'tournamentId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'round', AttributeType: 'S' },
{ AttributeName: 'bracket', AttributeType: 'S' },
{ AttributeName: 'player1Id', AttributeType: 'S' },
{ AttributeName: 'matchDate', AttributeType: 'S' }
],
// GSIs with multi-attribute keys
GlobalSecondaryIndexes: [
{
IndexName: 'TournamentRegionIndex',
KeySchema: [
{ AttributeName: 'tournamentId', KeyType: 'HASH' }, // GSI PK attribute 1
{ AttributeName: 'region', KeyType: 'HASH' }, // GSI PK attribute 2
{ AttributeName: 'round', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'bracket', KeyType: 'RANGE' }, // GSI SK attribute 2
{ AttributeName: 'matchId', KeyType: 'RANGE' } // GSI SK attribute 3
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'PlayerMatchHistoryIndex',
KeySchema: [
{ AttributeName: 'player1Id', KeyType: 'HASH' }, // GSI PK
{ AttributeName: 'matchDate', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'round', KeyType: 'RANGE' } // GSI SK attribute 2
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}));
console.log("Table with multi-attribute GSI keys created successfully");
```
**Decisiones de diseño de clave:**
**Tabla base:** la tabla base utiliza una clave de partición de `matchId` simple para las búsquedas de coincidencias directas, lo que mantiene la estructura de la tabla base sencilla, mientras que los GSI proporcionan patrones de consulta complejos.
**Índice secundario global TournamentRegionIndex**: el índice secundario global `TournamentRegionIndex` utiliza `tournamentId` \$1 `region` como clave de partición con varios atributos, lo que aísla la región del torneo, ya que los datos se distribuyen mediante el hash de ambos atributos combinados, lo que permite realizar consultas eficaces dentro de un contexto específico de una región o torneo. La clave de clasificación de varios atributos (`round` \$1 `bracket` \$1 `matchId`) proporciona una clasificación jerárquica que permite realizar consultas en cualquier nivel de la jerarquía con un orden natural, desde general (ronda) hasta específico (ID de partido).
**Índice secundario global PlayerMatchHistoryIndex:** el índice secundario global `PlayerMatchHistoryIndex` reorganiza los datos por jugador usando `player1Id` como clave de partición, lo que permite realizar consultas entre torneos para un jugador específico. La clave de clasificación con varios atributos (`matchDate` \$1 `round`) proporciona un orden cronológico y permite filtrar por intervalos de fechas o rondas específicas del torneo.
### Paso 2: insertar datos con atributos nativos
Agrega los datos de los partidos del torneo con atributos naturales. El GSI indexará automáticamente estos atributos sin necesidad de claves sintéticas.
#### Ejemplo de código
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Tournament match data - no synthetic keys needed for GSIs
const matches = [
// Winter 2024 Tournament, NA-EAST region
{
matchId: 'match-001',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'FINALS',
bracket: 'CHAMPIONSHIP',
player1Id: '101',
player2Id: '103',
matchDate: '2024-01-20',
winner: '101',
score: '3-1'
},
{
matchId: 'match-002',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '105',
matchDate: '2024-01-18',
winner: '101',
score: '3-2'
},
{
matchId: 'match-003',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '103',
player2Id: '107',
matchDate: '2024-01-18',
winner: '103',
score: '3-0'
},
{
matchId: 'match-004',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '109',
matchDate: '2024-01-15',
winner: '101',
score: '3-1'
},
// Winter 2024 Tournament, NA-WEST region
{
matchId: 'match-005',
tournamentId: 'WINTER2024',
region: 'NA-WEST',
round: 'FINALS',
bracket: 'CHAMPIONSHIP',
player1Id: '102',
player2Id: '104',
matchDate: '2024-01-20',
winner: '102',
score: '3-2'
},
{
matchId: 'match-006',
tournamentId: 'WINTER2024',
region: 'NA-WEST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '102',
player2Id: '106',
matchDate: '2024-01-18',
winner: '102',
score: '3-1'
},
// Spring 2024 Tournament, NA-EAST region
{
matchId: 'match-007',
tournamentId: 'SPRING2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '108',
matchDate: '2024-03-15',
winner: '101',
score: '3-0'
},
{
matchId: 'match-008',
tournamentId: 'SPRING2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'LOWER',
player1Id: '103',
player2Id: '110',
matchDate: '2024-03-15',
winner: '103',
score: '3-2'
}
];
// Insert all matches
for (const match of matches) {
await docClient.send(new PutCommand({
TableName: 'TournamentMatches',
Item: match
}));
console.log(`Added: ${match.matchId} - ${match.tournamentId}/${match.region} - ${match.round} ${match.bracket}`);
}
console.log(`\nInserted ${matches.length} tournament matches`);
console.log("No synthetic keys created - GSIs use native attributes automatically");
```
**Explicación de la estructura de datos:**
**Uso de atributos naturales:** cada atributo representa un concepto de torneo real sin necesidad de concatenar cadenas ni analizar, lo que proporciona una asignación directa al modelo de dominio.
**Indexación automática del índice secundario global:** los GSI indexan automáticamente los elementos utilizando los atributos existentes (`tournamentId`, `region`, `round`, `bracket`, `matchId` para TournamentRegionIndex y `player1Id`, `matchDate`, `round` para PlayerMatchHistoryIndex) sin necesidad de claves concatenadas sintéticas.
**No es necesario rellenar:** al agregar un nuevo índice secundario global con claves de varios atributos a una tabla existente, DynamoDB indexa automáticamente todos los elementos existentes con sus atributos naturales, sin necesidad de actualizar los elementos con claves sintéticas.
### Paso 3: consulte el índice secundario global de TournamentRegionIndex con todos los atributos de las claves de partición
En este ejemplo, se consulta el índice secundario global TournamentRegionIndex, que tiene una clave de partición de varios atributos (`tournamentId` \$1 `region`). Todos los atributos de la clave de partición se deben especificar con condiciones de igualdad en las consultas; no se pueden consultar solo con `tournamentId` ni utilizar operadores de desigualdad en los atributos de la clave de partición.
#### Ejemplo de código
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query GSI: All matches for WINTER2024 tournament in NA-EAST region
const response = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
ExpressionAttributeNames: {
'#region': 'region', // 'region' is a reserved keyword
'#tournament': 'tournament'
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST'
}
}));
console.log(`Found ${response.Items.length} matches for WINTER2024/NA-EAST:\n`);
response.Items.forEach(match => {
console.log(` ${match.round} | ${match.bracket} | ${match.matchId}`);
console.log(` Players: ${match.player1Id} vs ${match.player2Id}`);
console.log(` Winner: ${match.winner}, Score: ${match.score}\n`);
});
```
**Resultado previsto:**
```
Found 4 matches for WINTER2024/NA-EAST:
FINALS | CHAMPIONSHIP | match-001
Players: 101 vs 103
Winner: 101, Score: 3-1
QUARTERFINALS | UPPER | match-004
Players: 101 vs 109
Winner: 101, Score: 3-1
SEMIFINALS | UPPER | match-002
Players: 101 vs 105
Winner: 101, Score: 3-2
SEMIFINALS | UPPER | match-003
Players: 103 vs 107
Winner: 103, Score: 3-0
```
**Consultas no válidas:**
```
// Missing region attribute
KeyConditionExpression: 'tournamentId = :tournament'
// Using inequality on partition key attribute
KeyConditionExpression: 'tournamentId = :tournament AND #region > :region'
```
**Rendimiento:** las claves de partición de varios atributos se codifican entre sí, lo que proporciona el mismo rendimiento de búsqueda O(1) que las claves de un solo atributo.
### Paso 4: consulte las claves de clasificación del índice secundario global de izquierda a derecha
Los atributos de clave de clasificación se deben consultar de izquierda a derecha en el orden en que están definidos en el índice secundario global. En este ejemplo, se muestra cómo consultar el TournamentRegionIndex en diferentes niveles jerárquicos: filtrando solo por `round`, por `round` \$1 `bracket`, o por los tres atributos de clave de clasificación. No puede omitir los atributos que están en el centro; por ejemplo, no puede consultar `round` y `matchId` mientras se omite `bracket`.
#### Ejemplo de código
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: Filter by first sort key attribute (round)
console.log("Query 1: All SEMIFINALS matches");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS'
}
}));
console.log(` Found ${query1.Items.length} matches\n`);
// Query 2: Filter by first two sort key attributes (round + bracket)
console.log("Query 2: SEMIFINALS UPPER bracket matches");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':bracket': 'UPPER'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Filter by all three sort key attributes (round + bracket + matchId)
console.log("Query 3: Specific match in SEMIFINALS UPPER bracket");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket AND matchId = :matchId',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':bracket': 'UPPER',
':matchId': 'match-002'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: INVALID - skipping round
console.log("Query 4: Attempting to skip first sort key attribute (WILL FAIL)");
try {
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':bracket': 'UPPER'
}
}));
} catch (error) {
console.log(` Error: ${error.message}`);
console.log(` Cannot skip sort key attributes - must query left-to-right\n`);
}
```
**Resultado previsto:**
```
Query 1: All SEMIFINALS matches
Found 2 matches
Query 2: SEMIFINALS UPPER bracket matches
Found 2 matches
Query 3: Specific match in SEMIFINALS UPPER bracket
Found 1 matches
Query 4: Attempting to skip first sort key attribute (WILL FAIL)
Error: Query key condition not supported
Cannot skip sort key attributes - must query left-to-right
```
**Reglas de consulta de izquierda a derecha:** debe consultar los atributos en orden de izquierda a derecha, sin omitir ninguno.
**Patrones validos:**
+ Solo el primer atributo: `round = 'SEMIFINALS'`
+ Los dos primeros atributos: `round = 'SEMIFINALS' AND bracket = 'UPPER'`
+ Los tres atributos: `round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId = 'match-002'`
**Patrones no válidos:**
+ Omisión del primer atributo: `bracket = 'UPPER'` (se salta)
+ La consulta está fuera de orden: `matchId = 'match-002' AND round = 'SEMIFINALS'`
+ Dejar huecos: `round = 'SEMIFINALS' AND matchId = 'match-002'` (se salta el corchete)
**nota**
**Consejo de diseño:** ordene los atributos de la clave de clasificación desde los más generales hasta los más específicos para maximizar la flexibilidad de las consultas.
### Paso 5: uso de las condiciones de desigualdad en las claves de clasificación del índice secundario global
Las condiciones de desigualdad deben ser la última condición de la consulta. En este ejemplo, se muestra el uso de los operadores de comparación (`>=`, `BETWEEN`) y la coincidencia de prefijos (`begins_with()`) en los atributos de las claves de clasificación. Una vez que utilice un operador de desigualdad, no podrá agregar ninguna condición de clave de clasificación adicional después de este; la desigualdad debe ser la condición final de la expresión de condición de la clave.
#### Ejemplo de código
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: Round comparison (inequality on first sort key attribute)
console.log("Query 1: Matches from QUARTERFINALS onwards");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round >= :round',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'QUARTERFINALS'
}
}));
console.log(` Found ${query1.Items.length} matches\n`);
// Query 2: Round range with BETWEEN
console.log("Query 2: Matches between QUARTERFINALS and SEMIFINALS");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round BETWEEN :start AND :end',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':start': 'QUARTERFINALS',
':end': 'SEMIFINALS'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Prefix matching with begins_with (treated as inequality)
console.log("Query 3: Matches in brackets starting with 'U'");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND begins_with(bracket, :prefix)',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':prefix': 'U'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: INVALID - condition after inequality
console.log("Query 4: Attempting condition after inequality (WILL FAIL)");
try {
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round > :round AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'QUARTERFINALS',
':bracket': 'UPPER'
}
}));
} catch (error) {
console.log(` Error: ${error.message}`);
console.log(` Cannot add conditions after inequality - it must be last\n`);
}
```
**Reglas de operadores de desigualdad:** puede usar operadores de comparación (`>`, `>=`, `<`, `<=`) `BETWEEN` para consultas de rango y `begins_with()` para hacer coincidir prefijos. La desigualdad deben ser la última condición de la consulta.
**Patrones validos:**
+ Condiciones de igualdad seguidas de desigualdad: `round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId > 'match-001'`
+ Desigualdad en el primer atributo: `round BETWEEN 'QUARTERFINALS' AND 'SEMIFINALS'`
+ La coincidencia de prefijos como condición final: `round = 'SEMIFINALS' AND begins_with(bracket, 'U')`
**Patrones no válidos:**
+ Agregación de condiciones después de una desigualdad: `round > 'QUARTERFINALS' AND bracket = 'UPPER'`
+ Uso de múltiples desigualdades: `round > 'QUARTERFINALS' AND bracket > 'L'`
**importante**
`begins_with()` se trata como una condición de desigualdad, por lo que no puede seguirla ninguna condición de clave de clasificación adicional.
### Paso 6: consulta del índice secundario global PlayerMatchHistoryIndex con la clave de clasificación de varios atributos
En este ejemplo, se consulta el PlayerMatchHistoryIndex, que tiene una clave de partición única (`player1Id`) y una clave de clasificación de varios atributos (`matchDate` \$1 `round`). Esto permite analizar todos los torneos consultando todos los partidos de un jugador específico sin conocer los ID del torneo, mientras que la tabla base requeriría consultas independientes por combinación de torneo y región.
#### Ejemplo de código
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: All matches for Player 101 across all tournaments
console.log("Query 1: All matches for Player 101");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player',
ExpressionAttributeValues: {
':player': '101'
}
}));
console.log(` Found ${query1.Items.length} matches for Player 101:`);
query1.Items.forEach(match => {
console.log(` ${match.tournamentId}/${match.region} - ${match.matchDate} - ${match.round}`);
});
console.log();
// Query 2: Player 101 matches on specific date
console.log("Query 2: Player 101 matches on 2024-01-18");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate = :date',
ExpressionAttributeValues: {
':player': '101',
':date': '2024-01-18'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Player 101 SEMIFINALS matches on specific date
console.log("Query 3: Player 101 SEMIFINALS matches on 2024-01-18");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate = :date AND round = :round',
ExpressionAttributeValues: {
':player': '101',
':date': '2024-01-18',
':round': 'SEMIFINALS'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: Player 101 matches in date range
console.log("Query 4: Player 101 matches in January 2024");
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate BETWEEN :start AND :end',
ExpressionAttributeValues: {
':player': '101',
':start': '2024-01-01',
':end': '2024-01-31'
}
}));
console.log(` Found ${query4.Items.length} matches\n`);
```
## Variaciones de patrones
### Datos de series temporales con claves de varios atributos
Optimización de las consultas de series temporales con atributos temporales jerárquicos
#### Ejemplo de código
```
{
TableName: 'IoTReadings',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'readingId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'readingId', AttributeType: 'S' },
{ AttributeName: 'deviceId', AttributeType: 'S' },
{ AttributeName: 'locationId', AttributeType: 'S' },
{ AttributeName: 'year', AttributeType: 'S' },
{ AttributeName: 'month', AttributeType: 'S' },
{ AttributeName: 'day', AttributeType: 'S' },
{ AttributeName: 'timestamp', AttributeType: 'S' }
],
// GSI with multi-attribute keys for time-series queries
GlobalSecondaryIndexes: [{
IndexName: 'DeviceLocationTimeIndex',
KeySchema: [
{ AttributeName: 'deviceId', KeyType: 'HASH' },
{ AttributeName: 'locationId', KeyType: 'HASH' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' },
{ AttributeName: 'day', KeyType: 'RANGE' },
{ AttributeName: 'timestamp', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}
// Query patterns enabled via GSI:
// - All readings for device in location
// - Readings for specific year
// - Readings for specific month in year
// - Readings for specific day
// - Readings in time range
```
**Beneficios:** la jerarquía temporal natural (año → mes → día → marca temporal) permite realizar consultas eficientes con una granularidad en cualquier momento sin necesidad de analizar ni manipular la fecha. El índice secundario global indexa automáticamente todas las lecturas con sus atributos de tiempo natural.
### Pedidos de comercio electrónico con claves de varios atributos
Realización de un seguimiento de los pedidos con múltiples dimensiones
#### Ejemplo de código
```
{
TableName: 'Orders',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'orderId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'orderId', AttributeType: 'S' },
{ AttributeName: 'sellerId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'orderDate', AttributeType: 'S' },
{ AttributeName: 'category', AttributeType: 'S' },
{ AttributeName: 'customerId', AttributeType: 'S' },
{ AttributeName: 'orderStatus', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'SellerRegionIndex',
KeySchema: [
{ AttributeName: 'sellerId', KeyType: 'HASH' },
{ AttributeName: 'region', KeyType: 'HASH' },
{ AttributeName: 'orderDate', KeyType: 'RANGE' },
{ AttributeName: 'category', KeyType: 'RANGE' },
{ AttributeName: 'orderId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'CustomerOrdersIndex',
KeySchema: [
{ AttributeName: 'customerId', KeyType: 'HASH' },
{ AttributeName: 'orderDate', KeyType: 'RANGE' },
{ AttributeName: 'orderStatus', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// SellerRegionIndex GSI queries:
// - Orders by seller and region
// - Orders by seller, region, and date
// - Orders by seller, region, date, and category
// CustomerOrdersIndex GSI queries:
// - Customer's orders
// - Customer's orders by date
// - Customer's orders by date and status
```
### Datos de organización jerárquica
Jerarquías organizativas de modelos
#### Ejemplo de código
```
{
TableName: 'Employees',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'employeeId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'employeeId', AttributeType: 'S' },
{ AttributeName: 'companyId', AttributeType: 'S' },
{ AttributeName: 'divisionId', AttributeType: 'S' },
{ AttributeName: 'departmentId', AttributeType: 'S' },
{ AttributeName: 'teamId', AttributeType: 'S' },
{ AttributeName: 'skillCategory', AttributeType: 'S' },
{ AttributeName: 'skillLevel', AttributeType: 'S' },
{ AttributeName: 'yearsExperience', AttributeType: 'N' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'OrganizationIndex',
KeySchema: [
{ AttributeName: 'companyId', KeyType: 'HASH' },
{ AttributeName: 'divisionId', KeyType: 'HASH' },
{ AttributeName: 'departmentId', KeyType: 'RANGE' },
{ AttributeName: 'teamId', KeyType: 'RANGE' },
{ AttributeName: 'employeeId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'SkillsIndex',
KeySchema: [
{ AttributeName: 'skillCategory', KeyType: 'HASH' },
{ AttributeName: 'skillLevel', KeyType: 'RANGE' },
{ AttributeName: 'yearsExperience', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'INCLUDE', NonKeyAttributes: ['employeeId', 'name'] }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// OrganizationIndex GSI query patterns:
// - All employees in company/division
// - Employees in specific department
// - Employees in specific team
// SkillsIndex GSI query patterns:
// - Employees by skill and experience level
```
### Claves dispersas de varios atributos
Combinación de claves de varios atributos para crear un GSI disperso
#### Ejemplo de código
```
{
TableName: 'Products',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'productId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'productId', AttributeType: 'S' },
{ AttributeName: 'categoryId', AttributeType: 'S' },
{ AttributeName: 'subcategoryId', AttributeType: 'S' },
{ AttributeName: 'averageRating', AttributeType: 'N' },
{ AttributeName: 'reviewCount', AttributeType: 'N' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'CategoryIndex',
KeySchema: [
{ AttributeName: 'categoryId', KeyType: 'HASH' },
{ AttributeName: 'subcategoryId', KeyType: 'HASH' },
{ AttributeName: 'productId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'ReviewedProductsIndex',
KeySchema: [
{ AttributeName: 'categoryId', KeyType: 'HASH' },
{ AttributeName: 'averageRating', KeyType: 'RANGE' }, // Optional attribute
{ AttributeName: 'reviewCount', KeyType: 'RANGE' } // Optional attribute
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// Only products with reviews appear in ReviewedProductsIndex GSI
// Automatic filtering without application logic
// Multi-attribute sort key enables rating and count queries
```
### Multitenencia de SaaS
Plataforma SaaS multiusuario con aislamiento de clientes
#### Ejemplo de código
```
// Table design
{
TableName: 'SaasData',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'resourceId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'resourceId', AttributeType: 'S' },
{ AttributeName: 'tenantId', AttributeType: 'S' },
{ AttributeName: 'customerId', AttributeType: 'S' },
{ AttributeName: 'resourceType', AttributeType: 'S' }
],
// GSI with multi-attribute keys for tenant-customer isolation
GlobalSecondaryIndexes: [{
IndexName: 'TenantCustomerIndex',
KeySchema: [
{ AttributeName: 'tenantId', KeyType: 'HASH' },
{ AttributeName: 'customerId', KeyType: 'HASH' },
{ AttributeName: 'resourceType', KeyType: 'RANGE' },
{ AttributeName: 'resourceId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}
// Query GSI: All resources for tenant T001, customer C001
const resources = await docClient.send(new QueryCommand({
TableName: 'SaasData',
IndexName: 'TenantCustomerIndex',
KeyConditionExpression: 'tenantId = :tenant AND customerId = :customer',
ExpressionAttributeValues: {
':tenant': 'T001',
':customer': 'C001'
}
}));
// Query GSI: Specific resource type for tenant/customer
const documents = await docClient.send(new QueryCommand({
TableName: 'SaasData',
IndexName: 'TenantCustomerIndex',
KeyConditionExpression: 'tenantId = :tenant AND customerId = :customer AND resourceType = :type',
ExpressionAttributeValues: {
':tenant': 'T001',
':customer': 'C001',
':type': 'document'
}
}));
```
**Beneficios:** consultas eficientes en el contexto de inquilino-cliente y organización natural de los datos.
### Transacciones financieras
Sistema bancario que rastrea las transacciones de las cuentas mediante GSI
#### Ejemplo de código
```
// Table design
{
TableName: 'BankTransactions',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'transactionId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'transactionId', AttributeType: 'S' },
{ AttributeName: 'accountId', AttributeType: 'S' },
{ AttributeName: 'year', AttributeType: 'S' },
{ AttributeName: 'month', AttributeType: 'S' },
{ AttributeName: 'day', AttributeType: 'S' },
{ AttributeName: 'transactionType', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'AccountTimeIndex',
KeySchema: [
{ AttributeName: 'accountId', KeyType: 'HASH' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' },
{ AttributeName: 'day', KeyType: 'RANGE' },
{ AttributeName: 'transactionId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'TransactionTypeIndex',
KeySchema: [
{ AttributeName: 'accountId', KeyType: 'HASH' },
{ AttributeName: 'transactionType', KeyType: 'RANGE' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// Query AccountTimeIndex GSI: All transactions for account in 2023
const yearTransactions = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'AccountTimeIndex',
KeyConditionExpression: 'accountId = :account AND #year = :year',
ExpressionAttributeNames: { '#year': 'year' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':year': '2023'
}
}));
// Query AccountTimeIndex GSI: Transactions in specific month
const monthTransactions = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'AccountTimeIndex',
KeyConditionExpression: 'accountId = :account AND #year = :year AND #month = :month',
ExpressionAttributeNames: { '#year': 'year', '#month': 'month' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':year': '2023',
':month': '11'
}
}));
// Query TransactionTypeIndex GSI: Deposits in 2023
const deposits = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'TransactionTypeIndex',
KeyConditionExpression: 'accountId = :account AND transactionType = :type AND #year = :year',
ExpressionAttributeNames: { '#year': 'year' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':type': 'deposit',
':year': '2023'
}
}));
```
## Ejemplo completo
El siguiente ejemplo muestra las claves de varios atributos desde la configuración hasta la limpieza:
### Ejemplo de código
```
import {
DynamoDBClient,
CreateTableCommand,
DeleteTableCommand,
waitUntilTableExists
} from "@aws-sdk/client-dynamodb";
import {
DynamoDBDocumentClient,
PutCommand,
QueryCommand
} from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
async function multiAttributeKeysDemo() {
console.log("Starting Multi-Attribute GSI Keys Demo\n");
// Step 1: Create table with GSIs using multi-attribute keys
console.log("1. Creating table with multi-attribute GSI keys...");
await client.send(new CreateTableCommand({
TableName: 'TournamentMatches',
KeySchema: [
{ AttributeName: 'matchId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'matchId', AttributeType: 'S' },
{ AttributeName: 'tournamentId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'round', AttributeType: 'S' },
{ AttributeName: 'bracket', AttributeType: 'S' },
{ AttributeName: 'player1Id', AttributeType: 'S' },
{ AttributeName: 'matchDate', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'TournamentRegionIndex',
KeySchema: [
{ AttributeName: 'tournamentId', KeyType: 'HASH' },
{ AttributeName: 'region', KeyType: 'HASH' },
{ AttributeName: 'round', KeyType: 'RANGE' },
{ AttributeName: 'bracket', KeyType: 'RANGE' },
{ AttributeName: 'matchId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'PlayerMatchHistoryIndex',
KeySchema: [
{ AttributeName: 'player1Id', KeyType: 'HASH' },
{ AttributeName: 'matchDate', KeyType: 'RANGE' },
{ AttributeName: 'round', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}));
await waitUntilTableExists({ client, maxWaitTime: 120 }, { TableName: 'TournamentMatches' });
console.log("Table created\n");
// Step 2: Insert tournament matches
console.log("2. Inserting tournament matches...");
const matches = [
{ matchId: 'match-001', tournamentId: 'WINTER2024', region: 'NA-EAST', round: 'FINALS', bracket: 'CHAMPIONSHIP', player1Id: '101', player2Id: '103', matchDate: '2024-01-20', winner: '101', score: '3-1' },
{ matchId: 'match-002', tournamentId: 'WINTER2024', region: 'NA-EAST', round: 'SEMIFINALS', bracket: 'UPPER', player1Id: '101', player2Id: '105', matchDate: '2024-01-18', winner: '101', score: '3-2' },
{ matchId: 'match-003', tournamentId: 'WINTER2024', region: 'NA-WEST', round: 'FINALS', bracket: 'CHAMPIONSHIP', player1Id: '102', player2Id: '104', matchDate: '2024-01-20', winner: '102', score: '3-2' },
{ matchId: 'match-004', tournamentId: 'SPRING2024', region: 'NA-EAST', round: 'QUARTERFINALS', bracket: 'UPPER', player1Id: '101', player2Id: '108', matchDate: '2024-03-15', winner: '101', score: '3-0' }
];
for (const match of matches) {
await docClient.send(new PutCommand({ TableName: 'TournamentMatches', Item: match }));
}
console.log(`Inserted ${matches.length} tournament matches\n`);
// Step 3: Query GSI with multi-attribute partition key
console.log("3. Query TournamentRegionIndex GSI: WINTER2024/NA-EAST matches");
const gsiQuery1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
ExpressionAttributeNames: { '#region': 'region' },
ExpressionAttributeValues: { ':tournament': 'WINTER2024', ':region': 'NA-EAST' }
}));
console.log(` Found ${gsiQuery1.Items.length} matches:`);
gsiQuery1.Items.forEach(match => {
console.log(` ${match.round} - ${match.bracket} - ${match.winner} won`);
});
// Step 4: Query GSI with multi-attribute sort key
console.log("\n4. Query PlayerMatchHistoryIndex GSI: All matches for Player 101");
const gsiQuery2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player',
ExpressionAttributeValues: { ':player': '101' }
}));
console.log(` Found ${gsiQuery2.Items.length} matches for Player 101:`);
gsiQuery2.Items.forEach(match => {
console.log(` ${match.tournamentId}/${match.region} - ${match.matchDate} - ${match.round}`);
});
console.log("\nDemo complete");
console.log("No synthetic keys needed - GSIs use native attributes automatically");
}
async function cleanup() {
console.log("Deleting table...");
await client.send(new DeleteTableCommand({ TableName: 'TournamentMatches' }));
console.log("Table deleted");
}
// Run demo
multiAttributeKeysDemo().catch(console.error);
// Uncomment to cleanup:
// cleanup().catch(console.error);
```
**Estructura de código mínima**
### Ejemplo de código
```
// 1. Create table with GSI using multi-attribute keys
await client.send(new CreateTableCommand({
TableName: 'MyTable',
KeySchema: [
{ AttributeName: 'id', KeyType: 'HASH' } // Simple base table PK
],
AttributeDefinitions: [
{ AttributeName: 'id', AttributeType: 'S' },
{ AttributeName: 'attr1', AttributeType: 'S' },
{ AttributeName: 'attr2', AttributeType: 'S' },
{ AttributeName: 'attr3', AttributeType: 'S' },
{ AttributeName: 'attr4', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [{
IndexName: 'MyGSI',
KeySchema: [
{ AttributeName: 'attr1', KeyType: 'HASH' }, // GSI PK attribute 1
{ AttributeName: 'attr2', KeyType: 'HASH' }, // GSI PK attribute 2
{ AttributeName: 'attr3', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'attr4', KeyType: 'RANGE' } // GSI SK attribute 2
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}));
// 2. Insert items with native attributes (no concatenation needed for GSI)
await docClient.send(new PutCommand({
TableName: 'MyTable',
Item: {
id: 'item-001',
attr1: 'value1',
attr2: 'value2',
attr3: 'value3',
attr4: 'value4',
// ... other attributes
}
}));
// 3. Query GSI with all partition key attributes
await docClient.send(new QueryCommand({
TableName: 'MyTable',
IndexName: 'MyGSI',
KeyConditionExpression: 'attr1 = :v1 AND attr2 = :v2',
ExpressionAttributeValues: {
':v1': 'value1',
':v2': 'value2'
}
}));
// 4. Query GSI with sort key attributes (left-to-right)
await docClient.send(new QueryCommand({
TableName: 'MyTable',
IndexName: 'MyGSI',
KeyConditionExpression: 'attr1 = :v1 AND attr2 = :v2 AND attr3 = :v3',
ExpressionAttributeValues: {
':v1': 'value1',
':v2': 'value2',
':v3': 'value3'
}
}));
// Note: If any attribute name is a DynamoDB reserved keyword, use ExpressionAttributeNames:
// KeyConditionExpression: 'attr1 = :v1 AND #attr2 = :v2'
// ExpressionAttributeNames: { '#attr2': 'attr2' }
```
## Recursos adicionales
+ [Prácticas recomendadas de DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html)
+ [Uso de tablas y datos](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.html)
+ [Índices secundarios globales](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html)
+ [Operaciones de consulta y análisis](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html)
# Administración de índices secundarios globales en DynamoDB
En esta sección se describe cómo crear, modificar y eliminar índices secundarios globales en Amazon DynamoDB.
**Topics**
+ [Creación de una tabla con índices secundarios globales](#GSI.Creating)
+ [Descripción de los índices secundarios globales en una tabla](#GSI.Describing)
+ [Adición de un índice secundario global a una tabla existente](#GSI.OnlineOps.Creating)
+ [Eliminación de un índice secundario global](#GSI.OnlineOps.Deleting)
+ [Modificación de un índice secundario global durante la creación](#GSI.OnlineOps.Creating.Modify)
## Creación de una tabla con índices secundarios globales
Para crear una tabla con uno o varios índices secundarios globales, use la operación `CreateTable` con el parámetro `GlobalSecondaryIndexes`. Para disfrutar de la máxima flexibilidad en las consultas, puede crear hasta 20 índices secundarios globales (cuota predeterminada) por tabla.
Debe especificar un atributo que actúe como clave de partición del índice. También tiene la opción de especificar otro atributo para la clave de ordenación del índice. No es necesario que ninguno de estos atributos de clave sea igual que un atributo de clave de la tabla. Por ejemplo, en la tabla *GameScores* (consulte [Uso de índices secundarios globales en DynamoDB](GSI.md)), ni `TopScore` ni `TopScoreDateTime` son atributos de clave. Puede crear un índice secundario global que tenga una clave de partición de `TopScore` y una clave de ordenación de `TopScoreDateTime`. Se podría usar un índice de este tipo para determinar si existe una correlación entre las mejores puntuaciones y la hora del día a la que se juega.
Todos los atributos de clave del índice deben ser escalares y pueden ser de tipo `String`, `Number` o `Binary`. No pueden ser documentos ni conjuntos. Puede proyectar atributos de cualquier tipo de datos en un índice secundario global. Esto incluye escalares, documentos y conjuntos. Para obtener una lista completa de los tipos de datos, consulte [Tipos de datos](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes).
Si usa el modo aprovisionado, debe proporcionar para el índice los ajustes de `ProvisionedThroughput`, que constan de `ReadCapacityUnits` y `WriteCapacityUnits`. Estos ajustes de rendimiento aprovisionado son independientes de los de la tabla pero se comportan de forma parecida. Para obtener más información, consulte [Consideraciones sobre el rendimiento aprovisionado para los índices secundarios globales](GSI.md#GSI.ThroughputConsiderations).
Los índices secundarios globales heredan el modo de capacidad de lectura/escritura de la tabla base. Para obtener más información, consulte [Aspectos a tener en cuenta al cambiar los modos de capacidad en DynamoDB](bp-switching-capacity-modes.md).
**nota**
Al crear un nuevo índice secundario global, resulta importante verificar si la elección de clave de partición produce una distribución desigual o restringida de datos o tráfico entre los valores de clave de partición del nuevo índice. Si esto ocurre, podría ver operaciones de reposición y escritura que se producen al mismo tiempo y que se limiten las escrituras en la tabla base. El servicio adopta medidas para minimizar el potencial de este escenario, pero no tiene información de la forma de los datos del cliente con respecto a la clave de partición de índice, la proyección elegida o la escasez de la clave principal del índice.
Si sospecha que el nuevo índice secundario global puede tener datos estrechos o sesgados, o bien una distribución del tráfico entre los valores clave de partición, tenga en cuenta lo siguiente antes de agregar nuevos índices a tablas importantes desde el punto de vista operativo.
Es posible que sea más seguro agregar el índice en un momento en que la aplicación esté generando la menor cantidad de tráfico.
Considere la posibilidad de habilitar CloudWatch Contributor Insights en la tabla base y los índices. Esto le proporcionará información valiosa sobre la distribución del tráfico.
Vea las métricas de `WriteThrottleEvents`, `ThrottledRequests` y `OnlineIndexPercentageProgress` de CloudWatch durante todo el proceso. Ajuste la capacidad de escritura aprovisionada según sea necesario para completar la reposición en un tiempo razonable sin ningún efecto de limitación significativo en las operaciones en curso. Se espera que `OnlineIndexConsumedWriteCapacity` y `OnlineThrottleEvents` muestren 0 durante la reposición del índice.
Prepárese para cancelar la creación del índice si experimenta un impacto operativo debido a la limitación de escritura.
## Descripción de los índices secundarios globales en una tabla
Para ver el estado de todos los índices secundarios globales de una tabla, se usa la operación `DescribeTable`. La parte `GlobalSecondaryIndexes` de la respuesta enumera todos los índices de la tabla, junto con el estado actual de cada uno de ellos (`IndexStatus`).
El `IndexStatus` para un índice secundario global será uno de los siguientes:
+ `CREATING`: el índice está en proceso de creación y aún no está disponible para usarlo.
+ `ACTIVE`: el índice está listo para usarlo y las aplicaciones pueden realizar operaciones `Query` en él.
+ `UPDATING`: se están cambiando los ajustes de desempeño provisionado del índice.
+ `DELETING`: el índice se está eliminando y ya no se puede utilizar.
Cuando DynamoDB ha terminado de crear un índice secundario global, el estado de este último cambia de `CREATING` a `ACTIVE`.
## Adición de un índice secundario global a una tabla existente
Para agregar un índice secundario global a una tabla existente, se usa la operación `UpdateTable` con el parámetro `GlobalSecondaryIndexUpdates`. Debe proporcionar lo siguiente:
+ El nombre del índice. Este nombre debe ser único entre todos los índices de la tabla.
+ El esquema de claves del índice. Debe especificar un atributo para la clave de partición del índice y, si lo desea, otro atributo para la clave de ordenación del índice. No es necesario que ninguno de estos atributos de clave sea igual que un atributo de clave de la tabla. Los tipos de datos de cada atributo del esquema deben ser escalares: `String`, `Number` o `Binary`.
+ Los atributos de la tabla que se van a proyectar en el índice:
+ `KEYS_ONLY`: cada elemento del índice consta únicamente de los valores de la clave de partición y la clave de ordenación de la tabla, así como de los valores de las claves del índice.
+ `INCLUDE`: además de los atributos que se describen en `KEYS_ONLY`, el índice secundario incluye otros atributos sin clave que se especifiquen.
+ `ALL`: el índice incluye todos los atributos de la tabla de origen.
+ Los ajustes de rendimiento aprovisionado del índice, que constan de `ReadCapacityUnits` y `WriteCapacityUnits`. Estos ajustes de rendimiento aprovisionado son independientes de los de la tabla.
Solo puede crear un índice secundario global por operación `UpdateTable`.
### Fases de creación del índice
Cuando se agrega un nuevo índice secundario global a una tabla existente, la tabla sigue estando disponible mientras se crea el índice. Sin embargo, el nuevo índice no estará disponible para las operaciones de consulta hasta que el estado cambie de `CREATING` a `ACTIVE`.
**nota**
La creación de índices secundarios globales no utiliza Application Auto Scaling. El aumento de la capacidad de `MIN` de Application Auto Scaling no disminuirá el tiempo de creación del índice secundario global.
En segundo plano, DynamoDB crea el índice en dos fases:
**Asignación de recursos**
DynamoDB asigna los recursos informáticos y de almacenamiento que se necesitan para crear el índice.
Durante la fase de asignación de recursos, el valor del atributo `IndexStatus` es `CREATING` y el valor del atributo `Backfilling` es false. Use la operación `DescribeTable` para recuperar el estado de una tabla y todos sus índices secundarios.
Mientras el índice se encuentra en la fase de asignación de recursos, no se puede eliminar el índice ni eliminar su tabla principal. Tampoco se puede modificar el rendimiento aprovisionado del índice ni de la tabla. No se pueden agregar ni eliminar otros índices de la tabla. Sin embargo, se puede modificar el rendimiento aprovisionado de estos otros índices.
**Reposición**
Para cada elemento de la tabla, DynamoDB determina el conjunto de atributos que se escribirá en el índice según su proyección (`KEYS_ONLY`, `INCLUDE` o `ALL`). A continuación, escribe estos atributos en el índice. Durante la fase de reposición, DynamoDB lleva un seguimiento de los elementos que se agregan, eliminan o actualizan en la tabla. Los atributos de estos elementos también se agregan, eliminan o actualizan en el índice, según proceda.
Durante la fase de reposición, el atributo `IndexStatus` está establecido en `CREATING` y el atributo `Backfilling` está establecido en true. Use la operación `DescribeTable` para recuperar el estado de una tabla y todos sus índices secundarios.
Mientras el índice se encuentra en la fase de reposición, no se puede eliminar su tabla principal. Sin embargo, sí se puede eliminar el índice o modificar el rendimiento aprovisionado de la tabla y de cualquiera de sus índices secundarios globales.
Durante la fase de reposición, algunas escrituras de elementos infractores podrían realizarse correctamente y otras se rechazarán. Después de la reposición, se rechazarán todas las escrituras en elementos que infrinjan el esquema de claves del nuevo índice. Recomendamos ejecutar la herramienta Violation Detector una vez que haya finalizado la fase de reposición para detectar y resolver cualquier infracción de clave que pueda haberse producido. Para obtener más información, consulte [Detección y corrección de infracciones de la clave del índice en DynamoDB](GSI.OnlineOps.ViolationDetection.md).
Mientras las fases de asignación de recursos y reposición están en curso, el índice se encuentra en el estado `CREATING`. Durante este plazo de tiempo, DynamoDB realiza operaciones de lectura en al tabla. No se le cobrará por las operaciones de lectura de la tabla base para rellenar el índice secundario global.
Una vez que se completa la creación del índice, su estado cambia a `ACTIVE`. No puede `Query` ni `Scan` el índice hasta que esté `ACTIVE`.
**nota**
En algunos casos, DynamoDB no puede escribir datos de la tabla en el índice porque se producen infracciones en las claves del índice. Esto puede ocurrir si:
El tipo de dato de un valor de atributo no coincide con el del esquema de claves de índice.
El tamaño de un atributo supera la longitud máxima de un atributo de clave del índice.
Un atributo de clave del índice tiene un valor binario o de cadena vacío.
Las infracciones de claves del índice no interfieren con la creación de un índice secundario global. Sin embargo, cuando el índice adquiera el estado `ACTIVE`, las claves infractoras no estarán presentes en él.
DynamoDB proporciona una herramienta independiente para encontrar y resolver estos problemas. Para obtener más información, consulte [Detección y corrección de infracciones de la clave del índice en DynamoDB](GSI.OnlineOps.ViolationDetection.md).
### Adición de un índice secundario global a una tabla grande
El tiempo necesario para crear un índice secundario global depende de varios factores, como los siguientes:
+ El tamaño de la tabla.
+ El número de elementos de la tabla que son aptos para incluirlos en el índice.
+ El número de atributos que se proyectan en el índice.
+ La actividad de escritura en la tabla principal mientras se crean los índices.
Si se va a agregar un índice secundario global a una tabla muy grande, el proceso de creación puede tardar mucho tiempo en completarse. Para monitorear el progreso y determinar si el índice tiene suficiente capacidad de escritura, consulte las siguientes métricas de Amazon CloudWatch:
+ `OnlineIndexPercentageProgress`
Para obtener más información acerca de cómo las métricas de CloudWatch se relacionan con DynamoDB, consulte [Métricas de DynamoDB](metrics-dimensions.md#dynamodb-metrics).
**importante**
Es posible que tenga que permitir listas de tablas muy grandes antes de crear o actualizar un índice secundario global. Póngase en contacto con AWS Support para incluir las tablas en la lista de permitidos.
Mientras el índice está en la fase de reposición, DynamoDB utiliza la capacidad interna del sistema para leer la tabla. Esto permite minimizar el impacto de la creación del índice y asegurarse de que no se agote la capacidad de lectura de la tabla.
## Eliminación de un índice secundario global
Si ya no necesita un índice secundario global, puede eliminarlo mediante la ooperación `UpdateTable`.
Solo se puede eliminar un índice secundario global por operación `UpdateTable`.
Mientras se elimina el índice secundario global, no afecta en absoluto a la actividad de lectura o escritura en la tabla principal. Mientras la eliminación está en curso, puede modificar el rendimiento aprovisionado de los demás índices.
**nota**
Al eliminar una tabla mediante la acción `DeleteTable`, todos los índices secundarios globales de esa tabla se eliminan también.
No se cargará en su cuenta la operación de eliminación del índice secundario global.
## Modificación de un índice secundario global durante la creación
Mientras se está creando un índice, puede usar la operación `DescribeTable` para determinar en qué fase se encuentra. La descripción del índice incluye un atributo de tipo Boolean, `Backfilling`, que indica si DynamoDB está cargando elementos de la tabla en el índice en un momento dado. Si `Backfilling` es true, significa que la fase de asignación de recursos se ha completado y el índice se encuentra en la fase de reposición.
Durante la fase de reposición, puede eliminar el índice que se está creando. Durante esta fase, no se pueden agregar ni eliminar otros índices de la tabla.
**nota**
En el caso de los índices que se han creado como parte de una operación `CreateTable`, el atributo `Backfilling` no aparece en el resultado de `DescribeTable`. Para obtener más información, consulte [Fases de creación del índice](#GSI.OnlineOps.Creating.Phases).
# Detección y corrección de infracciones de la clave del índice en DynamoDB
Durante la fase de reposición de la creación de un índice secundario global, Amazon DynamoDB examina cada elemento de la tabla para determinar si es apto para incluirlo en el índice. Algunos elementos podrían no ser aptos por la posibilidad de que causen infracciones de claves de índice. En estos casos, el elemento en cuestión permanecen en la tabla, pero el índice no incluye la entrada correspondiente a dicho elemento.
Un registro *infracción de clave de índice* se produce en las siguientes situaciones:
+ Los tipos de datos del valor de un atributo y del esquema de claves del índice no coinciden. Por ejemplo, supongamos que uno de los elementos de la tabla `GameScores` tiene un atributo `TopScore` cuyo valor es de tipo `String`. Si agrega un índice secundario global con una clave de partición de `TopScore` de tipo `Number`, el elemento de la tabla infringiría la clave de índice.
+ El valor de atributo de la tabla supera la longitud máxima de un atributo de clave del índice. La longitud máxima de una clave de partición es de 2048 bytes y la longitud máxima de una clave de ordenación es de 1024 bytes. Si cualquiera de los valores de atributos correspondientes de la tabla supera estos límites, el elemento de la tabla infringiría la clave de índice.
**nota**
Si se establece un valor binario o de cadena en un atributo que se utiliza como clave de índice, este valor debe tener una longitud mayor que cero; de lo contrario, el elemento de la tabla podría infringir la clave del índice.
En la actualidad, esta herramienta no indica esta infracción de clave de índice de ninguna forma.
Si se produce una infracción de índice, la fase de reposición continúa sin interrupción. Sin embargo, los elementos infractores no se incluyen en el índice. Una vez que haya finalizado la fase de reposición, se rechazarán todas las escrituras en elementos que infringen el esquema de claves del nuevo índice.
Para identificar y corregir los valores de los atributos de una tabla que infringen una clave de índice, se utiliza la herramienta Violation Detector. Para ejecutar Violation Detector, debe crear un archivo de configuración que especifique el nombre de la tabla que se va a examinar, los nombres y los tipos de datos de las claves de partición y de ordenación del índice secundario global y qué medidas deben adoptarse si se detecta cualquier infracción de clave de índice. Violation Detector puede ejecutarse en dos modos diferentes:
+ **Modo de detección**: detecta las infracciones de claves de índice. El modo de detección se utiliza para registrar los elementos de la tabla que causarían infracciones de claves en un índice secundario global. (Si lo desea, puede solicitar que estos elementos infractores de la tabla se eliminen de inmediato en cuanto se encuentren). El resultado del modo de detección se escribe en un archivo, que se puede utilizar para analizar los datos posteriormente.
+ **Modo de corrección**: corrige las infracciones de claves de índice. En el modo de corrección, Violation Detector lee un archivo de información de entrada con el mismo formato que el archivo de resultados del modo de detección. En el modo de corrección se leen los registros del archivo de información de entrada y, para cada registro, se elimina o actualiza el elemento correspondiente de la tabla. Tenga en cuenta que si decide actualizar los elementos, deberá editar el archivo de información de entrada y establecer valores adecuados para estas actualizaciones.
## Descargar y ejecutar Violation Detector
Violation Detector está disponible como archivo Java ejecutable (`.jar`) y se ejecuta en ordenadores Windows, Mac o Linux. Violation Detector requiere Java 1.7 (o posterior) y Apache Maven.
+ [Descargar Violation Detector de GitHub](https://github.com/awslabs/dynamodb-online-index-violation-detector)
Siga las instrucciones del archivo `README.md` para descargar e instalar Violation Detector mediante Maven.
Para iniciar Violation Detector, vaya al directorio donde ha construido `ViolationDetector.java` e ingrese el siguiente comando.
```
java -jar ViolationDetector.jar [options]
```
La línea de comandos de Violation Detector acepta las siguientes opciones:
+ `-h | --help`: imprime un resumen de uso y las opciones posibles de Violation Detector.
+ `-p | --configFilePath` `value`: nombre completo de un archivo de configuración de Violation Detector. Para obtener más información, consulte [El archivo de configuración de Violation Detector](#GSI.OnlineOps.ViolationDetection.ConfigFile).
+ `-t | --detect` `value`: detecta las infracciones de claves de índice de la tabla y las escribe en el archivo de resultados de Violation Detector. Si el valor de este parámetro se establece en `keep`, los elementos con infracciones de claves no se modifican. Si el valor se establece en `delete`, los elementos con infracciones de claves se eliminan de la tabla.
+ `-c | --correct` `value`: lee las infracciones de claves de índice en un archivo de información de entrada y adopta medidas para corregir los elementos de la tabla. Si el valor de este parámetro se establece en `update`, los elementos con infracciones de claves se actualizan a otros valores sin infracciones. Si el valor se establece en `delete`, los elementos con infracciones de claves se eliminan de la tabla.
## El archivo de configuración de Violation Detector
En tiempo de ejecución, la herramienta Violation Detector requiere un archivo de configuración. Los parámetros de este archivo determinan a qué recursos de DynamoDB puede obtener acceso Violation Detector y cuánto rendimiento aprovisionado puede consumir. En la siguiente tabla se describen estos parámetros.
****
| Nombre del parámetro | Descripción | ¿Obligatorio? |
| --- | --- | --- |
| `awsCredentialsFile` | Nombre completo de un archivo que contiene las credenciales de AWS. El archivo de credenciales debe tener el siguiente formato: accessKey = access_key_id_goes_here
secretKey = secret_key_goes_here
| Sí |
| `dynamoDBRegion` | Región de AWS en la que la reside la tabla. Por ejemplo: `us-west-2`. | Sí |
| `tableName` | Nombre de la tabla de DynamoDB que se va a examinar. | Sí |
| `gsiHashKeyName` | Nombre de la clave de partición del índice. | Sí |
| `gsiHashKeyType` | Tipo de datos de la clave de partición del índice: `String`, `Number` o `Binary`: `S \| N \| B` | Sí |
| `gsiRangeKeyName` | Nombre de la clave de ordenación del índice. No especifique este parámetro si el índice solo tiene una clave principal simple (clave de partición). | No |
| `gsiRangeKeyType` | Tipo de datos de la clave de ordenación del índice: `String`, `Number` o `Binary`: `S \| N \| B` No especifique este parámetro si el índice solo tiene una clave principal simple (clave de partición). | No |
| `recordDetails` | Indica si se deben escribir todos los detalles de las infracciones de claves de índice en el archivo de resultados. Si se establece en `true` (valor predeterminado), se registra toda la información sobre los elementos infractores. Si se establece en `false`, solo se registra el número de infracciones. | No |
| `recordGsiValueInViolationRecord` | Indica si se deben escribir los valores de las claves de índice infractoras en el archivo de resultados. Si se establece en `true` (predeterminado), se registran los valores de las claves. Si se establece en `false`, los valores de las claves no se registran. | No |
| `detectionOutputPath` | Ruta completa del archivo de resultados de Violation Detector;. Este parámetro es compatible con la escritura en un directorio local o en Amazon Simple Storage Service (Amazon S3). A continuación se muestran algunos ejemplos: `detectionOutputPath = ``//local/path/filename.csv` `detectionOutputPath = ``s3://bucket/filename.csv` La información del archivo de resultados aparece en formato CSV (valores separados por comas). Si no se establece `detectionOutputPath`, el archivo de resultados se denomina `violation_detection.csv` y se escribe en el directorio de trabajo actual. | No |
| `numOfSegments` | El número de segmentos de examen en paralelo que se utilizarán cuando Violation Detector analice la tabla. El valor predeterminado es 1, lo que significa que la tabla se examina de forma secuencial. Si el valor es 2 o superior, entonces Violation Detector dividirá la tabla en esa cantidad de segmentos lógicos y un número igual de subprocesos de examen. El ajuste máximo de `numOfSegments` es 4096.En el caso de las tablas de mayor tamaño, un examen en paralelo suele resultar más rápido que un examen secuencial. Además, si la tabla es lo bastante grande para abarcar varias particiones, un examen en paralelo distribuye su actividad de lectura de manera uniforme entre varias particiones.Para obtener más información sobre los análisis en paralelo en DynamoDB, consulte [Análisis paralelo](Scan.md#Scan.ParallelScan). | No |
| `numOfViolations` | Límite superior de infracciones de claves de índice que se escribirán en el archivo de resultados. Si se establece en `-1` (valor predeterminado), se examina toda la tabla. Si se establece en un número entero positivo, entonces Violation Detector se detendrá después de haber detectado esa cantidad de infracciones. | No |
| `numOfRecords` | Número de elementos de la tabla que se va a examinar. Si se establece en -1 (valor predeterminado), se examinará toda la tabla. Si se establece en un número entero positivo, entonces Violation Detector se detendrá después de haber examinado esa cantidad de elementos en la tabla. | No |
| `readWriteIOPSPercent` | Regula el porcentaje de unidades de capacidad de lectura provisionadas que se consumen durante un examen de la tabla. Los valores válidos van de `1` a `100`. El valor predeterminado (`25`) significa que Violation Detector consumirá no más del 25 % del rendimiento de lectura aprovisionado de la tabla. | No |
| `correctionInputPath` | Ruta completa del archivo de información de entrada de corrección de Violation Detector. Si ejecuta Violation Detector en modo de corrección, el contenido de este archivo se usa para modificar o eliminar los elementos de datos de la tabla que infringen el índice secundario global. El formato del archivo `correctionInputPath` es el mismo que el del archivo `detectionOutputPath`. Esto permite procesar el resultado del modo de detección como información de entrada en el modo de corrección. | No |
| `correctionOutputPath` | Ruta completa del archivo de resultados de corrección de Violation Detector. Este archivo se crea solo si existen errores de actualización. Este parámetro es compatible con la escritura en un directorio local o en Amazon S3. A continuación se muestran algunos ejemplos: `correctionOutputPath = ``//local/path/filename.csv` `correctionOutputPath = ``s3://bucket/filename.csv` La información del archivo de resultados aparece en formato CSV. Si no se establece `correctionOutputPath`, el archivo de resultados se denomina `violation_update_errors.csv` y se escribe en el directorio de trabajo actual. | No |
## Detección
Para detectar infracciones de claves de índice, use Violation Detector con la opción de línea de comandos `--detect`. Para ver cómo funciona esta opción, tomemos la tabla `ProductCatalog`. A continuación se muestra una lista de elementos de la tabla. Solo se muestran la clave principal (`Id`) y el atributo `Price`.
****
| Id (clave principal) | Precio |
| --- | --- |
| 101 | 5 |
| 102 | 20 |
| 103 | 200 |
| 201 | 100 |
| 202 | 200 |
| 203 | 300 |
| 204 | 400 |
| 205 | 500 |
Todos los valores de `Price` son de tipo `Number`. No obstante, dado que en DynamoDB no se usan esquemas, es posible agregar un elemento con un valor de no numérico `Price`. Por ejemplo, supongamos que agrega otro elemento a la tabla `ProductCatalog`.
****
| Id (clave principal) | Precio |
| --- | --- |
| 999 | "Hello" |
Ahora, la tabla contiene un total de nueve elementos.
Ahora agrega un nuevo índice secundario global a la tabla: `PriceIndex`. La clave principal de este índice es una clave de partición, `Price`, que es de tipo `Number`. Después de crearlo, el índice contendrá ocho elementos. Sin embargo, la tabla `ProductCatalog` tiene nueve elementos. El motivo de esta discrepancia es que, aunque el valor `"Hello"` es de tipo `String`, la clave principal de `PriceIndex` es de tipo `Number`. El valor `String` infringe la clave del índice secundario global, por lo que no está presente en el índice.
Para usar Violation Detector en esta situación, primero se crea un archivo de configuración, como el siguiente.
```
# Properties file for violation detection tool configuration.
# Parameters that are not specified will use default values.
awsCredentialsFile = /home/alice/credentials.txt
dynamoDBRegion = us-west-2
tableName = ProductCatalog
gsiHashKeyName = Price
gsiHashKeyType = N
recordDetails = true
recordGsiValueInViolationRecord = true
detectionOutputPath = ./gsi_violation_check.csv
correctionInputPath = ./gsi_violation_check.csv
numOfSegments = 1
readWriteIOPSPercent = 40
```
A continuación, se ejecuta el Violation Detector como en el siguiente ejemplo.
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --detect keep
Violation detection started: sequential scan, Table name: ProductCatalog, GSI name: PriceIndex
Progress: Items scanned in total: 9, Items scanned by this thread: 9, Violations found by this thread: 1, Violations deleted by this thread: 0
Violation detection finished: Records scanned: 9, Violations found: 1, Violations deleted: 0, see results at: ./gsi_violation_check.csv
```
Si el parámetro de configuración `recordDetails` se establece en `true`, entonces Violation Detector escribe los detalles de cada infracción en el archivo de resultados, como en el siguiente ejemplo.
```
Table Hash Key,GSI Hash Key Value,GSI Hash Key Violation Type,GSI Hash Key Violation Description,GSI Hash Key Update Value(FOR USER),Delete Blank Attributes When Updating?(Y/N)
999,"{""S"":""Hello""}",Type Violation,Expected: N Found: S,,
```
El archivo de salida está en formato CSV. La primera línea del archivo es un encabezado, seguido de un registro por cada elemento que infringe la clave del índice. Los campos de estos registros de infracción son los siguientes:
+ **Table hash key**: valor de la clave de partición del elemento de la tabla.
+ **Table range key**: valor de la clave de clasificación del elemento de la tabla.
+ **GSI hash key value**: valor de la clave de partición del índice secundario global.
+ **GSI hash key violation type**: puede ser `Type Violation` o `Size Violation`.
+ **GSI hash key violation description**: causa de la infracción.
+ **GSI hash key update value (FOR USER)**: en el modo de corrección, nuevo valor suministrado por el usuario para el atributo.
+ **GSI range key values**: el valor de la clave de clasificación del índice secundario global.
+ **GSI range key violation type**: puede ser `Type Violation` o `Size Violation`.
+ **GSI range key violation description**: causa de la infracción.
+ **GSI range key update value (FOR USER)**: en el modo de corrección, nuevo valor suministrado por el usuario para el atributo.
+ **Delete blank attribute when updating (Y/N)**: en el modo de corrección, determina si el elemento infractor se eliminará (Y) o se conservará (N) en la tabla, pero solamente si cualquiera de los campos siguientes está en blanco:
+ `GSI Hash Key Update Value(FOR USER)`
+ `GSI Range Key Update Value(FOR USER)`
Si alguno de estos campos no está en blanco, entonces `Delete Blank Attribute When Updating(Y/N)` no surte ningún efecto.
**nota**
El formato de los resultados puede variar, en función del archivo de configuración y de las opciones de la línea de comandos. Por ejemplo, si la tabla tiene una clave principal simple (sin clave de ordenación), no habrá ningún campo de clave de ordenación en el resultado.
Los registros de infracción del archivo podrían no estar ordenados.
## Corrección
Para corregir infracciones de claves de índice, use Violation Detector con la opción de línea de comandos `--correct`. En el modo de corrección, Violation Detector lee el archivo de información de entrada especificado por el parámetro `correctionInputPath`. Este archivo tiene el mismo formato que el archivo `detectionOutputPath`, lo que permite utilizar el resultado de la detección como información de entrada para la corrección.
Violation Detector ofrece dos maneras distintas de corregir las infracciones de claves de índice:
+ **Eliminar las infracciones**: se eliminan los elementos de la tabla cuyos valores de atributos infringen alguna clave.
+ **Actualizar las infracciones**: se actualizan los elementos de la tabla, para lo cual se sustituyen los atributos infractores por otros que no causan ninguna infracción.
En ambos casos, puede utilizar el archivo de resultados del modo de detección como información de entrada para el modo de corrección.
Si continuamos con el ejemplo anterior de `ProductCatalog`, supongamos que desea eliminar el elemento infractor de la tabla. Para ello, utilizamos la línea de comandos siguiente.
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --correct delete
```
En este momento, le pedirá que confirme si desea eliminar los elementos infractores.
```
Are you sure to delete all violations on the table?y/n
y
Confirmed, will delete violations on the table...
Violation correction from file started: Reading records from file: ./gsi_violation_check.csv, will delete these records from table.
Violation correction from file finished: Violations delete: 1, Violations Update: 0
```
Ahora, tanto `ProductCatalog` como `PriceIndex` tienen el mismo número de elementos.
# Trabajo con índices secundarios globales: Java
Puede utilizar la API de documentos AWS SDK para Java para crear una tabla Amazon DynamoDB con uno o varios índices secundarios globales, describir los índices de la tabla y utilizarlos para realizar consultas.
A continuación se indican los pasos comunes para las operaciones con tablas.
1. Cree una instancia de la clase `DynamoDB`.
1. Cree los objetos de solicitud correspondientes para proporcionar los parámetros obligatorios y opcionales de la operación.
1. Llame al método apropiado proporcionado por el cliente que ha creado en el paso anterior.
**Topics**
+ [Creación de una tabla con un índice secundario global](#GSIJavaDocumentAPI.CreateTableWithIndex)
+ [Descripción de una tabla con un índice secundario global](#GSIJavaDocumentAPI.DescribeTableWithIndex)
+ [Consulta de un índice secundario local](#GSIJavaDocumentAPI.QueryAnIndex)
+ [Ejemplo: índices secundarios globales que utilizan la API de documentos de AWS SDK para Java](GSIJavaDocumentAPI.Example.md)
## Creación de una tabla con un índice secundario global
Puede crear índices secundarios globales a la vez que crea la tabla. Para ello, utilice `CreateTable` e indique las especificaciones para uno o varios índices secundarios globales. En el ejemplo de código Java siguiente, se crea una tabla para contener información sobre datos meteorológicos. La clave de partición es `Location` y la de ordenación, `Date`. Un índice secundario global denominado `PrecipIndex` permite obtener acceso rápido a los datos sobre precipitaciones de varias ubicaciones.
A continuación se indican los pasos que hay que seguir para crear una tabla con un índice secundario global mediante el API de documentos de DynamoDB.
1. Cree una instancia de la clase `DynamoDB`.
1. Cree una instancia de la clase `CreateTableRequest` para proporcionar la información de solicitud.
Debe proporcionar el nombre de la tabla, su clave principal y los valores de rendimiento aprovisionado. Para el índice secundario global, debe proporcionar el nombre del índice, los ajustes de rendimiento aprovisionado, las definiciones de atributos de la clave de ordenación del índice, el esquema de claves del índice y la proyección de atributos.
1. Llame al método `createTable` proporcionando el objeto de solicitud como parámetro.
En el siguiente ejemplo de código Java se muestran los pasos anteriores. El código crea una tabla (`WeatherData`) con un índice secundario global (`PrecipIndex`). La clave de partición del índice es `Date` y la de ordenación, `Precipitation`. Todos los atributos de la tabla se proyectan en el índice. Los usuarios pueden consultar este índice para obtener los datos meteorológicos de una determinada fecha y, si lo desean, ordenarlos según la cantidad de precipitación.
Ya que `Precipitation` no es un atributo de clave para la tabla, no es obligatorio. Sin embargo, los elementos`WeatherData` sin `Precipitation` no aparecen en `PrecipIndex`.
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
// Attribute definitions
ArrayList attributeDefinitions = new ArrayList();
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Location")
.withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Date")
.withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Precipitation")
.withAttributeType("N"));
// Table key schema
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement()
.withAttributeName("Location")
.withKeyType(KeyType.HASH)); //Partition key
tableKeySchema.add(new KeySchemaElement()
.withAttributeName("Date")
.withKeyType(KeyType.RANGE)); //Sort key
// PrecipIndex
GlobalSecondaryIndex precipIndex = new GlobalSecondaryIndex()
.withIndexName("PrecipIndex")
.withProvisionedThroughput(new ProvisionedThroughput()
.withReadCapacityUnits((long) 10)
.withWriteCapacityUnits((long) 1))
.withProjection(new Projection().withProjectionType(ProjectionType.ALL));
ArrayList indexKeySchema = new ArrayList();
indexKeySchema.add(new KeySchemaElement()
.withAttributeName("Date")
.withKeyType(KeyType.HASH)); //Partition key
indexKeySchema.add(new KeySchemaElement()
.withAttributeName("Precipitation")
.withKeyType(KeyType.RANGE)); //Sort key
precipIndex.setKeySchema(indexKeySchema);
CreateTableRequest createTableRequest = new CreateTableRequest()
.withTableName("WeatherData")
.withProvisionedThroughput(new ProvisionedThroughput()
.withReadCapacityUnits((long) 5)
.withWriteCapacityUnits((long) 1))
.withAttributeDefinitions(attributeDefinitions)
.withKeySchema(tableKeySchema)
.withGlobalSecondaryIndexes(precipIndex);
Table table = dynamoDB.createTable(createTableRequest);
System.out.println(table.getDescription());
```
Debe esperar hasta que DynamoDB cree la tabla y establezca el estado de esta última en `ACTIVE`. A partir de ese momento, puede comenzar a incluir elementos de datos en la tabla.
## Descripción de una tabla con un índice secundario global
Para obtener información sobre los índices secundarios globales en una tabla, use `DescribeTable`. Para cada índice, puede obtener acceso a su nombre, esquema de claves y atributos proyectados.
Los siguientes son los pasos para acceder a la información global de índice secundario de una tabla.
1. Cree una instancia de la clase `DynamoDB`.
1. Cree una instancia de la clase `Table` para representar el índice que desea usar.
1. Llame al método `describe` del objeto `Table`.
En el siguiente ejemplo de código Java se muestran los pasos anteriores.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
Table table = dynamoDB.getTable("WeatherData");
TableDescription tableDesc = table.describe();
Iterator gsiIter = tableDesc.getGlobalSecondaryIndexes().iterator();
while (gsiIter.hasNext()) {
GlobalSecondaryIndexDescription gsiDesc = gsiIter.next();
System.out.println("Info for index "
+ gsiDesc.getIndexName() + ":");
Iterator kseIter = gsiDesc.getKeySchema().iterator();
while (kseIter.hasNext()) {
KeySchemaElement kse = kseIter.next();
System.out.printf("\t%s: %s\n", kse.getAttributeName(), kse.getKeyType());
}
Projection projection = gsiDesc.getProjection();
System.out.println("\tThe projection type is: "
+ projection.getProjectionType());
if (projection.getProjectionType().toString().equals("INCLUDE")) {
System.out.println("\t\tThe non-key projected attributes are: "
+ projection.getNonKeyAttributes());
}
}
```
## Consulta de un índice secundario local
Puede utilizar `Query` en un índice secundario global, de un modo bastante similar al que realiza una `Query` en una tabla. Debe especificar el nombre del índice, los criterios de consulta de la clave de partición y la clave de ordenación (si procede) del índice y los atributos que desea devolver. En este ejemplo, el índice es `PrecipIndex`, cuyas clave de partición y ordenación son, respectivamente, `Date` y `Precipitation`. La consulta del índice devuelve todos los datos meteorológicos de una determinada fecha cuando el valor de Precipitation sea mayor que cero.
A continuación se indican los pasos que hay que seguir para consultar un índice secundario global mediante la API Document de AWS SDK para Java.
1. Cree una instancia de la clase `DynamoDB`.
1. Cree una instancia de la clase `Table` para representar el índice que desea usar.
1. Cree una instancia de la clase `Index` para el índice que desea consultar.
1. Llame al método `query` del objeto `Index`.
El nombre de atributo `Date` es una palabra reservada de DynamoDB. Por consiguiente, debe usar un nombre de atributo de expresión como marcador de posición en la expresión `KeyConditionExpression`.
En el siguiente ejemplo de código Java se muestran los pasos anteriores.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
Table table = dynamoDB.getTable("WeatherData");
Index index = table.getIndex("PrecipIndex");
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("#d = :v_date and Precipitation = :v_precip")
.withNameMap(new NameMap()
.with("#d", "Date"))
.withValueMap(new ValueMap()
.withString(":v_date","2013-08-10")
.withNumber(":v_precip",0));
ItemCollection items = index.query(spec);
Iterator- iter = items.iterator();
while (iter.hasNext()) {
System.out.println(iter.next().toJSONPretty());
}
```
# Ejemplo: índices secundarios globales que utilizan la API de documentos de AWS SDK para Java
En el siguiente ejemplo de código Java se muestra cómo usar índices secundarios globales. En el ejemplo se crea una tabla denominada `Issues`, que puede utilizarse en un sistema sencillo de seguimiento de errores con fines de desarrollo de software. La clave de partición es `IssueId` y la de ordenación, `Title`. Hay tres índices secundarios globales en esta tabla:
+ `CreateDateIndex`: la clave de partición es `CreateDate` y la de ordenación `IssueId`. Además de las claves de tabla, se proyectan en el índice los atributos `Description` y `Status`.
+ `TitleIndex`: la clave de partición es `Title` y la de ordenación `IssueId`. No se proyecta en el índice ningún otro atributo excepto las claves de tabla.
+ `DueDateIndex`: la clave de partición es `DueDate` y no hay clave de ordenación. Todos los atributos de la tabla se proyectan en el índice.
Una vez que se ha creado la tabla `Issues`, el programa carga la tabla con datos que representan informes de errores de software. A continuación, consulta los datos utilizando los índices secundarios globales. Por último, el programa elimina la tabla `Issues`.
Para obtener instrucciones paso a paso para probar el siguiente ejemplo, consulte [Ejemplos de código Java](CodeSamples.Java.md).
**Example**
```
package com.amazonaws.codesamples.document;
import java.util.ArrayList;
import java.util.Iterator;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.document.DynamoDB;
import com.amazonaws.services.dynamodbv2.document.Index;
import com.amazonaws.services.dynamodbv2.document.Item;
import com.amazonaws.services.dynamodbv2.document.ItemCollection;
import com.amazonaws.services.dynamodbv2.document.QueryOutcome;
import com.amazonaws.services.dynamodbv2.document.Table;
import com.amazonaws.services.dynamodbv2.document.spec.QuerySpec;
import com.amazonaws.services.dynamodbv2.document.utils.ValueMap;
import com.amazonaws.services.dynamodbv2.model.AttributeDefinition;
import com.amazonaws.services.dynamodbv2.model.CreateTableRequest;
import com.amazonaws.services.dynamodbv2.model.GlobalSecondaryIndex;
import com.amazonaws.services.dynamodbv2.model.KeySchemaElement;
import com.amazonaws.services.dynamodbv2.model.KeyType;
import com.amazonaws.services.dynamodbv2.model.Projection;
import com.amazonaws.services.dynamodbv2.model.ProvisionedThroughput;
public class DocumentAPIGlobalSecondaryIndexExample {
static AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
static DynamoDB dynamoDB = new DynamoDB(client);
public static String tableName = "Issues";
public static void main(String[] args) throws Exception {
createTable();
loadData();
queryIndex("CreateDateIndex");
queryIndex("TitleIndex");
queryIndex("DueDateIndex");
deleteTable(tableName);
}
public static void createTable() {
// Attribute definitions
ArrayList attributeDefinitions = new ArrayList();
attributeDefinitions.add(new AttributeDefinition().withAttributeName("IssueId").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("Title").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("CreateDate").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("DueDate").withAttributeType("S"));
// Key schema for table
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.HASH)); // Partition
// key
tableKeySchema.add(new KeySchemaElement().withAttributeName("Title").withKeyType(KeyType.RANGE)); // Sort
// key
// Initial provisioned throughput settings for the indexes
ProvisionedThroughput ptIndex = new ProvisionedThroughput().withReadCapacityUnits(1L)
.withWriteCapacityUnits(1L);
// CreateDateIndex
GlobalSecondaryIndex createDateIndex = new GlobalSecondaryIndex().withIndexName("CreateDateIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("CreateDate").withKeyType(KeyType.HASH), // Partition
// key
new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.RANGE)) // Sort
// key
.withProjection(
new Projection().withProjectionType("INCLUDE").withNonKeyAttributes("Description", "Status"));
// TitleIndex
GlobalSecondaryIndex titleIndex = new GlobalSecondaryIndex().withIndexName("TitleIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("Title").withKeyType(KeyType.HASH), // Partition
// key
new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.RANGE)) // Sort
// key
.withProjection(new Projection().withProjectionType("KEYS_ONLY"));
// DueDateIndex
GlobalSecondaryIndex dueDateIndex = new GlobalSecondaryIndex().withIndexName("DueDateIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("DueDate").withKeyType(KeyType.HASH)) // Partition
// key
.withProjection(new Projection().withProjectionType("ALL"));
CreateTableRequest createTableRequest = new CreateTableRequest().withTableName(tableName)
.withProvisionedThroughput(
new ProvisionedThroughput().withReadCapacityUnits((long) 1).withWriteCapacityUnits((long) 1))
.withAttributeDefinitions(attributeDefinitions).withKeySchema(tableKeySchema)
.withGlobalSecondaryIndexes(createDateIndex, titleIndex, dueDateIndex);
System.out.println("Creating table " + tableName + "...");
dynamoDB.createTable(createTableRequest);
// Wait for table to become active
System.out.println("Waiting for " + tableName + " to become ACTIVE...");
try {
Table table = dynamoDB.getTable(tableName);
table.waitForActive();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static void queryIndex(String indexName) {
Table table = dynamoDB.getTable(tableName);
System.out.println("\n***********************************************************\n");
System.out.print("Querying index " + indexName + "...");
Index index = table.getIndex(indexName);
ItemCollection items = null;
QuerySpec querySpec = new QuerySpec();
if (indexName == "CreateDateIndex") {
System.out.println("Issues filed on 2013-11-01");
querySpec.withKeyConditionExpression("CreateDate = :v_date and begins_with(IssueId, :v_issue)")
.withValueMap(new ValueMap().withString(":v_date", "2013-11-01").withString(":v_issue", "A-"));
items = index.query(querySpec);
} else if (indexName == "TitleIndex") {
System.out.println("Compilation errors");
querySpec.withKeyConditionExpression("Title = :v_title and begins_with(IssueId, :v_issue)")
.withValueMap(
new ValueMap().withString(":v_title", "Compilation error").withString(":v_issue", "A-"));
items = index.query(querySpec);
} else if (indexName == "DueDateIndex") {
System.out.println("Items that are due on 2013-11-30");
querySpec.withKeyConditionExpression("DueDate = :v_date")
.withValueMap(new ValueMap().withString(":v_date", "2013-11-30"));
items = index.query(querySpec);
} else {
System.out.println("\nNo valid index name provided");
return;
}
Iterator
- iterator = items.iterator();
System.out.println("Query: printing results...");
while (iterator.hasNext()) {
System.out.println(iterator.next().toJSONPretty());
}
}
public static void deleteTable(String tableName) {
System.out.println("Deleting table " + tableName + "...");
Table table = dynamoDB.getTable(tableName);
table.delete();
// Wait for table to be deleted
System.out.println("Waiting for " + tableName + " to be deleted...");
try {
table.waitForDelete();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static void loadData() {
System.out.println("Loading data into table " + tableName + "...");
// IssueId, Title,
// Description,
// CreateDate, LastUpdateDate, DueDate,
// Priority, Status
putItem("A-101", "Compilation error", "Can't compile Project X - bad version number. What does this mean?",
"2013-11-01", "2013-11-02", "2013-11-10", 1, "Assigned");
putItem("A-102", "Can't read data file", "The main data file is missing, or the permissions are incorrect",
"2013-11-01", "2013-11-04", "2013-11-30", 2, "In progress");
putItem("A-103", "Test failure", "Functional test of Project X produces errors", "2013-11-01", "2013-11-02",
"2013-11-10", 1, "In progress");
putItem("A-104", "Compilation error", "Variable 'messageCount' was not initialized.", "2013-11-15",
"2013-11-16", "2013-11-30", 3, "Assigned");
putItem("A-105", "Network issue", "Can't ping IP address 127.0.0.1. Please fix this.", "2013-11-15",
"2013-11-16", "2013-11-19", 5, "Assigned");
}
public static void putItem(
String issueId, String title, String description, String createDate, String lastUpdateDate, String dueDate,
Integer priority, String status) {
Table table = dynamoDB.getTable(tableName);
Item item = new Item().withPrimaryKey("IssueId", issueId).withString("Title", title)
.withString("Description", description).withString("CreateDate", createDate)
.withString("LastUpdateDate", lastUpdateDate).withString("DueDate", dueDate)
.withNumber("Priority", priority).withString("Status", status);
table.putItem(item);
}
}
```
# Trabajar con índices secundarios globales: .NET
Puede utilizar la API de bajo nivel AWS SDK para .NET para crear una tabla Amazon DynamoDB con uno o varios índices secundarios globales, describir los índices de la tabla y utilizarlos para realizar consultas. Estas operaciones se mapean a las operaciones correspondientes de DynamoDB. Para obtener más información, consulte la [Referencia de la API de Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).
A continuación se indican los pasos comunes para las operaciones con tablas mediante el API de bajo nivel de .NET.
1. Cree una instancia de la clase `AmazonDynamoDBClient`.
1. Cree los objetos de solicitud correspondientes para proporcionar los parámetros obligatorios y opcionales de la operación.
Por ejemplo, cree un objeto `CreateTableRequest` para crear una tabla y un objeto `QueryRequest` para consultar una tabla o un índice.
1. Ejecute el método apropiado proporcionado por el cliente que ha creado en el paso anterior.
**Topics**
+ [Creación de una tabla con un índice secundario global](#GSILowLevelDotNet.CreateTableWithIndex)
+ [Descripción de una tabla con un índice secundario global](#GSILowLevelDotNet.DescribeTableWithIndex)
+ [Consulta de un índice secundario local](#GSILowLevelDotNet.QueryAnIndex)
+ [Ejemplo: índices secundarios globales que usan la API de bajo nivel de AWS SDK para .NET](GSILowLevelDotNet.Example.md)
## Creación de una tabla con un índice secundario global
Puede crear índices secundarios globales a la vez que crea la tabla. Para ello, utilice `CreateTable` e indique las especificaciones para uno o varios índices secundarios globales. En el ejemplo de código C\$1 siguiente, se crea una tabla para contener información sobre datos meteorológicos. La clave de partición es `Location` y la de ordenación, `Date`. Un índice secundario global denominado `PrecipIndex` permite obtener acceso rápido a los datos sobre precipitaciones de varias ubicaciones.
A continuación se indican los pasos que hay que seguir para crear una tabla con un índice secundario global mediante el API de bajo nivel de .NET.
1. Cree una instancia de la clase `AmazonDynamoDBClient`.
1. Cree una instancia de la clase `CreateTableRequest` para proporcionar la información de solicitud.
Debe proporcionar el nombre de la tabla, su clave principal y los valores de rendimiento aprovisionado. Para el índice secundario global, debe proporcionar el nombre del índice, los ajustes de rendimiento aprovisionado, las definiciones de atributos de la clave de ordenación del índice, el esquema de claves del índice y la proyección de atributos.
1. Ejecute el método `CreateTable` proporcionando el objeto de solicitud como parámetro.
En el siguiente ejemplo de código C\$1 se ponen en práctica los pasos anteriores. El código crea una tabla (`WeatherData`) con un índice secundario global (`PrecipIndex`). La clave de partición del índice es `Date` y la de ordenación, `Precipitation`. Todos los atributos de la tabla se proyectan en el índice. Los usuarios pueden consultar este índice para obtener los datos meteorológicos de una determinada fecha y, si lo desean, ordenarlos según la cantidad de precipitación.
Ya que `Precipitation` no es un atributo de clave para la tabla, no es obligatorio. Sin embargo, los elementos`WeatherData` sin `Precipitation` no aparecen en `PrecipIndex`.
```
client = new AmazonDynamoDBClient();
string tableName = "WeatherData";
// Attribute definitions
var attributeDefinitions = new List()
{
{new AttributeDefinition{
AttributeName = "Location",
AttributeType = "S"}},
{new AttributeDefinition{
AttributeName = "Date",
AttributeType = "S"}},
{new AttributeDefinition(){
AttributeName = "Precipitation",
AttributeType = "N"}
}
};
// Table key schema
var tableKeySchema = new List()
{
{new KeySchemaElement {
AttributeName = "Location",
KeyType = "HASH"}}, //Partition key
{new KeySchemaElement {
AttributeName = "Date",
KeyType = "RANGE"} //Sort key
}
};
// PrecipIndex
var precipIndex = new GlobalSecondaryIndex
{
IndexName = "PrecipIndex",
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)10,
WriteCapacityUnits = (long)1
},
Projection = new Projection { ProjectionType = "ALL" }
};
var indexKeySchema = new List {
{new KeySchemaElement { AttributeName = "Date", KeyType = "HASH"}}, //Partition key
{new KeySchemaElement{AttributeName = "Precipitation",KeyType = "RANGE"}} //Sort key
};
precipIndex.KeySchema = indexKeySchema;
CreateTableRequest createTableRequest = new CreateTableRequest
{
TableName = tableName,
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)5,
WriteCapacityUnits = (long)1
},
AttributeDefinitions = attributeDefinitions,
KeySchema = tableKeySchema,
GlobalSecondaryIndexes = { precipIndex }
};
CreateTableResponse response = client.CreateTable(createTableRequest);
Console.WriteLine(response.CreateTableResult.TableDescription.TableName);
Console.WriteLine(response.CreateTableResult.TableDescription.TableStatus);
```
Debe esperar hasta que DynamoDB cree la tabla y establezca el estado de esta última en `ACTIVE`. A partir de ese momento, puede comenzar a incluir elementos de datos en la tabla.
## Descripción de una tabla con un índice secundario global
Para obtener información sobre los índices secundarios globales en una tabla, use `DescribeTable`. Para cada índice, puede obtener acceso a su nombre, esquema de claves y atributos proyectados.
A continuación se indican los pasos que hay que seguir para acceder a la información de un índice secundario global de una tabla mediante el API de bajo nivel de .NET.
1. Cree una instancia de la clase `AmazonDynamoDBClient`.
1. Ejecute el método `describeTable` proporcionando el objeto de solicitud como parámetro.
Cree una instancia de la clase `DescribeTableRequest` para proporcionar la información de solicitud. Debe proporcionar el nombre de la tabla.
En el siguiente ejemplo de código C\$1 se ponen en práctica los pasos anteriores.
**Example**
```
client = new AmazonDynamoDBClient();
string tableName = "WeatherData";
DescribeTableResponse response = client.DescribeTable(new DescribeTableRequest { TableName = tableName});
List globalSecondaryIndexes =
response.DescribeTableResult.Table.GlobalSecondaryIndexes;
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
foreach (GlobalSecondaryIndexDescription gsiDescription in globalSecondaryIndexes) {
Console.WriteLine("Info for index " + gsiDescription.IndexName + ":");
foreach (KeySchemaElement kse in gsiDescription.KeySchema) {
Console.WriteLine("\t" + kse.AttributeName + ": key type is " + kse.KeyType);
}
Projection projection = gsiDescription.Projection;
Console.WriteLine("\tThe projection type is: " + projection.ProjectionType);
if (projection.ProjectionType.ToString().Equals("INCLUDE")) {
Console.WriteLine("\t\tThe non-key projected attributes are: "
+ projection.NonKeyAttributes);
}
}
```
## Consulta de un índice secundario local
Puede utilizar `Query` en un índice secundario global, de un modo bastante similar al que realiza una `Query` en una tabla. Debe especificar el nombre del índice, los criterios de consulta de la clave de partición y la clave de ordenación (si procede) del índice y los atributos que desea devolver. En este ejemplo, el índice es `PrecipIndex`, cuyas clave de partición y ordenación son, respectivamente, `Date` y `Precipitation`. La consulta del índice devuelve todos los datos meteorológicos de una determinada fecha cuando el valor de Precipitation sea mayor que cero.
A continuación se indican los pasos que hay que seguir para consultar un índice secundario global mediante el API de bajo nivel de .NET.
1. Cree una instancia de la clase `AmazonDynamoDBClient`.
1. Cree una instancia de la clase `QueryRequest` para proporcionar la información de solicitud.
1. Ejecute el método `query` proporcionando el objeto de solicitud como parámetro.
El nombre de atributo `Date` es una palabra reservada de DynamoDB. Por consiguiente, debe usar un nombre de atributo de expresión como marcador de posición en la expresión `KeyConditionExpression`.
En el siguiente ejemplo de código C\$1 se ponen en práctica los pasos anteriores.
**Example**
```
client = new AmazonDynamoDBClient();
QueryRequest queryRequest = new QueryRequest
{
TableName = "WeatherData",
IndexName = "PrecipIndex",
KeyConditionExpression = "#dt = :v_date and Precipitation > :v_precip",
ExpressionAttributeNames = new Dictionary {
{"#dt", "Date"}
},
ExpressionAttributeValues = new Dictionary {
{":v_date", new AttributeValue { S = "2013-08-01" }},
{":v_precip", new AttributeValue { N = "0" }}
},
ScanIndexForward = true
};
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
Console.Write(attr + "---> ");
if (attr == "Precipitation")
{
Console.WriteLine(currentItem[attr].N);
}
else
{
Console.WriteLine(currentItem[attr].S);
}
}
Console.WriteLine();
}
```
# Ejemplo: índices secundarios globales que usan la API de bajo nivel de AWS SDK para .NET
En el siguiente ejemplo de código C\$1 se muestra cómo usar índices secundarios globales. En el ejemplo se crea una tabla denominada `Issues`, que puede utilizarse en un sistema sencillo de seguimiento de errores con fines de desarrollo de software. La clave de partición es `IssueId` y la de ordenación, `Title`. Hay tres índices secundarios globales en esta tabla:
+ `CreateDateIndex`: la clave de partición es `CreateDate` y la de ordenación `IssueId`. Además de las claves de tabla, se proyectan en el índice los atributos `Description` y `Status`.
+ `TitleIndex`: la clave de partición es `Title` y la de ordenación `IssueId`. No se proyecta en el índice ningún otro atributo excepto las claves de tabla.
+ `DueDateIndex`: la clave de partición es `DueDate` y no hay clave de ordenación. Todos los atributos de la tabla se proyectan en el índice.
Una vez que se ha creado la tabla `Issues`, el programa carga la tabla con datos que representan informes de errores de software. A continuación, consulta los datos utilizando los índices secundarios globales. Por último, el programa elimina la tabla `Issues`.
Para obtener instrucciones paso a paso para probar el siguiente ejemplo, consulte [Ejemplos de código .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using System.Linq;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelGlobalSecondaryIndexExample
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
public static String tableName = "Issues";
public static void Main(string[] args)
{
CreateTable();
LoadData();
QueryIndex("CreateDateIndex");
QueryIndex("TitleIndex");
QueryIndex("DueDateIndex");
DeleteTable(tableName);
Console.WriteLine("To continue, press enter");
Console.Read();
}
private static void CreateTable()
{
// Attribute definitions
var attributeDefinitions = new List()
{
{new AttributeDefinition {
AttributeName = "IssueId", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "Title", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "CreateDate", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "DueDate", AttributeType = "S"
}}
};
// Key schema for table
var tableKeySchema = new List() {
{
new KeySchemaElement {
AttributeName= "IssueId",
KeyType = "HASH" //Partition key
}
},
{
new KeySchemaElement {
AttributeName = "Title",
KeyType = "RANGE" //Sort key
}
}
};
// Initial provisioned throughput settings for the indexes
var ptIndex = new ProvisionedThroughput
{
ReadCapacityUnits = 1L,
WriteCapacityUnits = 1L
};
// CreateDateIndex
var createDateIndex = new GlobalSecondaryIndex()
{
IndexName = "CreateDateIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "CreateDate", KeyType = "HASH" //Partition key
},
new KeySchemaElement {
AttributeName = "IssueId", KeyType = "RANGE" //Sort key
}
},
Projection = new Projection
{
ProjectionType = "INCLUDE",
NonKeyAttributes = {
"Description", "Status"
}
}
};
// TitleIndex
var titleIndex = new GlobalSecondaryIndex()
{
IndexName = "TitleIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "Title", KeyType = "HASH" //Partition key
},
new KeySchemaElement {
AttributeName = "IssueId", KeyType = "RANGE" //Sort key
}
},
Projection = new Projection
{
ProjectionType = "KEYS_ONLY"
}
};
// DueDateIndex
var dueDateIndex = new GlobalSecondaryIndex()
{
IndexName = "DueDateIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "DueDate",
KeyType = "HASH" //Partition key
}
},
Projection = new Projection
{
ProjectionType = "ALL"
}
};
var createTableRequest = new CreateTableRequest
{
TableName = tableName,
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)1,
WriteCapacityUnits = (long)1
},
AttributeDefinitions = attributeDefinitions,
KeySchema = tableKeySchema,
GlobalSecondaryIndexes = {
createDateIndex, titleIndex, dueDateIndex
}
};
Console.WriteLine("Creating table " + tableName + "...");
client.CreateTable(createTableRequest);
WaitUntilTableReady(tableName);
}
private static void LoadData()
{
Console.WriteLine("Loading data into table " + tableName + "...");
// IssueId, Title,
// Description,
// CreateDate, LastUpdateDate, DueDate,
// Priority, Status
putItem("A-101", "Compilation error",
"Can't compile Project X - bad version number. What does this mean?",
"2013-11-01", "2013-11-02", "2013-11-10",
1, "Assigned");
putItem("A-102", "Can't read data file",
"The main data file is missing, or the permissions are incorrect",
"2013-11-01", "2013-11-04", "2013-11-30",
2, "In progress");
putItem("A-103", "Test failure",
"Functional test of Project X produces errors",
"2013-11-01", "2013-11-02", "2013-11-10",
1, "In progress");
putItem("A-104", "Compilation error",
"Variable 'messageCount' was not initialized.",
"2013-11-15", "2013-11-16", "2013-11-30",
3, "Assigned");
putItem("A-105", "Network issue",
"Can't ping IP address 127.0.0.1. Please fix this.",
"2013-11-15", "2013-11-16", "2013-11-19",
5, "Assigned");
}
private static void putItem(
String issueId, String title,
String description,
String createDate, String lastUpdateDate, String dueDate,
Int32 priority, String status)
{
Dictionary item = new Dictionary();
item.Add("IssueId", new AttributeValue
{
S = issueId
});
item.Add("Title", new AttributeValue
{
S = title
});
item.Add("Description", new AttributeValue
{
S = description
});
item.Add("CreateDate", new AttributeValue
{
S = createDate
});
item.Add("LastUpdateDate", new AttributeValue
{
S = lastUpdateDate
});
item.Add("DueDate", new AttributeValue
{
S = dueDate
});
item.Add("Priority", new AttributeValue
{
N = priority.ToString()
});
item.Add("Status", new AttributeValue
{
S = status
});
try
{
client.PutItem(new PutItemRequest
{
TableName = tableName,
Item = item
});
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
}
private static void QueryIndex(string indexName)
{
Console.WriteLine
("\n***********************************************************\n");
Console.WriteLine("Querying index " + indexName + "...");
QueryRequest queryRequest = new QueryRequest
{
TableName = tableName,
IndexName = indexName,
ScanIndexForward = true
};
String keyConditionExpression;
Dictionary expressionAttributeValues = new Dictionary();
if (indexName == "CreateDateIndex")
{
Console.WriteLine("Issues filed on 2013-11-01\n");
keyConditionExpression = "CreateDate = :v_date and begins_with(IssueId, :v_issue)";
expressionAttributeValues.Add(":v_date", new AttributeValue
{
S = "2013-11-01"
});
expressionAttributeValues.Add(":v_issue", new AttributeValue
{
S = "A-"
});
}
else if (indexName == "TitleIndex")
{
Console.WriteLine("Compilation errors\n");
keyConditionExpression = "Title = :v_title and begins_with(IssueId, :v_issue)";
expressionAttributeValues.Add(":v_title", new AttributeValue
{
S = "Compilation error"
});
expressionAttributeValues.Add(":v_issue", new AttributeValue
{
S = "A-"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else if (indexName == "DueDateIndex")
{
Console.WriteLine("Items that are due on 2013-11-30\n");
keyConditionExpression = "DueDate = :v_date";
expressionAttributeValues.Add(":v_date", new AttributeValue
{
S = "2013-11-30"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else
{
Console.WriteLine("\nNo valid index name provided");
return;
}
queryRequest.KeyConditionExpression = keyConditionExpression;
queryRequest.ExpressionAttributeValues = expressionAttributeValues;
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
if (attr == "Priority")
{
Console.WriteLine(attr + "---> " + currentItem[attr].N);
}
else
{
Console.WriteLine(attr + "---> " + currentItem[attr].S);
}
}
Console.WriteLine();
}
}
private static void DeleteTable(string tableName)
{
Console.WriteLine("Deleting table " + tableName + "...");
client.DeleteTable(new DeleteTableRequest
{
TableName = tableName
});
WaitForTableToBeDeleted(tableName);
}
private static void WaitUntilTableReady(string tableName)
{
string status = null;
// Let us wait until table is created. Call DescribeTable.
do
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
status = res.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found. So we handle the potential exception.
}
} while (status != "ACTIVE");
}
private static void WaitForTableToBeDeleted(string tableName)
{
bool tablePresent = true;
while (tablePresent)
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
}
catch (ResourceNotFoundException)
{
tablePresent = false;
}
}
}
}
}
```
# Uso de índices secundarios globales en DynamoDB con la AWS CLI
Puede utilizar la AWS CLI para crear una tabla de Amazon DynamoDB con uno o varios índices secundarios globales, describir los índices de la tabla y utilizarlos para realizar consultas.
**Topics**
+ [Creación de una tabla con un índice secundario global](#GCICli.CreateTableWithIndex)
+ [Adición de un índice secundario global a una tabla existente](#GCICli.CreateIndexAfterTable)
+ [Descripción de una tabla con un índice secundario global](#GCICli.DescribeTableWithIndex)
+ [Consulta de un índice secundario local](#GCICli.QueryAnIndex)
## Creación de una tabla con un índice secundario global
Se pueden crear índices secundarios globales al mismo tiempo que se crea una tabla. Para ello, utilice el parámetro `create-table` y proporcione sus especificaciones para uno o más índices secundarios globales. En el siguiente ejemplo, se crea una tabla llamada `GameScores` con un índice secundario global `GameTitleIndex`. La tabla base tiene una clave de partición de `UserId` y una clave de ordenación de `GameTitle`, lo que le permite encontrar eficientemente la mejor puntuación de un usuario individual para un juego específico, mientras que el GSI tiene una clave de partición de `GameTitle` y una clave de ordenación de `TopScore`, lo que te permite encontrar rápidamente la puntuación más alta en general para un juego en particular.
```
aws dynamodb create-table \
--table-name GameScores \
--attribute-definitions AttributeName=UserId,AttributeType=S \
AttributeName=GameTitle,AttributeType=S \
AttributeName=TopScore,AttributeType=N \
--key-schema AttributeName=UserId,KeyType=HASH \
AttributeName=GameTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--global-secondary-indexes \
"[
{
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
},
\"ProvisionedThroughput\": {
\"ReadCapacityUnits\": 10,
\"WriteCapacityUnits\": 5
}
}
]"
```
Debe esperar hasta que DynamoDB cree la tabla y establezca el estado de esta última en `ACTIVE`. A partir de ese momento, puede comenzar a incluir elementos de datos en la tabla. Puede utilizar [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) Para determinar el estado de la creación de tablas.
## Adición de un índice secundario global a una tabla existente
Los índices secundarios globales también se pueden agregar o modificar después de la creación de la tabla. Para ello, utilice el parámetro `update-table` y proporcione sus especificaciones para uno o más índices secundarios globales. En el siguiente ejemplo se utiliza el mismo esquema que el ejemplo anterior, pero se supone que la tabla ya se ha creado y que vamos a agregar el GSI más adelante.
```
aws dynamodb update-table \
--table-name GameScores \
--attribute-definitions AttributeName=TopScore,AttributeType=N \
--global-secondary-index-updates \
"[
{
\"Create\": {
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
}
}
}
]"
```
## Descripción de una tabla con un índice secundario global
Para obtener información acerca de los índices secundarios globales en una tabla, utilice el parámetro `describe-table`. Para cada índice, puede obtener acceso a su nombre, esquema de claves y atributos proyectados.
```
aws dynamodb describe-table --table-name GameScores
```
## Consulta de un índice secundario local
Puede utilizar la operación `query` en un índice secundario global de un modo bastante similar a como se usa `query` en una tabla. Debe especificar el nombre del índice, los criterios de consulta de la clave de ordenación del índice y los atributos que desea devolver. En este ejemplo, el índice es `GameTitleIndex` y la clave de ordenación del índice es `GameTitle`.
Los únicos atributos devueltos son aquellos que se han proyectado en el índice. Puede modificar esta consulta de modo que también seleccione atributos sin clave, pero esto requeriría realizar actividad de recuperación en la tabla, lo que resulta relativamente costoso. Para obtener más información sobre recuperaciones de tablas, consulte [Proyecciones de atributos](GSI.md#GSI.Projections).
```
aws dynamodb query --table-name GameScores\
--index-name GameTitleIndex \
--key-condition-expression "GameTitle = :v_game" \
--expression-attribute-values '{":v_game":{"S":"Alien Adventure"} }'
```
# Índices secundarios locales
Algunas aplicaciones solo necesitan consultar datos mediante la clave principal de la tabla base. Sin embargo, puede haber situaciones en las que una clave de ordenación alternativa sería útil. Para que la aplicación disponga de diversas claves de ordenación entre las que elegir, puede crear uno o varios índices secundarios en una tabla de Amazon DynamoDB y emitir solicitudes `Query` o `Scan` para estos índices.
**Topics**
+ [Situación: Uso de un índice secundario local](#LSI.Scenario)
+ [Proyecciones de atributos](#LSI.Projections)
+ [Creación de un índice secundario local](#LSI.Creating)
+ [Lectura de datos de un índice secundario local](#LSI.Reading)
+ [Escrituras de elementos e índices secundarios locales](#LSI.Writes)
+ [Consideraciones sobre el rendimiento aprovisionado para los índices secundarios locales](#LSI.ThroughputConsiderations)
+ [Consideraciones sobre el almacenamiento para los índices secundarios locales](#LSI.StorageConsiderations)
+ [Colecciones de elementos en los índices secundarios locales](#LSI.ItemCollections)
+ [Trabajar con índices secundarios locales: Java](LSIJavaDocumentAPI.md)
+ [Trabajar con índices secundarios locales: .NET](LSILowLevelDotNet.md)
+ [Uso de índices secundarios locales en la AWS CLI de DynamoDB](LCICli.md)
## Situación: Uso de un índice secundario local
Como ejemplo, veamos la tabla `Thread`. Esta tabla es útil para una aplicación como, por ejemplo, [Foros de debate de AWS](https://forums.aws.amazon.com/). En el siguiente diagrama se muestra cómo se organizarían los elementos de la tabla. No se muestran todos los atributos.
![\[Tabla de subprocesos que contiene una lista de nombres de foro, temas, hora de la última publicación y número de respuestas.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/LSI_01.png)
DynamoDB almacena todos los elementos que tienen el mismo valor de clave de partición de forma continua. En este ejemplo, para un valor determinado de `ForumName`, una operación `Query` podría localizar inmediatamente todas las conversaciones de ese foro. Dentro de un grupo de elementos con el mismo valor de clave de partición, los elementos se ordenan según el valor de la clave de ordenación. Si la clave de ordenación (`Subject`) también se incluye en la consulta, DynamoDB puede afinar los resultados que se devuelven; por ejemplo, devolvería todas las conversaciones del foro "S3" cuyo valor de `Subject` comience por la letra "a".
Algunas solicitudes podrían requerir patrones más complejos de acceso a los datos. Por ejemplo:
+ ¿Qué conversaciones del foro son las que suscitan más visualizaciones y respuestas?
+ ¿Qué conversación de un foro determinado tiene mayor cantidad de mensajes?
+ ¿Cuántas conversaciones se han publicado en un foro determinado dentro de un periodo concreto?
Para responder a estas preguntas, la acción `Query` no bastaría. En su lugar, habría que aplicar `Scan` a la tabla completa. Si la tabla contiene millones de elementos, esto consumiría una cantidad enorme de desempeño de lectura provisionado y tardaría mucho tiempo en completarse.
Sin embargo, puede especificar uno o más índices secundarios locales en atributos que no sean clave, tales como `Replies` or `LastPostDateTime`.
Un *índice secundario local* mantiene una clave de ordenación alternativa para un determinado valor de clave de partición. Un índice secundario local también contiene una copia parcial o total de los atributos de la tabla base. Al crear la tabla, se especifican qué atributos se proyectarán en el índice secundario local. Los datos de un índice secundario local se organizan según la misma clave de partición que la tabla base, pero con una clave de ordenación distinta. Esto le permite obtener acceso a los elementos de datos de forma eficiente en esta otra dimensión. Para lograr una mayor flexibilidad de consulta o examen, puede crear hasta cinco índices secundarios locales por tabla.
Supongamos que una aplicación tiene que encontrar todas las conversaciones que se han publicado en los últimos tres meses en un foro particular. Sin un índice secundario local, la aplicación tendría que aplicar la operación `Scan` a toda la tabla `Thread` y, después, descartar aquellas publicaciones que no estuviesen comprendidos en el periodo especificado. Con un índice secundario local una operación `Query` podría usar `LastPostDateTime` como clave de ordenación para encontrar rápidamente los datos.
En el siguiente diagrama se muestra un índice secundario local denominado `LastPostIndex`. Tenga en cuenta que la clave de partición es la misma que para la tabla `Thread`, pero que la clave de ordenación es `LastPostDateTime`.
![\[La tabla LastPostIndex que contiene una lista de nombres de foro, temas y última hora de publicación.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/LSI_02.png)
Cada índice secundario local debe cumplir las condiciones siguientes:
+ La clave de partición ha de ser la misma que aquella de la tabla base.
+ La clave de ordenación consta exactamente de un atributo escalar.
+ La clave de ordenación de la tabla base se proyectará en el índice, donde actuará como atributo sin clave.
En este ejemplo, la clave de partición es `ForumName` y la clave de ordenación del índice secundario local es `LastPostDateTime`. Además, el valor de clave de ordenación de la tabla base (en este ejemplo, `Subject`) se proyecta en el índice, aunque no forma parte de la clave de índice. Si una aplicación requiere una lista basada en `ForumName` y `LastPostDateTime`, puede emitir una solicitud `Query` para `LastPostIndex`. Los resultados de la consulta se ordenan por `LastPostDateTime` y se pueden devolver en orden ascendente o descendente. La consulta también puede aplicar condiciones de clave, tales como devolver solamente aquellos elementos cuyo valor de `LastPostDateTime` esté comprendido en un periodo determinado.
Cada índice secundario local contiene automáticamente las claves de partición y ordenación de su tabla base. Si lo desea, puede proyectar atributos sin clave en el índice. Cuando se consulta el índice, DynamoDB puede recuperar estos atributos proyectados de forma eficiente. Cuando se consulta un índice secuandario local, la consulta también puede recuperar atributos *no* proyectados en el índice. DynamoDB recuperará automáticamente estos atributos de la tabla base, pero con una mayor latencia y costes más elevados de rendimiento aprovisionado.
Para cualquier índice secundario local, puede almacenar hasta 10 GB de datos por cada valor diferente de clave de partición. Esta cifra incluye todos los elementos de la tabla base, además de todos los elementos de los índices, que tengan el mismo valor de clave de partición. Para obtener más información, consulte [Colecciones de elementos en los índices secundarios locales](#LSI.ItemCollections).
## Proyecciones de atributos
Con `LastPostIndex`, una aplicación podría usar `ForumName` y `LastPostDateTime` como criterios de consulta. Sin embargo, para recuperar cualquier atributo adicional, DynamoDB debe realizar operaciones de lectura adicionales en la tabla `Thread`. Estas lecturas adicionales se denominan *recuperaciones* y pueden aumentar la cantidad total de desempeño provisionado necesario para una consulta.
Supongamos que desea rellenar una página web con una lista de todas las conversaciones del foro "S3" y el número de respuestas de cada conversación, ordenadas según la fecha y hora de la última respuesta y comenzando por la respuesta más reciente. Para rellenar esta lista, se requieren los siguientes atributos:
+ `Subject`
+ `Replies`
+ `LastPostDateTime`
La forma más eficiente de consultar estos datos y evitar operaciones de recuperación, sería proyectar el atributo `Replies`de la tabla en el índice secundario global, tal y como se muestra en este diagrama.
![\[Tabla LastPostIndex que contiene una lista de nombres de foro, horas de las últimas publicaciones, temas y respuestas.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/LSI_03.png)
Una *proyección* es el conjunto de atributos que se copia de una tabla en un índice secundario. La clave de partición y la clave de ordenación de la tabla siempre se proyectan en el índice; puede proyectar otros atributos para admitir los requisitos de consulta de la aplicación. Cuando consulta un índice, Amazon DynamoDB puede acceder a cualquier atributo de la proyección como si esos atributos estuvieran en una tabla propia.
Al crear un índice secundario, debe especificar los atributos que se proyectarán en el índice. DynamoDB ofrece tres opciones diferentes para esto:
+ *KEYS\$1ONLY*: cada elemento del índice consta únicamente de los valores de la clave de partición y la clave de ordenación de la tabla, así como de los valores de las claves del índice. La opción `KEYS_ONLY` da como resultado el índice secundario más pequeño posible.
+ *INCLUDE*: además de los atributos que se describen en `KEYS_ONLY`, el índice secundario incluirá otros atributos sin clave que se especifiquen.
+ *ALL*: el índice secundario incluye todos los atributos de la tabla de origen. Debido a que todos los datos de la tabla están duplicados en el índice, un resultado de proyección `ALL` en el índice secundario más grande posible.
En el diagrama anterior, el atributo sin clave `Replies` se proyecta en `LastPostIndex`. Una aplicación puede consultar `LastPostIndex` en lugar de `Thread` completo para rellenar una página web con `Subject`, `Replies` y `LastPostDateTime`. Si se solicitasen otros atributos sin clave, DynamoDB tendría que recuperarlos en la tabla `Thread`.
Desde el punto de vista de una aplicación, la recuperación de atributos adicionales de la tabla base se lleva a cabo de forma automática y transparente, por lo que no es necesario volver a escribir la lógica de la aplicación. No obstante, este tipo de recuperaciones puede reducir en gran medida el efecto beneficioso para el desempeño que aporta el uso de un índice secundario local.
Cuando elija los atributos para proyectarlos en un índice secundario local, debe estudiar el equilibrio entre los costes de rendimiento aprovisionado y de almacenamiento:
+ Si solo necesita acceder a algunos atributos con la menor latencia posible, puede ser conveniente proyectar solamente esos atributos en un índice secundario local. Cuando menor es el índice, menos cuesta almacenarlo y menos son los costes de escritura. Si hay atributos que solo tiene que recuperar de vez en cuando, el costo del desempeño provisionado podría superar con creces el costo a largo plazo de almacenar esos atributos.
+ Si la aplicación va a obtener acceso con frecuencia a determinados atributos sin clave, puede ser interesante proyectarlos en un índice secundario local. Los costes del almacenamiento adicionales del índice secundario local compensarán el coste que supondrían los frecuentes exámenes de la tabla.
+ Si tiene que acceder a la mayoría de los atributos sin clave con frecuencia, puede proyectar estos atributos o, incluso, toda la tabla base, en un índice secundario local. De este modo, dispondrá de la máxima flexibilidad y el menor consumo de desempeño provisionado, porque no será preciso realizar recuperaciones. Sin embargo, el coste del almacenamiento aumentaría y podría llegar a duplicarse si se proyectan todos los atributos.
+ Si la aplicación tiene que consultar una tabla con poca frecuencia, pero tiene que realizar gran cantidad de escrituras o actualizaciones en los datos de la tabla, puede ser conveniente proyectar *KEYS\$1ONLY*. El índice secundario local tendrá el tamaño mínimo, pero estaría disponible siempre que se requiriese para actividades de consulta.
## Creación de un índice secundario local
Para crear una tabla con uno o varios índices secundarios locales, use el parámetro `LocalSecondaryIndexes` de la operación `CreateTable`. Los índices secundarios locales de una tabla se crean cuando se crea la tabla. Al eliminar una tabla, todos los índices secundarios globales de esa tabla se eliminan también.
Debe especificar un atributo sin clave que actúe como clave de ordenación del índice secundario local. El atributo que elija debe ser un escalar `String`, `Number` o `Binary`. No se admite ningún otro tipo de escalar, documento ni conjunto. Para obtener una lista completa de los tipos de datos, consulte [Tipos de datos](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes).
**importante**
Para las tablas con índices secundarios locales, existe un límite de tamaño de 10 GB por valor de clave de partición. Una tabla con índices secundarios locales puede almacenar cualquier número de elementos, siempre y cuando el tamaño total de cualquier valor de clave de partición individual no supere los 10 GB. Para obtener más información, consulte [Límite del tamaño de una colección de elementos](#LSI.ItemCollections.SizeLimit).
Puede proyectar atributos de cualquier tipo de datos en un índice secundario local. Esto incluye escalares, documentos y conjuntos. Para obtener una lista completa de los tipos de datos, consulte [Tipos de datos](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes).
## Lectura de datos de un índice secundario local
Puede recuperar elementos de un índice secundario local utilizando las operaciones `Query` y `Scan`. Las operaciones `GetItem` y `BatchGetItem` no se pueden usar en un índice secundario local.
### Consulta a un índice secundario local
En una tabla de DynamoDB, la combinación de valor de clave de partición y valor de clave de ordenación de cada elemento debe ser única. Sin embargo, en un índice secundario local, no es preciso que el valor de la clave de ordenación sea exclusivo para un determinado valor de clave de partición. Si un índice secundario local contiene varios elementos que tienen el mismo valor de clave de ordenación, una operación `Query` devolverá todos los elementos que tengan el mismo valor de clave de partición. En la respuesta, los elementos coincidentes no se devuelven en ningún orden concreto.
Puede consultar un índice secundario local usando lecturas consistentes finales o de consistencia alta. Para especificar qué tipo de consistencia desea aplicar, se utiliza el parámetro `ConsistentRead`Consistentead de la operación `Query`. Una lectura de consistencia alta de un índice secundario local siempre devolverá los valores actualizados más recientemente. Si la consulta tiene que recuperar atributos adicionales de la tabla base, estos serán consistentes respecto al índice.
**Example**
Fíjese en los datos siguientes devueltos por una operación `Query` que solicita datos de las conversaciones de un foro determinado.
```
{
"TableName": "Thread",
"IndexName": "LastPostIndex",
"ConsistentRead": false,
"ProjectionExpression": "Subject, LastPostDateTime, Replies, Tags",
"KeyConditionExpression":
"ForumName = :v_forum and LastPostDateTime between :v_start and :v_end",
"ExpressionAttributeValues": {
":v_start": {"S": "2015-08-31T00:00:00.000Z"},
":v_end": {"S": "2015-11-31T00:00:00.000Z"},
":v_forum": {"S": "EC2"}
}
}
```
En esta consulta:
+ DynamoDB accede a `LastPostIndex`. Utiliza la clave de partición `ForumName` para localizar los elementos del índice correspondientes a "EC2". Todos los elementos de índice que tienen esta clave se almacenan en posiciones adyacentes, para agilizar su recuperación.
+ En este foro, DynamoDB utiliza el índice para buscar las claves que coinciden con la condición `LastPostDateTime` especificada.
+ Dado que el atributo `Replies` se proyecta en el índice, DynamoDB puede recuperar este atributo sin consumir ningún rendimiento provisionado adicional.
+ El atributo `Tags` no se proyecta en el índice, de tal forma que DynamoDB debe acceder a la tabla `Thread` y recuperar este atributo.
+ Se devuelven los resultados ordenados según `LastPostDateTime`. Las entradas de índice se ordenan según el valor de la clave de partición y, a continuación, según el valor de la clave de ordenación; `Query` las devuelve en el orden en el que se encuentran almacenadas. Puede utilizar el parámetro `ScanIndexForward` para devolver los resultados en orden descendente.
Puesto que el atributo `Tags` no se ha proyectado en el índice secundario local, DynamoDB debe consumir unidades de capacidad de lectura adicionales para recuperar este atributo de la tabla base. Si necesita ejecutar esta consulta a menudo, debe proyectar `Tags` en `LastPostIndex` para evitar la obtención de la tabla base. Sin embargo, si necesitaba acceder a `Tags` sólo ocasionalmente, el coste de almacenamiento adicional para proyectar `Tags` en el índice puede no valer la pena.
### Análisis de un índice secundario local
Puede utilizar `Scan` para recuperar todos los datos de un índice secundario local. Debe proporcionar el nombre de la tabla base y el nombre del índice en la solicitud. Con una operación `Scan`, DynamoDB lee todos los datos del índice y los devuelve a la aplicación. También puede solicitar que solo se devuelvan algunos de los datos y se descarten los demás. Para ello, se utiliza el parámetro `FilterExpression` del API `Scan`. Para obtener más información, consulte [Expresiones de filtro para el análisis](Scan.md#Scan.FilterExpression).
## Escrituras de elementos e índices secundarios locales
DynamoDB mantiene sincronizados automáticamente todos los índices secundarios locales con sus tablas base respectivas. Las aplicaciones nunca escriben directamente en un índice. Sin embargo, es importante que comprenda las implicaciones de cómo DynamoDB mantiene estos índices.
Al crear un índice secundario local, se especifica un atributo que actuará como clave de ordenación del índice. También se puede especificar el tipo de datos de ese atributo. Esto significa que, cada vez que se escribe un elemento en la tabla base, si el elemento define un atributo de clave de índice, su tipo debe coincidir con el tipo de datos del esquema de claves de índice. En el caso de `LastPostIndex`, el tipo de datos de la clave de ordenación `LastPostDateTime` del índice es `String`. Si intenta agregar un elemento a la tabla `Thread`, pero especifica un tipo de datos distinto para `LastPostDateTime` (tal como`Number`), DynamoDB devolverá una excepción `ValidationException`, porque los tipos de datos no coinciden.
No es obligatorio que exista una relación biunívoca entre los elementos de una tabla base y los elementos en un índice secundario local. De hecho, este comportamiento puede ser ventajoso para muchas aplicaciones.
Una tabla con muchos índices secundarios locales devengará costes más elevados por la actividad de escritura que las tablas con menos índices. Para obtener más información, consulte [Consideraciones sobre el rendimiento aprovisionado para los índices secundarios locales](#LSI.ThroughputConsiderations).
**importante**
Para las tablas con índices secundarios locales, existe un límite de tamaño de 10 GB por valor de clave de partición. Una tabla con índices secundarios locales puede almacenar cualquier número de elementos, siempre y cuando el tamaño total de cualquier valor de clave de partición individual no supere los 10 GB. Para obtener más información, consulte [Límite del tamaño de una colección de elementos](#LSI.ItemCollections.SizeLimit).
## Consideraciones sobre el rendimiento aprovisionado para los índices secundarios locales
Al crear una tabla en DynamoDB, se provisionan unidades de capacidad de lectura y escritura para la carga de trabajo prevista de esa tabla. Esta carga de trabajo incluye la actividad de lectura y escritura en los índices secundarios locales de la tabla.
Para ver las tarifas vigentes de la capacidad de rendimiento aprovisionada, visite [Precios de Amazon DynamoDB](https://aws.amazon.com/dynamodb/pricing).
### Unidades de capacidad de lectura
Cuando se realiza una consulta en un índice secundario local, el número de unidades de capacidad de lectura consumidas depende de cómo se obtiene acceso a los datos.
Al igual que ocurre con las consultas de tablas, las consultas de índices pueden utilizar lecturas consistentes finales o de consistencia alta, según el valor de `ConsistentRead`. Una lectura de consistencia alta consume una unidad de capacidad de lectura; una lectura eventualmente consistente consume solo la mitad. Por lo tanto, elegir la opción de lecturas consistentes finales permite reducir los cargos de unidades de capacidad de lectura.
Para las consultas de índices que solo solicitan claves de índice y atributos proyectados, DynamoDB calcula la actividad de lectura provisionada de la misma forma que para las consultas de tablas. La única diferencia es que el cálculo se basa en el tamaño de las entradas del índice, no en el tamaño del elemento en la tabla base. El número de unidades de capacidad de lectura es la suma de todos los tamaños de los atributos proyectados para todos los elementos devueltos; el resultado se redondea al múltiplo de 4 KB inmediatamente superior. Para obtener más información sobre cómo calcula DynamoDB el consumo de rendimiento aprovisionado, consulte [Modo de capacidad aprovisionada de DynamoDB](provisioned-capacity-mode.md).
Para indexar consultas que leen atributos no proyectados en el índice secundario, DynamoDB tendrá que recuperar esos atributos de la tabla base, además de leer los atributos proyectados en el índice. Estas recuperaciones tienen lugar cuando se incluyen atributos no proyectados en los parámetros `Select` o `ProjectionExpression` de la operación `Query`. Las recuperaciones provocan latencia adicional en las respuestas a las consultas y también devengan un mayor coste de desempeño provisionado. Esto se debe a que, además de las lecturas en el índice secundario local que se han descrito anteriormente, se le cobrarán unidades de capacidad de lectura por cada elemento recuperado de la tabla base. Este cargo incluye la lectura de cada elemento completo de la tabla, no solo de los atributos solicitados.
El tamaño máximo de los resultados que devuelve una operación `Query` es de 1 MB. Esta cifra incluye los tamaños de todos los nombres y valores de los atributos de todos los elementos devueltos. Sin embargo, si una consulta de un índice secundario local hace que DynamoDB recupere atributos de elementos de la tabla base, el tamaño máximo de los datos de los resultados podría ser inferior. En este caso, el tamaño del resultado es la suma de:
+ El tamaño de los elementos coincidentes del índice, redondeado al múltiplo de 4 KB inmediatamente superior.
+ El tamaño de cada elemento coincidente de la tabla base, redondeado individualmente al múltiplo de 4 KB inmediatamente superior.
Usando esta fórmula, el tamaño máximo de los resultados que devuelve una operación Query también es de 1 MB.
Por ejemplo, tomemos una tabla en la que el tamaño de cada elemento es de 300 bytes. Existe un índice secundario local en esa tabla, pero solo se proyectan en él 200 bytes de cada elemento. Ahora, supongamos que se ejecuta `Query` en este índice, que la consulta requiere recuperaciones en la tabla para cada elemento y que la consulta devuelve 4 elementos. DynamoDB calcula lo siguiente:
+ El tamaño de los elementos coincidentes en el índice: 200 bytes × 4 elementos = 800 bytes; este valor se redondea hasta 4 KB.
+ El tamaño de cada elemento coincidente de la tabla base: (300 bytes, redondeados al múltiplo de 4 KB inmediatamente superior) × 4 elementos = 16 KB.
Por lo tanto, el tamaño total de los datos del resultado es de 20 KB.
### Unidades de capacidad de escritura
Cuando se agrega, actualiza o elimina un elemento de una tabla, la actualización de los índices secundarios locales consumirá unidades de capacidad de escritura provisionadas para la tabla. El coste total de rendimiento aprovisionado de una escritura es la suma de las unidades de capacidad de escritura consumidas al escribir en la tabla y aquellas consumidas al actualizar los índices secundarios locales.
El coste de escribir un elemento en un índice secundario local depende de varios factores:
+ Si escribe un nuevo elemento en la tabla que define un atributo indexado o actualiza un elemento existente para definir un atributo indexado no definido previamente, se requiere una operación de escritura para colocar el elemento en el índice.
+ Si al actualizar la tabla se cambia el valor de un atributo de clave indexado (de A a B), se requieren dos escrituras: una para eliminar el elemento anterior del índice y otra para colocar el nuevo elemento en el índice.
+ Si ya hay un elemento en el índice, pero al escribir en la tabla se elimina el atributo indexado, se requiere una escritura para eliminar la proyección del elemento anterior del índice.
+ Si no hay ningún elemento presente en el índice antes o después de actualizar el elemento, no se devenga ningún coste de escritura adicional para el índice.
Al calcular las unidades de capacidad de escritura, en todos estos factores se presupone que el tamaño de cada elemento del índice es menor o igual que el tamaño de elemento de 1 KB. Las entradas de índice de mayor tamaño requieren más unidades de capacidad de escritura. Para minimizar los costes de escritura, es conveniente estudiar qué atributos tendrán que devolver las consultas y proyectar solamente esos atributos en el índice.
## Consideraciones sobre el almacenamiento para los índices secundarios locales
Cuando una aplicación escribe un elemento en una tabla, DynamoDB copia automáticamente el subconjunto de atributos correcto en todos los índices secundarios locales en los que deban aparecer esos atributos. Se aplica un cargo en su cuenta de AWS por el almacenamiento del elemento en la tabla base y también por el almacenamiento de los atributos en todos los índices secundarios locales de esa tabla.
La cantidad de espacio utilizado por un elemento de índice es la suma de lo siguiente:
+ El tamaño en bytes de la clave principal (clave de partición y clave de ordenación) de la tabla base
+ El tamaño en bytes del atributo de clave de índice
+ El tamaño en bytes de los atributos proyectados (si procede)
+ 100 bytes de gastos generales por cada elemento de índice
Para calcular los requisitos de almacenamiento de un índice secundario local, puede calcular el tamaño medio de un elemento del índice y, a continuación, multiplicarlo por el número de elementos del índice.
Si una tabla contiene un elemento en el que no se ha definido un atributo determinado, pero ese atributo se ha definido como clave de ordenación del índice, DynamoDB no escribirá ningún dato para ese elemento en el índice.
## Colecciones de elementos en los índices secundarios locales
**nota**
Esta sección solo concierne a las tablas que tienen índices secundarios locales.
En DynamoDB, una *colección de elementos* es cualquier grupo de elementos que contiene el mismo valor de clave de partición en una tabla y todos sus índices secundarios locales. En los ejemplos utilizados en esta sección, la clave de partición de la tabla `Thread` es `ForumName` y la clave de partición de `LastPostIndex`también es `ForumName`. Todos los elementos de la tabla y del índice que tienen el mismo valor de `ForumName` forman parte de la misma colección de elementos. Por ejemplo, en la tabla `Thread` y en el índice secundario local`LastPostIndex` hay una colección de elementos para el foro `EC2` y otra colección de elementos distinta para el foro `RDS`.
En el siguiente diagrama se muestra la colección de elementos del foro `S3`.
![\[Una colección de elementos de DynamoDB con elementos de tabla e índice secundario local que tienen el mismo valor de clave de partición de S3.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/LSI_04.png)
En este diagrama, la colección de elementos consta de todos los elementos de `Thread` y `LastPostIndex` donde el valor de clave de partición `ForumName` es "S3". Si hay otros índices secundarios locales en la tabla, los elementos de esos índices cuyo valor de `ForumName` sea "S3" también formarán parte de la colección de elementos.
Puede utilizar cualquiera de las siguientes operaciones de DynamoDB para devolver información sobre las colecciones de elementos:
+ `BatchWriteItem`
+ `DeleteItem`
+ `PutItem`
+ `UpdateItem`
+ `TransactWriteItems`
Todas estas operaciones admiten el parámetro `ReturnItemCollectionMetrics`. Si establece este parámetro en `SIZE`, podrá ver información sobre el tamaño de cada colección de elementos en el índice.
**Example**
A continuación se muestra un ejemplo del resultado de una operación `UpdateItem` en la tabla `Thread`, con `ReturnItemCollectionMetrics` configurado en `SIZE`. El elemento que se ha actualizado tenía un valor de `ForumName` de "EC2", por lo que el resultado incluye información acerca de esa colección de elementos.
```
{
ItemCollectionMetrics: {
ItemCollectionKey: {
ForumName: "EC2"
},
SizeEstimateRangeGB: [0.0, 1.0]
}
}
```
El objeto `SizeEstimateRangeGB` muestra que el tamaño de esta colección de elementos está comprendido entre 0 y 1 GB. DynamoDB actualiza periódicamente este cálculo del tamaño, de modo que las cifras podrían ser distintas la próxima vez que se modifique el elemento.
### Límite del tamaño de una colección de elementos
El tamaño máximo de cualquier colección de elementos para una tabla que tenga uno o más índices secundarios locales es de 10 GB. Esto no se aplica a las colecciones de elementos en tablas sin índices secundarios locales, y tampoco se aplica a las colecciones de elementos en índices secundarios generales. Solo se ven afectadas las tablas que tienen uno o más índices secundarios locales.
Si una colección de elementos supera el límite de 10 GB, DynamoDB puede devolver una `ItemCollectionSizeLimitExceededException` y es posible que no pueda agregar más elementos a la colección de elementos ni incrementar los tamaños de los elementos contenidos en ella. (Las operaciones de lectura y escritura que reduzcan el tamaño de la colección de elementos sí se permitirán). También podrá agregar elementos a otras colecciones de elementos.
Para reducir el tamaño de una colección de elementos, puede elegir una de las siguientes opciones:
+ Eliminar todos los elementos innecesarios que tengan el valor de clave de partición de que se trate. Al eliminar estos elementos de la tabla base, DynamoDB también eliminará las entradas de índice cuyo valor de clave de partición sea el mismo.
+ Actualizar los elementos eliminando atributos o reduciendo el tamaño de estos últimos. Si estos atributos se han proyectado en uno o varios índices secundarios locales, DynamoDB también reducirá el tamaño de las entradas de índice correspondientes.
+ Crear una nueva tabla con las mismas clave de partición y clave de ordenación y, a continuación, mover elementos de la tabla anterior a la nueva. Esto puede ser conveniente si una tabla contiene datos históricos a los que se obtiene acceso con poca frecuencia. Puede considerar también el archivado de estos datos históricos en Amazon Simple Storage Service (Amazon S3).
Cuando el tamaño total de la colección de elementos disminuye por debajo de 10 GB, podrá volver a agregar elementos con el mismo valor de clave de partición.
Como práctica recomendada, es preferible instrumentar la aplicación de tal forma que monitorice los tamaños de las colecciones de elementos. Una forma de hacerlo es establecer el parámetro `ReturnItemCollectionMetrics` en `SIZE` siempre que utilice `BatchWriteItem`, `DeleteItem`, `PutItem` o `UpdateItem`. La aplicación debe examinar el objeto `ReturnItemCollectionMetrics` en los resultados y registrar un mensaje de error cada vez que una colección de elementos supere un límite definido por el usuario (8 GB, por ejemplo). Establecer un límite menor que 10 GB ofrece un mecanismo de advertencia precoz sistema que le permitirá saber qué colección de elementos está próxima a alcanzar el límite a tiempo para adoptar las medidas pertinentes.
### Colecciones de elementos y particiones
En una tabla con uno o más índices secundarios locales, cada colección de elementos se almacena en una partición. El tamaño total de esa colección de elementos está limitado a la capacidad de esa partición: 10 GB. En el caso de una aplicación en la que el modelo de datos incluya colecciones de elementos cuyo tamaño no esté limitado, o en la que pueda esperar razonablemente que algunas colecciones de elementos aumenten más allá de los 10 GB en el futuro, debería considerar la posibilidad de utilizar un índice secundario general.
Debe diseñar las aplicaciones de tal forma que los datos de las tablas se distribuyan uniformemente entre los distintos valores de clave de partición. Para las tablas que tienen índices secundarios locales, las aplicaciones no deben crear "puntos calientes" de actividad de lectura y escritura dentro de una misma colección de elementos de una sola partición.
# Trabajar con índices secundarios locales: Java
Puede utilizar la API de documentos AWS SDK para Java para crear una tabla Amazon DynamoDB con uno o varios índices secundarios locales, describir los índices de la tabla y utilizarlos para realizar consultas.
A continuación se indican los pasos comunes para las operaciones con tablas mediante el API de documentos del AWS SDK para Java.
1. Cree una instancia de la clase `DynamoDB`.
1. Cree los objetos de solicitud correspondientes para proporcionar los parámetros obligatorios y opcionales de la operación.
1. Llame al método apropiado proporcionado por el cliente que ha creado en el paso anterior.
**Topics**
+ [Creación de una tabla con un índice secundario local](#LSIJavaDocumentAPI.CreateTableWithIndex)
+ [Descripción de una tabla con un índice secundario local](#LSIJavaDocumentAPI.DescribeTableWithIndex)
+ [Consulta de un índice secundario local](#LSIJavaDocumentAPI.QueryAnIndex)
+ [Ejemplo: índices secundarios locales mediante la API de documentos de Java](LSIJavaDocumentAPI.Example.md)
## Creación de una tabla con un índice secundario local
Los índices secundarios locales se deben crear a la vez que se crea la tabla. Para ello, utilice el método `createTable` e indique las especificaciones para uno o varios índices secundarios locales. En el ejemplo de código Java siguiente, se crea una tabla para contener información sobre las canciones de una colección de música. La clave de partición es `Artist` y la de ordenación, `SongTitle`. Un índice secundario, `AlbumTitleIndex`, facilita las consultas por título de álbum.
A continuación se indican los pasos que hay que seguir para crear una tabla con un índice secundario local mediante la API de documentos de DynamoDB.
1. Cree una instancia de la clase `DynamoDB`.
1. Cree una instancia de la clase `CreateTableRequest` para proporcionar la información de solicitud.
Debe proporcionar el nombre de la tabla, su clave principal y los valores de rendimiento aprovisionado. Para el índice secundario local, debe proporcionar el nombre de índice, el nombre y el tipo de datos de la clave de ordenación del índice, el esquema de claves del índice y la proyección de atributos.
1. Llame al método `createTable` proporcionando el objeto de solicitud como parámetro.
En el siguiente ejemplo de código Java se muestran los pasos anteriores. En el fragmento se crea una tabla (`Music`) con un índice secundario basado en el atributo `AlbumTitle`. La clave de partición y la clave de ordenación de la tabla, además de la clave de ordenación del índice, son los únicos atributos proyectados en el índice.
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
CreateTableRequest createTableRequest = new CreateTableRequest().withTableName(tableName);
//ProvisionedThroughput
createTableRequest.setProvisionedThroughput(new ProvisionedThroughput().withReadCapacityUnits((long)5).withWriteCapacityUnits((long)5));
//AttributeDefinitions
ArrayList attributeDefinitions= new ArrayList();
attributeDefinitions.add(new AttributeDefinition().withAttributeName("Artist").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("SongTitle").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("AlbumTitle").withAttributeType("S"));
createTableRequest.setAttributeDefinitions(attributeDefinitions);
//KeySchema
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement().withAttributeName("Artist").withKeyType(KeyType.HASH)); //Partition key
tableKeySchema.add(new KeySchemaElement().withAttributeName("SongTitle").withKeyType(KeyType.RANGE)); //Sort key
createTableRequest.setKeySchema(tableKeySchema);
ArrayList indexKeySchema = new ArrayList();
indexKeySchema.add(new KeySchemaElement().withAttributeName("Artist").withKeyType(KeyType.HASH)); //Partition key
indexKeySchema.add(new KeySchemaElement().withAttributeName("AlbumTitle").withKeyType(KeyType.RANGE)); //Sort key
Projection projection = new Projection().withProjectionType(ProjectionType.INCLUDE);
ArrayList nonKeyAttributes = new ArrayList();
nonKeyAttributes.add("Genre");
nonKeyAttributes.add("Year");
projection.setNonKeyAttributes(nonKeyAttributes);
LocalSecondaryIndex localSecondaryIndex = new LocalSecondaryIndex()
.withIndexName("AlbumTitleIndex").withKeySchema(indexKeySchema).withProjection(projection);
ArrayList localSecondaryIndexes = new ArrayList();
localSecondaryIndexes.add(localSecondaryIndex);
createTableRequest.setLocalSecondaryIndexes(localSecondaryIndexes);
Table table = dynamoDB.createTable(createTableRequest);
System.out.println(table.getDescription());
```
Debe esperar hasta que DynamoDB cree la tabla y establezca el estado de esta última en `ACTIVE`. A partir de ese momento, puede comenzar a incluir elementos de datos en la tabla.
## Descripción de una tabla con un índice secundario local
Para obtener información acerca de los índices secundarios locales en una tabla, utilice el método `describeTable`. Para cada índice, puede obtener acceso a su nombre, esquema de claves y atributos proyectados.
A continuación, se muestran los pasos que hay que seguir para obtener acceso a la información de un índice secundario local de una tabla mediante la API de documentos de AWS SDK para Java.
1. Cree una instancia de la clase `DynamoDB`.
1. Cree una instancia de la clase `Table`. Debe proporcionar el nombre de la tabla.
1. Llame al método `describeTable` del objeto `Table`.
En el siguiente ejemplo de código Java se muestran los pasos anteriores.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
Table table = dynamoDB.getTable(tableName);
TableDescription tableDescription = table.describe();
List localSecondaryIndexes
= tableDescription.getLocalSecondaryIndexes();
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
Iterator lsiIter = localSecondaryIndexes.iterator();
while (lsiIter.hasNext()) {
LocalSecondaryIndexDescription lsiDescription = lsiIter.next();
System.out.println("Info for index " + lsiDescription.getIndexName() + ":");
Iterator kseIter = lsiDescription.getKeySchema().iterator();
while (kseIter.hasNext()) {
KeySchemaElement kse = kseIter.next();
System.out.printf("\t%s: %s\n", kse.getAttributeName(), kse.getKeyType());
}
Projection projection = lsiDescription.getProjection();
System.out.println("\tThe projection type is: " + projection.getProjectionType());
if (projection.getProjectionType().toString().equals("INCLUDE")) {
System.out.println("\t\tThe non-key projected attributes are: " + projection.getNonKeyAttributes());
}
}
```
## Consulta de un índice secundario local
Puede utilizar la operación `Query` en un índice secundario local de un modo bastante parecido a como `Query` se usa en una tabla. Debe especificar el nombre del índice, los criterios de consulta de la clave de ordenación del índice y los atributos que desea devolver. En este ejemplo, el índice es `AlbumTitleIndex` y la clave de ordenación del índice es `AlbumTitle`.
Los únicos atributos devueltos son aquellos que se han proyectado en el índice. Puede modificar esta consulta de modo que también seleccione atributos sin clave, pero esto requeriría realizar actividad de recuperación en la tabla, lo que resulta relativamente costoso. Para obtener más información sobre recuperaciones de tablas, consulte [Proyecciones de atributos](LSI.md#LSI.Projections).
A continuación se indican los pasos que hay que seguir para consultar un índice secundario local con la API de documentos de AWS SDK para Java.
1. Cree una instancia de la clase `DynamoDB`.
1. Cree una instancia de la clase `Table`. Debe proporcionar el nombre de la tabla.
1. Cree una instancia de la clase `Index`. Debe proporcionar el nombre del índice.
1. Llame al método `query` de la clase `Index`.
En el siguiente ejemplo de código Java se muestran los pasos anteriores.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
Table table = dynamoDB.getTable(tableName);
Index index = table.getIndex("AlbumTitleIndex");
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("Artist = :v_artist and AlbumTitle = :v_title")
.withValueMap(new ValueMap()
.withString(":v_artist", "Acme Band")
.withString(":v_title", "Songs About Life"));
ItemCollection items = index.query(spec);
Iterator
- itemsIter = items.iterator();
while (itemsIter.hasNext()) {
Item item = itemsIter.next();
System.out.println(item.toJSONPretty());
}
```
### Lecturas coherentes en un índice secundario local
A diferencia de los índices secundarios globales, que solo admiten lecturas coherentes posteriores, un índice secundario local admite lecturas coherentes posteriores y lecturas altamente coherentes. Una lectura de consistencia alta de un índice secundario local siempre devolverá los valores actualizados más recientemente. Si la consulta tiene que recuperar atributos adicionales de la tabla base, estos atributos recuperados también son coherentes con respecto al índice.
De forma predeterminada, `Query` usa lecturas coherentes posteriores. Para solicitar una lectura altamente coherente, establezca `ConsistentRead` en `true` en `QuerySpec`. A continuación, se muestran consultas `AlbumTitleIndex` mediante una lectura altamente coherente:
**Example**
```
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("Artist = :v_artist and AlbumTitle = :v_title")
.withValueMap(new ValueMap()
.withString(":v_artist", "Acme Band")
.withString(":v_title", "Songs About Life"))
.withConsistentRead(true);
```
**nota**
una lectura altamente coherente consume una unidad de capacidad de lectura por cada 4 KB de datos devueltos (redondeados al alza), mientras que una lectura coherente posterior consume la mitad. Por ejemplo, una lectura altamente coherente que devuelva 9 KB de datos consume 3 unidades de capacidad de lectura (9 KB/ 4 KB = 2,25, redondeada a 3), mientras que la misma consulta que utilice una lectura coherente posterior consume 1,5 unidades de capacidad de lectura. Si la aplicación puede tolerar la lectura de datos que puedan estar ligeramente obsoletos, utilice lecturas coherentes posteriores para reducir el uso de la capacidad de lectura. Para obtener más información, consulte [Unidades de capacidad de lectura](LSI.md#LSI.ThroughputConsiderations.Reads).
# Ejemplo: índices secundarios locales mediante la API de documentos de Java
En el siguiente ejemplo de código Java se muestra cómo usar índices secundarios locales en Amazon DynamoDB. En el ejemplo se crea una tabla denominada `CustomerOrders` cuya clave de partición es `CustomerId` y cuya clave de ordenación es `OrderId`. Hay dos índices secundarios locales en esta tabla:
+ `OrderCreationDateIndex`: la clave de ordenación es `OrderCreationDate` y los atributos siguientes se proyectan en el índice:
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex`: la clave de ordenación es `IsOpen` y todos los atributos de la tabla se proyectan en el índice.
Después de que se crea la tabla `CustomerOrders`, el programa carga la tabla con datos que representan pedidos de clientes. A continuación, consulta los datos utilizando los índices secundarios locales. Por último, el programa elimina la tabla `CustomerOrders`.
Para obtener instrucciones paso a paso para probar el siguiente ejemplo, consulte [Ejemplos de código Java](CodeSamples.Java.md).
**Example**
```
package com.example.dynamodb;
import software.amazon.awssdk.core.waiters.WaiterResponse;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.*;
import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter;
import java.util.HashMap;
import java.util.Map;
public class DocumentAPILocalSecondaryIndexExample {
static DynamoDbClient client = DynamoDbClient.create();
public static String tableName = "CustomerOrders";
public static void main(String[] args) {
createTable();
loadData();
query(null);
query("IsOpenIndex");
query("OrderCreationDateIndex");
deleteTable(tableName);
}
public static void createTable() {
CreateTableRequest request = CreateTableRequest.builder()
.tableName(tableName)
.provisionedThroughput(ProvisionedThroughput.builder()
.readCapacityUnits(1L)
.writeCapacityUnits(1L)
.build())
.attributeDefinitions(
AttributeDefinition.builder().attributeName("CustomerId").attributeType(ScalarAttributeType.S).build(),
AttributeDefinition.builder().attributeName("OrderId").attributeType(ScalarAttributeType.N).build(),
AttributeDefinition.builder().attributeName("OrderCreationDate").attributeType(ScalarAttributeType.N).build(),
AttributeDefinition.builder().attributeName("IsOpen").attributeType(ScalarAttributeType.N).build())
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("OrderId").keyType(KeyType.RANGE).build())
.localSecondaryIndexes(
LocalSecondaryIndex.builder()
.indexName("OrderCreationDateIndex")
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("OrderCreationDate").keyType(KeyType.RANGE).build())
.projection(Projection.builder()
.projectionType(ProjectionType.INCLUDE)
.nonKeyAttributes("ProductCategory", "ProductName")
.build())
.build(),
LocalSecondaryIndex.builder()
.indexName("IsOpenIndex")
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("IsOpen").keyType(KeyType.RANGE).build())
.projection(Projection.builder()
.projectionType(ProjectionType.ALL)
.build())
.build())
.build();
System.out.println("Creating table " + tableName + "...");
client.createTable(request);
try (DynamoDbWaiter waiter = client.waiter()) {
WaiterResponse response = waiter.waitUntilTableExists(r -> r.tableName(tableName));
response.matched().response().ifPresent(System.out::println);
}
}
public static void query(String indexName) {
System.out.println("\n***********************************************************\n");
System.out.println("Querying table " + tableName + "...");
if ("IsOpenIndex".equals(indexName)) {
System.out.println("\nUsing index: '" + indexName + "': Bob's orders that are open.");
System.out.println("Only a user-specified list of attributes are returned\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
values.put(":v_isopen", AttributeValue.builder().n("1").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName(indexName)
.keyConditionExpression("CustomerId = :v_custid and IsOpen = :v_isopen")
.expressionAttributeValues(values)
.projectionExpression("OrderCreationDate, ProductCategory, ProductName, OrderStatus")
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
} else if ("OrderCreationDateIndex".equals(indexName)) {
System.out.println("\nUsing index: '" + indexName + "': Bob's orders that were placed after 01/31/2015.");
System.out.println("Only the projected attributes are returned\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
values.put(":v_orddate", AttributeValue.builder().n("20150131").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName(indexName)
.keyConditionExpression("CustomerId = :v_custid and OrderCreationDate >= :v_orddate")
.expressionAttributeValues(values)
.select(Select.ALL_PROJECTED_ATTRIBUTES)
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
} else {
System.out.println("\nNo index: All of Bob's orders, by OrderId:\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.keyConditionExpression("CustomerId = :v_custid")
.expressionAttributeValues(values)
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
}
}
public static void deleteTable(String tableName) {
System.out.println("Deleting table " + tableName + "...");
client.deleteTable(DeleteTableRequest.builder().tableName(tableName).build());
try (DynamoDbWaiter waiter = client.waiter()) {
waiter.waitUntilTableNotExists(r -> r.tableName(tableName));
}
}
public static void loadData() {
System.out.println("Loading data into table " + tableName + "...");
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("1").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150101").build(),
"ProductCategory", AttributeValue.builder().s("Book").build(),
"ProductName", AttributeValue.builder().s("The Great Outdoors").build(),
"OrderStatus", AttributeValue.builder().s("PACKING ITEMS").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("2").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150221").build(),
"ProductCategory", AttributeValue.builder().s("Bike").build(),
"ProductName", AttributeValue.builder().s("Super Mountain").build(),
"OrderStatus", AttributeValue.builder().s("ORDER RECEIVED").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("3").build(),
"OrderCreationDate", AttributeValue.builder().n("20150304").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("A Quiet Interlude").build(),
"OrderStatus", AttributeValue.builder().s("IN TRANSIT").build(),
"ShipmentTrackingId", AttributeValue.builder().s("176493").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150111").build(),
"ProductCategory", AttributeValue.builder().s("Movie").build(),
"ProductName", AttributeValue.builder().s("Calm Before The Storm").build(),
"OrderStatus", AttributeValue.builder().s("SHIPPING DELAY").build(),
"ShipmentTrackingId", AttributeValue.builder().s("859323").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("2").build(),
"OrderCreationDate", AttributeValue.builder().n("20150124").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("E-Z Listening").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("756943").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("3").build(),
"OrderCreationDate", AttributeValue.builder().n("20150221").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("Symphony 9").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("645193").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("4").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150222").build(),
"ProductCategory", AttributeValue.builder().s("Hardware").build(),
"ProductName", AttributeValue.builder().s("Extra Heavy Hammer").build(),
"OrderStatus", AttributeValue.builder().s("PACKING ITEMS").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("5").build(),
"OrderCreationDate", AttributeValue.builder().n("20150309").build(),
"ProductCategory", AttributeValue.builder().s("Book").build(),
"ProductName", AttributeValue.builder().s("How To Cook").build(),
"OrderStatus", AttributeValue.builder().s("IN TRANSIT").build(),
"ShipmentTrackingId", AttributeValue.builder().s("440185").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("6").build(),
"OrderCreationDate", AttributeValue.builder().n("20150318").build(),
"ProductCategory", AttributeValue.builder().s("Luggage").build(),
"ProductName", AttributeValue.builder().s("Really Big Suitcase").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("893927").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("7").build(),
"OrderCreationDate", AttributeValue.builder().n("20150324").build(),
"ProductCategory", AttributeValue.builder().s("Golf").build(),
"ProductName", AttributeValue.builder().s("PGA Pro II").build(),
"OrderStatus", AttributeValue.builder().s("OUT FOR DELIVERY").build(),
"ShipmentTrackingId", AttributeValue.builder().s("383283").build()));
}
private static void putItem(Map item) {
client.putItem(PutItemRequest.builder().tableName(tableName).item(item).build());
}
}
```
# Trabajar con índices secundarios locales: .NET
**Topics**
+ [Creación de una tabla con un índice secundario local](#LSILowLevelDotNet.CreateTableWithIndex)
+ [Descripción de una tabla con un índice secundario local](#LSILowLevelDotNet.DescribeTableWithIndex)
+ [Consulta de un índice secundario local](#LSILowLevelDotNet.QueryAnIndex)
+ [Ejemplo: índices secundarios locales que utilizan la API de bajo nivel de AWS SDK para .NET](LSILowLevelDotNet.Example.md)
Puede utilizar la API de bajo nivel AWS SDK para .NET para crear una tabla Amazon DynamoDB con uno o varios índices secundarios locales, describir los índices de la tabla y utilizarlos para realizar consultas. Estas operaciones se mapean a las acciones correspondientes del API de bajo nivel de DynamoDB. Para obtener más información, consulte [Ejemplos de código .NET](CodeSamples.DotNet.md).
A continuación se indican los pasos comunes para las operaciones con tablas mediante el API de bajo nivel de .NET.
1. Cree una instancia de la clase `AmazonDynamoDBClient`.
1. Cree los objetos de solicitud correspondientes para proporcionar los parámetros obligatorios y opcionales de la operación.
Por ejemplo, cree un objeto `CreateTableRequest` para crear una tabla y un objeto `QueryRequest` para consultar una tabla o un índice.
1. Ejecute el método apropiado proporcionado por el cliente que ha creado en el paso anterior.
## Creación de una tabla con un índice secundario local
Los índices secundarios locales se deben crear a la vez que se crea la tabla. Para ello, utilice `CreateTable` e indique las especificaciones para uno o varios índices secundarios globales. En el ejemplo de código C\$1 siguiente, se crea una tabla para contener información sobre las canciones de una colección de música. La clave de partición es `Artist` y la de ordenación, `SongTitle`. Un índice secundario, `AlbumTitleIndex`, facilita las consultas por título de álbum.
A continuación se indican los pasos que hay que seguir para crear una tabla con un índice secundario local mediante la API de bajo nivel de .NET.
1. Cree una instancia de la clase `AmazonDynamoDBClient`.
1. Cree una instancia de la clase `CreateTableRequest` para proporcionar la información de solicitud.
Debe proporcionar el nombre de la tabla, su clave principal y los valores de rendimiento aprovisionado. Para el índice secundario local, debe proporcionar el nombre de índice, el nombre y el tipo de datos de la clave de ordenación del índice, el esquema de claves del índice y la proyección de atributos.
1. Ejecute el método `CreateTable` proporcionando el objeto de solicitud como parámetro.
En el siguiente ejemplo de código C\$1 se ponen en práctica los pasos anteriores. En el fragmento se crea una tabla (`Music`) con un índice secundario basado en el atributo `AlbumTitle`. La clave de partición y la clave de ordenación de la tabla, además de la clave de ordenación del índice, son los únicos atributos proyectados en el índice.
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "Music";
CreateTableRequest createTableRequest = new CreateTableRequest()
{
TableName = tableName
};
//ProvisionedThroughput
createTableRequest.ProvisionedThroughput = new ProvisionedThroughput()
{
ReadCapacityUnits = (long)5,
WriteCapacityUnits = (long)5
};
//AttributeDefinitions
List attributeDefinitions = new List();
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "Artist",
AttributeType = "S"
});
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "SongTitle",
AttributeType = "S"
});
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "AlbumTitle",
AttributeType = "S"
});
createTableRequest.AttributeDefinitions = attributeDefinitions;
//KeySchema
List tableKeySchema = new List();
tableKeySchema.Add(new KeySchemaElement() { AttributeName = "Artist", KeyType = "HASH" }); //Partition key
tableKeySchema.Add(new KeySchemaElement() { AttributeName = "SongTitle", KeyType = "RANGE" }); //Sort key
createTableRequest.KeySchema = tableKeySchema;
List indexKeySchema = new List();
indexKeySchema.Add(new KeySchemaElement() { AttributeName = "Artist", KeyType = "HASH" }); //Partition key
indexKeySchema.Add(new KeySchemaElement() { AttributeName = "AlbumTitle", KeyType = "RANGE" }); //Sort key
Projection projection = new Projection() { ProjectionType = "INCLUDE" };
List nonKeyAttributes = new List();
nonKeyAttributes.Add("Genre");
nonKeyAttributes.Add("Year");
projection.NonKeyAttributes = nonKeyAttributes;
LocalSecondaryIndex localSecondaryIndex = new LocalSecondaryIndex()
{
IndexName = "AlbumTitleIndex",
KeySchema = indexKeySchema,
Projection = projection
};
List localSecondaryIndexes = new List();
localSecondaryIndexes.Add(localSecondaryIndex);
createTableRequest.LocalSecondaryIndexes = localSecondaryIndexes;
CreateTableResponse result = client.CreateTable(createTableRequest);
Console.WriteLine(result.CreateTableResult.TableDescription.TableName);
Console.WriteLine(result.CreateTableResult.TableDescription.TableStatus);
```
Debe esperar hasta que DynamoDB cree la tabla y establezca el estado de esta última en `ACTIVE`. A partir de ese momento, puede comenzar a incluir elementos de datos en la tabla.
## Descripción de una tabla con un índice secundario local
Para obtener información acerca de los índices secundarios locales en una tabla, utilice la API `DescribeTable`. Para cada índice, puede obtener acceso a su nombre, esquema de claves y atributos proyectados.
A continuación se indican los pasos que hay que seguir para acceder a la información de un índice secundario local de una tabla mediante el API de bajo nivel de .NET.
1. Cree una instancia de la clase `AmazonDynamoDBClient`.
1. Cree una instancia de la clase `DescribeTableRequest` para proporcionar la información de solicitud. Debe proporcionar el nombre de la tabla.
1. Ejecute el método `describeTable` proporcionando el objeto de solicitud como parámetro.
En el siguiente ejemplo de código C\$1 se ponen en práctica los pasos anteriores.
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "Music";
DescribeTableResponse response = client.DescribeTable(new DescribeTableRequest() { TableName = tableName });
List localSecondaryIndexes =
response.DescribeTableResult.Table.LocalSecondaryIndexes;
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
foreach (LocalSecondaryIndexDescription lsiDescription in localSecondaryIndexes)
{
Console.WriteLine("Info for index " + lsiDescription.IndexName + ":");
foreach (KeySchemaElement kse in lsiDescription.KeySchema)
{
Console.WriteLine("\t" + kse.AttributeName + ": key type is " + kse.KeyType);
}
Projection projection = lsiDescription.Projection;
Console.WriteLine("\tThe projection type is: " + projection.ProjectionType);
if (projection.ProjectionType.ToString().Equals("INCLUDE"))
{
Console.WriteLine("\t\tThe non-key projected attributes are:");
foreach (String s in projection.NonKeyAttributes)
{
Console.WriteLine("\t\t" + s);
}
}
}
```
## Consulta de un índice secundario local
Puede utilizar `Query` en un índice secundario local de un modo bastante parecido a como usa `Query` en una tabla. Debe especificar el nombre del índice, los criterios de consulta de la clave de ordenación del índice y los atributos que desea devolver. En este ejemplo, el índice es `AlbumTitleIndex` y la clave de ordenación del índice es `AlbumTitle`.
Los únicos atributos devueltos son aquellos que se han proyectado en el índice. Puede modificar esta consulta de modo que también seleccione atributos sin clave, pero esto requeriría realizar actividad de recuperación en la tabla, lo que resulta relativamente costoso. Para obtener más información sobre recuperaciones de tablas, consulte [Proyecciones de atributos](LSI.md#LSI.Projections)
A continuación se indican los pasos que hay que seguir para consultar un índice secundario local mediante la API de bajo nivel de .NET.
1. Cree una instancia de la clase `AmazonDynamoDBClient`.
1. Cree una instancia de la clase `QueryRequest` para proporcionar la información de solicitud.
1. Ejecute el método `query` proporcionando el objeto de solicitud como parámetro.
En el siguiente ejemplo de código C\$1 se ponen en práctica los pasos anteriores.
**Example**
```
QueryRequest queryRequest = new QueryRequest
{
TableName = "Music",
IndexName = "AlbumTitleIndex",
Select = "ALL_ATTRIBUTES",
ScanIndexForward = true,
KeyConditionExpression = "Artist = :v_artist and AlbumTitle = :v_title",
ExpressionAttributeValues = new Dictionary()
{
{":v_artist",new AttributeValue {S = "Acme Band"}},
{":v_title",new AttributeValue {S = "Songs About Life"}}
},
};
QueryResponse response = client.Query(queryRequest);
foreach (var attribs in response.Items)
{
foreach (var attrib in attribs)
{
Console.WriteLine(attrib.Key + " ---> " + attrib.Value.S);
}
Console.WriteLine();
}
```
# Ejemplo: índices secundarios locales que utilizan la API de bajo nivel de AWS SDK para .NET
En el siguiente ejemplo de código C\$1 se muestra cómo usar índices secundarios locales en Amazon DynamoDB. En el ejemplo se crea una tabla denominada `CustomerOrders` cuya clave de partición es `CustomerId` y cuya clave de ordenación es `OrderId`. Hay dos índices secundarios locales en esta tabla:
+ `OrderCreationDateIndex`: la clave de ordenación es `OrderCreationDate` y los atributos siguientes se proyectan en el índice:
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex`: la clave de ordenación es `IsOpen` y todos los atributos de la tabla se proyectan en el índice.
Después de que se crea la tabla `CustomerOrders`, el programa carga la tabla con datos que representan pedidos de clientes. A continuación, consulta los datos utilizando los índices secundarios locales. Por último, el programa elimina la tabla `CustomerOrders`.
Para obtener instrucciones paso a paso para probar el siguiente ejemplo, consulte [Ejemplos de código .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using System.Linq;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelLocalSecondaryIndexExample
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
private static string tableName = "CustomerOrders";
static void Main(string[] args)
{
try
{
CreateTable();
LoadData();
Query(null);
Query("IsOpenIndex");
Query("OrderCreationDateIndex");
DeleteTable(tableName);
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
catch (AmazonDynamoDBException e) { Console.WriteLine(e.Message); }
catch (AmazonServiceException e) { Console.WriteLine(e.Message); }
catch (Exception e) { Console.WriteLine(e.Message); }
}
private static void CreateTable()
{
var createTableRequest =
new CreateTableRequest()
{
TableName = tableName,
ProvisionedThroughput =
new ProvisionedThroughput()
{
ReadCapacityUnits = (long)1,
WriteCapacityUnits = (long)1
}
};
var attributeDefinitions = new List()
{
// Attribute definitions for table primary key
{ new AttributeDefinition() {
AttributeName = "CustomerId", AttributeType = "S"
} },
{ new AttributeDefinition() {
AttributeName = "OrderId", AttributeType = "N"
} },
// Attribute definitions for index primary key
{ new AttributeDefinition() {
AttributeName = "OrderCreationDate", AttributeType = "N"
} },
{ new AttributeDefinition() {
AttributeName = "IsOpen", AttributeType = "N"
}}
};
createTableRequest.AttributeDefinitions = attributeDefinitions;
// Key schema for table
var tableKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
} }, //Partition key
{ new KeySchemaElement() {
AttributeName = "OrderId", KeyType = "RANGE"
} } //Sort key
};
createTableRequest.KeySchema = tableKeySchema;
var localSecondaryIndexes = new List();
// OrderCreationDateIndex
LocalSecondaryIndex orderCreationDateIndex = new LocalSecondaryIndex()
{
IndexName = "OrderCreationDateIndex"
};
// Key schema for OrderCreationDateIndex
var indexKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
} }, //Partition key
{ new KeySchemaElement() {
AttributeName = "OrderCreationDate", KeyType = "RANGE"
} } //Sort key
};
orderCreationDateIndex.KeySchema = indexKeySchema;
// Projection (with list of projected attributes) for
// OrderCreationDateIndex
var projection = new Projection()
{
ProjectionType = "INCLUDE"
};
var nonKeyAttributes = new List()
{
"ProductCategory",
"ProductName"
};
projection.NonKeyAttributes = nonKeyAttributes;
orderCreationDateIndex.Projection = projection;
localSecondaryIndexes.Add(orderCreationDateIndex);
// IsOpenIndex
LocalSecondaryIndex isOpenIndex
= new LocalSecondaryIndex()
{
IndexName = "IsOpenIndex"
};
// Key schema for IsOpenIndex
indexKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
}}, //Partition key
{ new KeySchemaElement() {
AttributeName = "IsOpen", KeyType = "RANGE"
}} //Sort key
};
// Projection (all attributes) for IsOpenIndex
projection = new Projection()
{
ProjectionType = "ALL"
};
isOpenIndex.KeySchema = indexKeySchema;
isOpenIndex.Projection = projection;
localSecondaryIndexes.Add(isOpenIndex);
// Add index definitions to CreateTable request
createTableRequest.LocalSecondaryIndexes = localSecondaryIndexes;
Console.WriteLine("Creating table " + tableName + "...");
client.CreateTable(createTableRequest);
WaitUntilTableReady(tableName);
}
public static void Query(string indexName)
{
Console.WriteLine("\n***********************************************************\n");
Console.WriteLine("Querying table " + tableName + "...");
QueryRequest queryRequest = new QueryRequest()
{
TableName = tableName,
ConsistentRead = true,
ScanIndexForward = true,
ReturnConsumedCapacity = "TOTAL"
};
String keyConditionExpression = "CustomerId = :v_customerId";
Dictionary expressionAttributeValues = new Dictionary {
{":v_customerId", new AttributeValue {
S = "bob@example.com"
}}
};
if (indexName == "IsOpenIndex")
{
Console.WriteLine("\nUsing index: '" + indexName
+ "': Bob's orders that are open.");
Console.WriteLine("Only a user-specified list of attributes are returned\n");
queryRequest.IndexName = indexName;
keyConditionExpression += " and IsOpen = :v_isOpen";
expressionAttributeValues.Add(":v_isOpen", new AttributeValue
{
N = "1"
});
// ProjectionExpression
queryRequest.ProjectionExpression = "OrderCreationDate, ProductCategory, ProductName, OrderStatus";
}
else if (indexName == "OrderCreationDateIndex")
{
Console.WriteLine("\nUsing index: '" + indexName
+ "': Bob's orders that were placed after 01/31/2013.");
Console.WriteLine("Only the projected attributes are returned\n");
queryRequest.IndexName = indexName;
keyConditionExpression += " and OrderCreationDate > :v_Date";
expressionAttributeValues.Add(":v_Date", new AttributeValue
{
N = "20130131"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else
{
Console.WriteLine("\nNo index: All of Bob's orders, by OrderId:\n");
}
queryRequest.KeyConditionExpression = keyConditionExpression;
queryRequest.ExpressionAttributeValues = expressionAttributeValues;
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
if (attr == "OrderId" || attr == "IsOpen"
|| attr == "OrderCreationDate")
{
Console.WriteLine(attr + "---> " + currentItem[attr].N);
}
else
{
Console.WriteLine(attr + "---> " + currentItem[attr].S);
}
}
Console.WriteLine();
}
Console.WriteLine("\nConsumed capacity: " + result.ConsumedCapacity.CapacityUnits + "\n");
}
private static void DeleteTable(string tableName)
{
Console.WriteLine("Deleting table " + tableName + "...");
client.DeleteTable(new DeleteTableRequest()
{
TableName = tableName
});
WaitForTableToBeDeleted(tableName);
}
public static void LoadData()
{
Console.WriteLine("Loading data into table " + tableName + "...");
Dictionary item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "1"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130101"
};
item["ProductCategory"] = new AttributeValue
{
S = "Book"
};
item["ProductName"] = new AttributeValue
{
S = "The Great Outdoors"
};
item["OrderStatus"] = new AttributeValue
{
S = "PACKING ITEMS"
};
/* no ShipmentTrackingId attribute */
PutItemRequest putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "2"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130221"
};
item["ProductCategory"] = new AttributeValue
{
S = "Bike"
};
item["ProductName"] = new AttributeValue
{
S = "Super Mountain"
};
item["OrderStatus"] = new AttributeValue
{
S = "ORDER RECEIVED"
};
/* no ShipmentTrackingId attribute */
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "3"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130304"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "A Quiet Interlude"
};
item["OrderStatus"] = new AttributeValue
{
S = "IN TRANSIT"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "176493"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "1"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130111"
};
item["ProductCategory"] = new AttributeValue
{
S = "Movie"
};
item["ProductName"] = new AttributeValue
{
S = "Calm Before The Storm"
};
item["OrderStatus"] = new AttributeValue
{
S = "SHIPPING DELAY"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "859323"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "2"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130124"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "E-Z Listening"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "756943"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "3"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130221"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "Symphony 9"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "645193"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "4"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130222"
};
item["ProductCategory"] = new AttributeValue
{
S = "Hardware"
};
item["ProductName"] = new AttributeValue
{
S = "Extra Heavy Hammer"
};
item["OrderStatus"] = new AttributeValue
{
S = "PACKING ITEMS"
};
/* no ShipmentTrackingId attribute */
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "5"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130309"
};
item["ProductCategory"] = new AttributeValue
{
S = "Book"
};
item["ProductName"] = new AttributeValue
{
S = "How To Cook"
};
item["OrderStatus"] = new AttributeValue
{
S = "IN TRANSIT"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "440185"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "6"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130318"
};
item["ProductCategory"] = new AttributeValue
{
S = "Luggage"
};
item["ProductName"] = new AttributeValue
{
S = "Really Big Suitcase"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "893927"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "7"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130324"
};
item["ProductCategory"] = new AttributeValue
{
S = "Golf"
};
item["ProductName"] = new AttributeValue
{
S = "PGA Pro II"
};
item["OrderStatus"] = new AttributeValue
{
S = "OUT FOR DELIVERY"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "383283"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
}
private static void WaitUntilTableReady(string tableName)
{
string status = null;
// Let us wait until table is created. Call DescribeTable.
do
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
status = res.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found. So we handle the potential exception.
}
} while (status != "ACTIVE");
}
private static void WaitForTableToBeDeleted(string tableName)
{
bool tablePresent = true;
while (tablePresent)
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
}
catch (ResourceNotFoundException)
{
tablePresent = false;
}
}
}
}
}
```
# Uso de índices secundarios locales en la AWS CLI de DynamoDB
Puede usar la AWS CLI para crear una tabla de Amazon DynamoDB con uno o más índices secundarios locales, describir los índices de la tabla y utilizarlos para realizar consultas.
**Topics**
+ [Creación de una tabla con un índice secundario local](#LCICli.CreateTableWithIndex)
+ [Descripción de una tabla con un índice secundario local](#LCICli.DescribeTableWithIndex)
+ [Consulta de un índice secundario local](#LCICli.QueryAnIndex)
## Creación de una tabla con un índice secundario local
Los índices secundarios locales se deben crear al mismo tiempo que la tabla. Para ello, use el parámetro `create-table` y proporcione las especificaciones para uno o más índices secundarios locales. En el ejemplo siguiente, se crea una tabla (`Music`) para contener información sobre las canciones de una colección de música. La clave de partición es `Artist` y la de ordenación, `SongTitle`. Un índice secundario `AlbumTitleIndex` en el atributo `AlbumTitle` facilita las consultas por título de álbum.
```
aws dynamodb create-table \
--table-name Music \
--attribute-definitions AttributeName=Artist,AttributeType=S AttributeName=SongTitle,AttributeType=S \
AttributeName=AlbumTitle,AttributeType=S \
--key-schema AttributeName=Artist,KeyType=HASH AttributeName=SongTitle,KeyType=RANGE \
--provisioned-throughput \
ReadCapacityUnits=10,WriteCapacityUnits=5 \
--local-secondary-indexes \
"[{\"IndexName\": \"AlbumTitleIndex\",
\"KeySchema\":[{\"AttributeName\":\"Artist\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"AlbumTitle\",\"KeyType\":\"RANGE\"}],
\"Projection\":{\"ProjectionType\":\"INCLUDE\", \"NonKeyAttributes\":[\"Genre\", \"Year\"]}}]"
```
Debe esperar hasta que DynamoDB cree la tabla y establezca el estado de esta última en `ACTIVE`. A partir de ese momento, puede comenzar a incluir elementos de datos en la tabla. Puede utilizar [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) Para determinar el estado de la creación de tablas.
## Descripción de una tabla con un índice secundario local
Para obtener información acerca de los índices secundarios locales en una tabla, utilice el parámetro `describe-table`. Para cada índice, puede obtener acceso a su nombre, esquema de claves y atributos proyectados.
```
aws dynamodb describe-table --table-name Music
```
## Consulta de un índice secundario local
Puede usar la operación `query` en un índice secundario local de un modo bastante parecido a como `query` se usa en una tabla. Debe especificar el nombre del índice, los criterios de consulta de la clave de ordenación del índice y los atributos que desea devolver. En este ejemplo, el índice es `AlbumTitleIndex` y la clave de ordenación del índice es `AlbumTitle`.
Los únicos atributos devueltos son aquellos que se han proyectado en el índice. Puede modificar esta consulta de modo que también seleccione atributos sin clave, pero esto requeriría realizar actividad de recuperación en la tabla, lo que resulta relativamente costoso. Para obtener más información sobre recuperaciones de tablas, consulte [Proyecciones de atributos](LSI.md#LSI.Projections).
```
aws dynamodb query \
--table-name Music \
--index-name AlbumTitleIndex \
--key-condition-expression "Artist = :v_artist and AlbumTitle = :v_title" \
--expression-attribute-values '{":v_artist":{"S":"Acme Band"},":v_title":{"S":"Songs About Life"} }'
```
# Administración de flujos de trabajo complejos con transacciones de DynamoDB
Amazon DynamoDB Transactions simplifica la experiencia de los desarrolladores que realizan cambios coordinados de "todo o nada" en varios elementos y distintas tablas. Las transacciones proporcionan atomicidad, consistencia, aislamiento y durabilidad (ACID, por sus siglas en inglés) en DynamoDB, lo que le ayuda a mantener la exactitud de los datos en sus aplicaciones.
Puede usar las API de lectura y escritura transaccional de DynamoDB para administrar flujos de trabajo empresarial complejos que requieren agregar, actualizar o eliminar varios elementos en una única operación de tipo "todo o nada". Por ejemplo, un desarrollador de videojuegos puede garantizar que los perfiles de los jugadores se actualicen correctamente cuando intercambien elementos en un juego o realicen compras dentro de este.
Con la API de escritura de transacciones, puede agrupar varias acciones `Put`, `Update`, `Delete` y `ConditionCheck`. A continuación, puede presentarlas como una sola operación `TransactWriteItems` que se realiza correctamente o da error como unidad. Lo mismo sucede con varias acciones `Get`, que se pueden agrupar y enviar como una sola operación `TransactGetItems`.
Habilitar las transacciones para las tablas de DynamoDB no conlleva ningún coste adicional. Usted paga sólo por las lecturas o escrituras que forman parte de su transacción. DynamoDB lleva a cabo dos lecturas o escrituras subyacentes de cada elemento de la transacción: una para preparar la transacción y otra para confirmarla. Estas dos operaciones de lectura/escritura subyacentes están visibles en las métricas de Amazon CloudWatch.
Para comenzar a trabajar con transacciones de DynamoDB, descargue el SDK de AWS o la AWS Command Line Interface (AWS CLI) más recientes. A continuación, siga el [Ejemplo de transacciones en DynamoDB](transaction-example.md).
En las secciones siguientes, se proporciona información general detallada sobre las API de transacciones y cómo usarlas en DynamoDB.
**Topics**
+ [Funcionamiento](transaction-apis.md)
+ [Uso de IAM con las transacciones](transaction-apis-iam.md)
+ [Código de ejemplo](transaction-example.md)
# Funcionamiento de las Transacciones de Amazon DynamoDB
Con Amazon DynamoDB Transactions, puede agrupar varias acciones y enviarlas como una sola operación `TransactWriteItems` o `TransactGetItems` de tipo "todo o nada". En las secciones siguientes, se describen las operaciones de la API, la administración de la capacidad, las prácticas recomendadas y otros detalles sobre el uso de operaciones transaccionales en DynamoDB.
**Topics**
+ [API TransactWriteItems](#transaction-apis-txwriteitems)
+ [API TransactGetItems](#transaction-apis-txgetitems)
+ [Niveles de aislamiento para las transacciones de DynamoDB](#transaction-isolation)
+ [Gestión de conflictos de transacciones en DynamoDB](#transaction-conflict-handling)
+ [Uso de las API transaccionales en DynamoDB Accelerator (DAX)](#transaction-apis-dax)
+ [Administración de la capacidad para las transacciones](#transaction-capacity-handling)
+ [Prácticas recomendadas para las transacciones](#transaction-best-practices)
+ [Uso de las API transaccionales con tablas globales](#transaction-integration)
+ [Transacciones de DynamoDB en comparación con la biblioteca de transacciones del cliente de AWSLabs](#transaction-vs-library)
## API TransactWriteItems
`TransactWriteItems` es una operación de escritura síncrona e idempotente que agrupa hasta 100 acciones de escritura en una única operación de tipo “todo o nada”. Estas acciones pueden estar dirigidas a un máximo de 100 elementos diferenciados en una o varias tablas de DynamoDB en la misma cuenta de AWS y en la misma región. El tamaño total de los elementos de la transacción no puede superar 4 MB. Las acciones se realizan atómicamente, de tal forma que se llevan a cabo correctamente todas o ninguna de ellas.
**nota**
Una operación `TransactWriteItems` se diferencia de una operación `BatchWriteItem` en que todas las acciones que contiene deben completarse correctamente o, de lo contrario, no se realiza ningún cambio. Con una operación `BatchWriteItem`, es posible que solo algunas de las acciones del lote se realicen correctamente y otras, no.
Las transacciones no se pueden realizar mediante índices.
No se pueden dirigir varias operaciones de la misma transacción al mismo elemento. Por ejemplo, no se puede realizar una acción `ConditionCheck` y también una acción `Update` en el mismo elemento de la misma transacción.
Puede agregar los tipos de acciones siguientes a una transacción:
+ `Put`: Inicia una operación `PutItem` para crear un nuevo elemento o sustituir uno antiguo por otro nuevo, ya sea de forma condicional o sin especificar ninguna condición.
+ `Update`: Inicia una operación `UpdateItem` para editar los atributos de un elemento existente o agregar un nuevo elemento a la tabla, si no existe ya. Esta acción se utiliza para agregar, eliminar o actualizar atributos a un elemento existente, de forma condicional o sin condiciones.
+ `Delete`: Inicia una operación `DeleteItem` para eliminar un solo elemento de una tabla identificado por su clave principal.
+ `ConditionCheck`: Comprueba la existencia de un elemento o la condición de atributos concretos del elemento.
Cuando se completa una transacción en DynamoDB, los cambios comienzan a propagarse a los índices secundarios globales (GSI), los flujos y las copias de seguridad. Esta propagación se produce gradualmente: los registros de flujo de la misma transacción pueden aparecer en momentos diferentes y pueden intercalarse con registros de otras transacciones. Los consumidores de flujos no deben asumir la atomicidad de la transacción ni las garantías de orden.
Para garantizar una instantánea atómica de los elementos modificados en una transacción, utilice la operación TransactGetItems para leer todos los elementos relevantes juntos. Esta operación proporciona una visión coherente de los datos, lo que garantiza que vea todos los cambios de una transacción completada o ninguno en absoluto.
Debido a que la propagación no es inmediata, si una tabla se restaura desde una copia de seguridad ([RestoreTableFromBackup](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_RestoreTableFromBackup.html)) o se exporta a un momento dado ([ExportTableToPointInTime](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_ExportTableToPointInTime.html)) a mitad de la propagación, puede contener solo algunos de los cambios realizados durante una transacción reciente.
### Idempotencia
Opcionalmente, puede incluir un token de cliente al realizar una llamada a `TransactWriteItems` para asegurarse de que la solicitud sea *idempotente*. Hacer que las transacciones sean idempotentes ayuda a evitar errores de aplicaciones si se envía la misma operación varias veces debido a una interrupción de la conexión u otro problema de conectividad.
Si la llamada a `TransactWriteItems` original se realizó correctamente, las llamadas siguientes a `TransactWriteItems` con el mismo token de cliente también se devolverán correctamente sin hacer ningún cambio. Si se ha establecido el parámetro `ReturnConsumedCapacity`, la llamada `TransactWriteItems` inicial devolverá el número de unidades de capacidad de escritura consumidas al realizar los cambios. Las llamadas siguientes a `TransactWriteItems` con el mismo token de cliente devolverán el número de unidades de capacidad de lectura consumidas al leer el elemento.
**Información importante sobre la idempotencia**
+ Un token de cliente es válido durante 10 minutos desde que finaliza la solicitud que lo utiliza. Transcurridos esos 10 minutos, cualquier solicitud que use el mismo token de cliente se tratará como si fuera nueva. No debe reutilizar el mismo token de cliente para la misma solicitud si han pasado 10 minutos.
+ Si repite una solicitud con el mismo token de cliente dentro del periodo de idempotencia de 10 minutos, pero cambia algún otro parámetro de la solicitud, DynamoDB devolverá una excepción `IdempotentParameterMismatch`.
### Control de errores de escritura
Las transacciones de escritura no se realizarán correctamente en las siguientes circunstancias:
+ Cuando no se cumple alguna de las condiciones de las expresiones de condición.
+ Cuando se produce un error de validación de transacción porque hay más de una acción dirigida al mismo elemento en una sola operación `TransactWriteItems`.
+ Cuando una solicitud `TransactWriteItems` está en conflicto con una operación `TransactWriteItems` en curso para uno o varios elementos de la solicitud `TransactWriteItems`. En este caso, la solicitud genera un error `TransactionCanceledException`.
+ Cuando no hay suficiente capacidad aprovisionada para completar la transacción.
+ Cuando el tamaño de un elemento es excesivo (más de 400 KB), un índice secundario local (LSI) se vuelve demasiado grande o se produce algún error de validación semejante a causa de los cambios realizados por la transacción.
+ Cuando hay algún error de usuario, como un formato de datos no válido.
Para obtener más información acerca de cómo se manejan los conflictos con operaciones `TransactWriteItems`, consulte [Gestión de conflictos de transacciones en DynamoDB](#transaction-conflict-handling).
## API TransactGetItems
`TransactGetItems` es una operación de lectura síncrona que agrupa hasta 100 acciones `Get`. Estas acciones pueden estar dirigidas a un máximo de 100 elementos diferenciados en una o varias tablas de DynamoDB en la misma cuenta y región de AWS. El tamaño total de los elementos de la transacción no puede superar 4 MB.
Las acciones `Get` se realizan atómicamente, de tal forma que se llevan a cabo correctamente todas o ninguna de ellas:
+ `Get`: Inicia una operación `GetItem` para recuperar un conjunto de atributos para el elemento que tiene la clave principal especificada. Si no se encuentra ningún elemento que coincida, `Get` no devuelve ningún dato.
### Control de errores de lectura
Las transacciones de lectura no se realizarán correctamente en las siguientes circunstancias:
+ Cuando una solicitud `TransactGetItems` está en conflicto con una operación `TransactWriteItems` en curso para uno o varios elementos de la solicitud `TransactGetItems`. En este caso, la solicitud genera un error `TransactionCanceledException`.
+ Cuando no hay suficiente capacidad aprovisionada para completar la transacción.
+ Cuando hay algún error de usuario, como un formato de datos no válido.
Para obtener más información acerca de cómo se manejan los conflictos con operaciones `TransactGetItems`, consulte [Gestión de conflictos de transacciones en DynamoDB](#transaction-conflict-handling).
## Niveles de aislamiento para las transacciones de DynamoDB
Los niveles de aislamiento de las operaciones transaccionales (`TransactWriteItems` o `TransactGetItems`) y otras operaciones son los siguientes.
### SERIALIZABLE
El aislamiento *serializable* garantiza que los resultados de varias operaciones concurrentes sean iguales que si ninguna operación se hubiera iniciado antes de finalizar la anterior.
Existe aislamiento serializable entre los siguientes tipos de operaciones:
+ Entre cualquier operación transaccional y cualquier operación de escritura estándar (`PutItem`, `UpdateItem` o `DeleteItem`).
+ Entre cualquier operación transaccional y cualquier operación de lectura estándar (`GetItem`).
+ Entre una operación `TransactWriteItems` y una operación `TransactGetItems`.
Aunque existe aislamiento serializable entre las operaciones transaccionales y cada escritura estándar individual escribe en una operación `BatchWriteItem`, no se produce aislamiento serializable entre la transacción y la operación `BatchWriteItem` como una unidad.
Del mismo modo, el nivel de aislamiento entre una operación transaccional y una operación `GetItems` individual de una operación `BatchGetItem` es serializable. Pero el nivel de aislamiento entre la transacción y la operación `BatchGetItem` como unidad es de *lectura confirmada*.
Una sola solicitud `GetItem` es serializable con respecto a una solicitud `TransactWriteItems` de una de las dos formas siguientes: antes o después de la solicitud `TransactWriteItems`. Multiple solicitudes `GetItem`, de las claves en solicitudes `TransactWriteItems` se pueden ejecutar en cualquier orden, y por lo tanto los resultados son *lectura confirmada*.
Por ejemplo, si las solicitudes `GetItem` para el elemento A y el elemento B se ejecutan simultáneamente con una solicitud `TransactWriteItems` que modifica tanto el punto A como el punto B, hay cuatro posibilidades:
+ Ambos `GetItem` se ejecutan antes de que la solicitud `TransactWriteItems`.
+ Ambos `GetItem` se ejecutan después de la solicitud `TransactWriteItems`.
+ Solicitud `GetItem` para el elemento A se ejecuta antes de la solicitud `TransactWriteItems`. Para el elemento B, `GetItem` se ejecuta después de `TransactWriteItems`.
+ Solicitud `GetItem` para el elemento B se ejecuta antes de la solicitud `TransactWriteItems`. Para el elemento A, `GetItem` se ejecuta después de `TransactWriteItems`.
Utilice `TransactGetItems`, si prefiere el nivel de aislamiento serializable para múltiples solicitudes `GetItem`.
Si se realiza una lectura no transaccional de varios elementos que formaban parte de la misma solicitud de escritura de transacción durante el vuelo, es posible que pueda leer el nuevo estado de algunos de los elementos y el estado anterior de los demás. Solo podrá leer el nuevo estado de todos los elementos que formaban parte de la solicitud de escritura de transacción cuando reciba una respuesta correcta a la escritura de la transacción, lo que indica que la transacción se ha completado.
Una vez que la transacción se completa correctamente y se recibe una respuesta, las operaciones de lectura *coherente posterior* pueden seguir devolviendo el estado anterior durante un breve periodo debido al modelo de consistencia posterior de DynamoDB. Para garantizar la lectura de los datos más actualizados inmediatamente después de una transacción, debe utilizar lecturas [*altamente coherentes*](HowItWorks.ReadConsistency.md#HowItWorks.ReadConsistency.Strongly) mediante el establecimiento de `ConsistentRead` a true.
### LECTURA CONFIRMADA
El aislamiento de *lectura confirmada* garantiza que las operaciones de lectura siempre devuelven valores confirmados para un elemento: la lectura nunca presentará una vista al elemento que represente un estado de una escritura transaccional que no haya tenido éxito finalmente. El aislamiento de lectura confirmada no impide las modificaciones del elemento inmediatamente después de la operación de lectura.
El nivel de aislamiento es de lectura confirmada entre cualquier operación transaccional y cualquier operación de lectura que conlleve varias lecturas estándar (`BatchGetItem`, `Query` o `Scan`). Si una escritura transaccional actualiza un elemento en medio de una operación de `BatchGetItem`, `Query` o `Scan`, la parte posterior de la operación de lectura devuelve el nuevo valor confirmado (con `ConsistentRead)` o posiblemente un valor confirmado anterior [lecturas coherentes posteriores]).
### Resumen de la operación
A modo de resumen, en la siguiente tabla se indican los niveles de aislamiento entre una operación transaccional (`TransactWriteItems` o `TransactGetItems`) y otras operaciones.
| Operación | Nivel de aislamiento |
| --- | --- |
| `DeleteItem` | *Serializable* |
| `PutItem` | *Serializable* |
| `UpdateItem` | *Serializable* |
| `GetItem` | *Serializable* |
| `BatchGetItem` | *Lectura confirmada*\$1 |
| `BatchWriteItem` | *NO serializable*\$1 |
| `Query` | *Lectura confirmada* |
| `Scan` | *Lectura confirmada* |
| Otra operación transaccional | *Serializable* |
Los niveles marcados con un asterisco (\$1) se aplican a la operación como una unidad. Sin embargo, las acciones individuales contenidas en esas operaciones tienen el nivel de aislamiento *serializable*.
## Gestión de conflictos de transacciones en DynamoDB
Un conflicto de transacciones puede producirse durante solicitudes concurrentes de nivel de elemento en un elemento dentro de una transacción. Los conflictos de transacciones pueden producirse en los siguientes escenarios:
+ Una solicitud `PutItem`, `UpdateItem` o `DeleteItem` de un elemento entra en conflicto con una solicitud `TransactWriteItems` en curso que incluye el mismo elemento.
+ Un elemento incluido en una solicitud `TransactWriteItems` forma parte de otra solicitud `TransactWriteItems` en curso.
+ Un elemento incluido en una solicitud `TransactGetItems` forma parte de otra solicitud `TransactWriteItems`, `BatchWriteItem`, `PutItem`, `UpdateItem` o `DeleteItem` en curso.
**nota**
Cuando se rechaza una solicitud `PutItem`, `UpdateItem` o `DeleteItem`, la solicitud no se realiza correctamente y genera una excepción `TransactionConflictException`.
Si se rechaza cualquier solicitud de nivel de elemento dentro de una operación `TransactWriteItems` o `TransactGetItems`, la solicitud no se realiza correctamente y genera una excepción `TransactionCanceledException`. Si esa solicitud falla, los SDK de AWS no vuelven a intentar la solicitud.
Si se está utilizando el AWS SDK para Java, la excepción contiene la lista de [CancellationReasons](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CancellationReason.html), ordenada según la lista de elementos del parámetro `TransactItems` de la solicitud. Para los demás lenguajes, se incluye una representación de cadena de la lista en el mensaje de error de la excepción.
Si una operación `TransactWriteItems` o `TransactGetItems` está en conflicto con una solicitud `GetItem` concurrente, las dos operaciones podrían realizarse correctamente.
La [métrica TransactionConflict de CloudWatch](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/metrics-dimensions.html) se incrementa para cada solicitud de nivel de elemento que no se realiza correctamente.
## Uso de las API transaccionales en DynamoDB Accelerator (DAX)
Tanto `TransactWriteItems` como `TransactGetItems` se admiten en DynamoDB Accelerator (DAX) con los mismos niveles de aislamiento que en DynamoDB.
`TransactWriteItems` escribe a través de DAX. DAX pasa una llamada `TransactWriteItems` a DynamoDB y devuelve la respuesta. Para rellenar la caché después de la escritura, DAX llama a `TransactGetItems` en segundo plano para cada elemento en la operación `TransactWriteItems`, que consume unidades de capacidad de lectura adicionales. (Para obtener más información, consulte ). [Administración de la capacidad para las transacciones](#transaction-capacity-handling).) Esta funcionalidad le permite no complicar la lógica de la aplicación y utilizar DAX para operaciones transaccionales así como para operaciones no transaccionales.
`TransactGetItems`Las llamadas se pasan por DAX sin que los elementos se almacenen en caché localmente. Es el mismo comportamiento que tienen las API de lectura de consistencia alta en DAX.
## Administración de la capacidad para las transacciones
Habilitar las transacciones para las tablas de DynamoDB no conlleva ningún coste adicional. Usted paga sólo por las lecturas o escrituras que forman parte de su transacción. DynamoDB lleva a cabo dos lecturas o escrituras subyacentes de cada elemento de la transacción: una para preparar la transacción y otra para confirmarla. Las dos operaciones de lectura/escritura subyacentes están visibles en las métricas de Amazon CloudWatch.
Planee las lecturas y escrituras adicionales que requieren las API transaccionales al aprovisionar la capacidad para las tablas. Por ejemplo, supongamos que su aplicación ejecuta una transacción por segundo y que cada transacción escribe tres elementos de 500 bites en la tabla. Cada elemento requiere dos unidades de capacidad de escritura (WCU): una para preparar la transacción y otra para confirmarla. Por consiguiente, tendría que aprovisionar seis WCU para la tabla.
Si utilizó DynamoDB Accelerator (DAX) en el ejemplo anterior, también debió utilizar dos unidades de capacidad de lectura (RCU) para cada elemento de la llamada `TransactWriteItems`. Por tanto, tendría que aprovisionar seis RCU adicionales para la tabla.
Del mismo modo, si la aplicación ejecuta una transacción de lectura por segundo y cada transacción lee tres elementos de 500 bytes de la tabla, debería aprovisionar seis unidades de capacidad de lectura (RCU) para la tabla. La lectura de cada elemento requiere dos RCU: una para preparar la transacción y otra para confirmarla.
Además, el comportamiento predeterminado del SDK consiste en reintentar las transacciones si se produce alguna excepción `TransactionInProgressException`. Planee las unidades de capacidad de lectura (RCU) adicionales que consumen estos reintentos. Lo mismo sucede si reintenta transacciones de su propio código mediante un `ClientRequestToken`.
## Prácticas recomendadas para las transacciones
Es importante tener en cuenta las prácticas recomendadas siguientes al utilizar transacciones de DynamoDB.
+ Habilite el escalado automático en las tablas o asegúrese de haber aprovisionado suficiente capacidad de rendimiento para llevar a cabo las dos operaciones de lectura o escritura para cada elemento de la transacción.
+ Si no utiliza un SDK proporcionado por AWS, incluya un atributo `ClientRequestToken` al realizar una llamada a `TransactWriteItems` para asegurarse de que la solicitud sea idempotente.
+ No agrupe las operaciones en una transacción si no es necesario. Por ejemplo, si una misma transacción compuesta de 10 operaciones se puede desglosar en varias transacciones de modo que la aplicación continúe siendo correcta, recomendamos dividir la transacción. Usar transacciones más sencillas mejora el rendimiento y aumenta la probabilidad de que se ejecuten correctamente.
+ Si varias transacciones actualizan los mismos elementos de forma simultánea, pueden provocar conflictos que cancelen las transacciones. Recomendamos las siguientes prácticas recomendadas de DynamoDB para modelar los datos de tal forma que se reduzcan al mínimo esos conflictos.
+ Si un conjunto de atributos se actualiza a menudo para varios elementos durante una misma transacción, puede ser conveniente agrupar los atributos en un solo elemento para reducir el ámbito de la transacción.
+ Evite utilizar transacciones para la ingesta masiva de datos. Para las escrituras masivas, es preferible usar `BatchWriteItem`.
## Uso de las API transaccionales con tablas globales
Las operaciones transaccionales proporcionan garantías de atomicidad, uniformidad, aislamiento y durabilidad (ACID) solo en la región de AWS en la que se invocó la API de escritura. No se admiten las transacciones entre regiones en las tablas globales. Por ejemplo, supongamos que tiene una tabla global con réplicas en las regiones EE. UU. Este (Ohio) y EE. UU. Oeste (Oregón) y realiza una operación `TransactWriteItems` en la región EE. UU. Este (Norte de Virginia). Puede observar transacciones parcialmente completadas en la región Oeste de EE. UU. (Oregón) a medida que se replican los cambios. Los cambios se replican en otras regiones solo cuando se han confirmado en la región de origen.
## Transacciones de DynamoDB en comparación con la biblioteca de transacciones del cliente de AWSLabs
Las transacciones de DynamoDB proporcionan una forma más rentable, robusta y eficiente de sustituir la biblioteca de cliente de transacciones de [AWSLabs](https://github.com/awslabs). Sugerimos actualizar las aplicaciones de modo que utilicen las API de transacciones nativas del lado del servidor.
# Uso de IAM con las transacciones de DynamoDB
Puede usar AWS Identity and Access Management (IAM) para restringir las acciones que las operaciones transaccionales pueden ejecutar en Amazon DynamoDB. Para obtener más información sobre el uso de políticas de IAM en DynamoDB, consulte [Políticas basadas en identidad de DynamoDB](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies).
Los permisos para las acciones `Put`, `Update`, `Delete` y `Get` se rigen por los permisos usados para las operaciones `PutItem`, `UpdateItem`, `DeleteItem` y `GetItem` subyacentes. Para la acción `ConditionCheck`, puede usar el permiso `dynamodb:ConditionCheckItem` en las políticas de IAM.
A continuación, se proporcionan ejemplos de políticas de IAM que puede utilizar para configurar las transacciones de DynamoDB.
## Ejemplo 1: permitir las operaciones transaccionales
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
]
}
]
}
```
------
## Ejemplo 2: permitir solo las operaciones transaccionales
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
],
"Condition": {
"ForAnyValue:StringEquals": {
"dynamodb:EnclosingOperation": [
"TransactWriteItems",
"TransactGetItems"
]
}
}
}
]
}
```
------
## Ejemplo 3: permitir las lecturas y escrituras no transaccionales y bloquear las lecturas y escrituras transaccionales
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
],
"Condition": {
"ForAnyValue:StringEquals": {
"dynamodb:EnclosingOperation": [
"TransactWriteItems",
"TransactGetItems"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:PutItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:UpdateItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
]
}
]
}
```
------
## Ejemplo 4: evitar que se devuelva información en caso de error de comprobación de condición
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": "arn:aws:dynamodb:*:*:table/table01",
"Condition": {
"StringEqualsIfExists": {
"dynamodb:ReturnValues": "NONE"
}
}
}
]
}
```
------
# Ejemplo de transacciones en DynamoDB
Como ejemplo de una situación en la que Amazon DynamoDB Transactions pueden ser útiles, considere esta aplicación Java de ejemplo para un mercado en línea.
La aplicación tiene tres tablas de DynamoDB en el backend:
+ `Customers`: en esta tabla se almacenan detalles sobre los clientes del mercado. Su clave principal es un identificador único `CustomerId`.
+ `ProductCatalog`: en esta tabla se almacenan detalles tales como el precio y la disponibilidad de los productos que se venden en el mercado. Su clave principal es un identificador único `ProductId`.
+ `Orders`: en esta tabla se almacenan detalles sobre los pedidos del mercado. Su clave principal es un identificador único `OrderId`.
## Hacer un pedido
Los siguientes fragmentos de código ilustran cómo utilizar las transacciones de DynamoDB para coordinar los múltiples pasos necesarios para crear y procesar un pedido. El uso de una única operación todo o nada garantiza que si falla alguna parte de la transacción, no se ejecuten acciones en la transacción y no se realicen cambios.
En este ejemplo, configura un pedido de un cliente cuyo `customerId` es `09e8e9c8-ec48`. A continuación, se ejecuta como una única transacción mediante el siguiente flujo de trabajo de procesamiento de pedidos:
1. Determine que el ID del cliente sea válido.
1. Asegúrese de que el producto sea `IN_STOCK` y actualice el estado del producto a `SOLD`.
1. Asegúrese de que el pedido aún no existe y cree el pedido.
### Validar al cliente
Primero, defina una acción para verificar que un cliente con `customerId` igual a `09e8e9c8-ec48` existe en la tabla de clientes.
```
final String CUSTOMER_TABLE_NAME = "Customers";
final String CUSTOMER_PARTITION_KEY = "CustomerId";
final String customerId = "09e8e9c8-ec48";
final HashMap customerItemKey = new HashMap<>();
customerItemKey.put(CUSTOMER_PARTITION_KEY, new AttributeValue(customerId));
ConditionCheck checkCustomerValid = new ConditionCheck()
.withTableName(CUSTOMER_TABLE_NAME)
.withKey(customerItemKey)
.withConditionExpression("attribute_exists(" + CUSTOMER_PARTITION_KEY + ")");
```
### Actualizar el estado del producto
A continuación, defina una acción para actualizar el estado del producto a `SOLD` si la condición en la que el estado del producto está establecido actualmente en `IN_STOCK` es `true`. Configuración del parámetro `ReturnValuesOnConditionCheckFailure` devuelve el elemento si el atributo de estado del producto del artículo no era igual a `IN_STOCK`.
```
final String PRODUCT_TABLE_NAME = "ProductCatalog";
final String PRODUCT_PARTITION_KEY = "ProductId";
HashMap productItemKey = new HashMap<>();
productItemKey.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
Map expressionAttributeValues = new HashMap<>();
expressionAttributeValues.put(":new_status", new AttributeValue("SOLD"));
expressionAttributeValues.put(":expected_status", new AttributeValue("IN_STOCK"));
Update markItemSold = new Update()
.withTableName(PRODUCT_TABLE_NAME)
.withKey(productItemKey)
.withUpdateExpression("SET ProductStatus = :new_status")
.withExpressionAttributeValues(expressionAttributeValues)
.withConditionExpression("ProductStatus = :expected_status")
.withReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD);
```
### Crear el pedido
Por último, cree el pedido siempre y cuando un pedido con ese `OrderId` no existe.
```
final String ORDER_PARTITION_KEY = "OrderId";
final String ORDER_TABLE_NAME = "Orders";
HashMap orderItem = new HashMap<>();
orderItem.put(ORDER_PARTITION_KEY, new AttributeValue(orderId));
orderItem.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
orderItem.put(CUSTOMER_PARTITION_KEY, new AttributeValue(customerId));
orderItem.put("OrderStatus", new AttributeValue("CONFIRMED"));
orderItem.put("OrderTotal", new AttributeValue("100"));
Put createOrder = new Put()
.withTableName(ORDER_TABLE_NAME)
.withItem(orderItem)
.withReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD)
.withConditionExpression("attribute_not_exists(" + ORDER_PARTITION_KEY + ")");
```
### Ejecutar la transacción
En el siguiente ejemplo de la se muestra cómo ejecutar las acciones definidas anteriormente como una única operación de tipo “todo o nada”.
```
Collection actions = Arrays.asList(
new TransactWriteItem().withConditionCheck(checkCustomerValid),
new TransactWriteItem().withUpdate(markItemSold),
new TransactWriteItem().withPut(createOrder));
TransactWriteItemsRequest placeOrderTransaction = new TransactWriteItemsRequest()
.withTransactItems(actions)
.withReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL);
// Run the transaction and process the result.
try {
client.transactWriteItems(placeOrderTransaction);
System.out.println("Transaction Successful");
} catch (ResourceNotFoundException rnf) {
System.err.println("One of the table involved in the transaction is not found" + rnf.getMessage());
} catch (InternalServerErrorException ise) {
System.err.println("Internal Server Error" + ise.getMessage());
} catch (TransactionCanceledException tce) {
System.out.println("Transaction Canceled " + tce.getMessage());
}
```
## Leer los detalles del pedido
En el siguiente ejemplo se muestra cómo leer el pedido completado transaccionalmente a través de las tablas `Orders` y `ProductCatalog`.
```
HashMap productItemKey = new HashMap<>();
productItemKey.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
HashMap orderKey = new HashMap<>();
orderKey.put(ORDER_PARTITION_KEY, new AttributeValue(orderId));
Get readProductSold = new Get()
.withTableName(PRODUCT_TABLE_NAME)
.withKey(productItemKey);
Get readCreatedOrder = new Get()
.withTableName(ORDER_TABLE_NAME)
.withKey(orderKey);
Collection getActions = Arrays.asList(
new TransactGetItem().withGet(readProductSold),
new TransactGetItem().withGet(readCreatedOrder));
TransactGetItemsRequest readCompletedOrder = new TransactGetItemsRequest()
.withTransactItems(getActions)
.withReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL);
// Run the transaction and process the result.
try {
TransactGetItemsResult result = client.transactGetItems(readCompletedOrder);
System.out.println(result.getResponses());
} catch (ResourceNotFoundException rnf) {
System.err.println("One of the table involved in the transaction is not found" + rnf.getMessage());
} catch (InternalServerErrorException ise) {
System.err.println("Internal Server Error" + ise.getMessage());
} catch (TransactionCanceledException tce) {
System.err.println("Transaction Canceled" + tce.getMessage());
}
```
# Captura de datos de cambio con Amazon DynamoDB
Muchas aplicaciones se benefician capturando los cambios en los elementos almacenados en una tabla de DynamoDB en el momento en que se producen. A continuación se muestran algunos ejemplos de casos de uso:
+ Una aplicación móvil popular modifica los datos de una tabla de DynamoDB a razón de miles de actualizaciones por segundo. Otra aplicación captura y almacena los datos sobre estas actualizaciones y ofrece métricas de uso de la aplicación para móviles prácticamente en tiempo real.
+ Una aplicación financiera modifica los datos del mercado de valores en una tabla de DynamoDB. Diferentes aplicaciones que se ejecutan en paralelo rastrean estos cambios en tiempo real, calculan el valor en riesgo y reequilibran automáticamente las carteras en función de los movimientos del precio de las acciones.
+ Los sensores en vehículos de transporte y equipos industriales envían datos a una tabla de DynamoDB. Diferentes aplicaciones monitorean el rendimiento y envían alertas de mensajería cuando se detecta un problema, predicen posibles defectos aplicando algoritmos de aprendizaje automático y comprimen y archivan datos en Amazon Simple Storage Service (Amazon S3).
+ Una aplicación envía automáticamente notificaciones a los dispositivos móviles de todos los amigos de un grupo tan pronto como uno de ellos carga una nueva imagen.
+ Un nuevo cliente agrega datos a una tabla de DynamoDB. Este evento invoca otra aplicación que envía un mensaje de correo electrónico de bienvenida al nuevo cliente.
DynamoDB admite el streaming de registros de captura de datos de cambio a nivel de elemento en tiempo casi real. Puede crear aplicaciones que consuman estas transmisiones y adopten medidas en función de su contenido.
**nota**
No se admite agregar etiquetas a DynamoDB Streams ni utilizar el [control de acceso basado en atributos (ABAC)](access-control-resource-based.md) con DynamoDB Streams.
El siguiente vídeo le ofrece una introducción al concepto de captación de datos de cambios.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/VVv_-mZ5Ge8)
**Topics**
+ [Opciones de streaming para la captura de datos de cambio](#streamsmain.choose)
+ [Uso de Kinesis Data Streams para capturar cambios en DynamoDB](kds.md)
+ [Captura de datos de cambios para DynamoDB Streams](Streams.md)
## Opciones de streaming para la captura de datos de cambio
DynamoDB ofrece dos modelos de streaming para la captura de datos de cambios: Kinesis Data Streams para DynamoDB y DynamoDB Streams.
Para ayudarle a elegir la solución adecuada para su aplicación, la siguiente tabla resume las características de cada modelo de streaming.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/streamsmain.html)
Puede habilitar ambos modelos de streaming en la misma tabla de DynamoDB.
En las siguientes charlas de vídeo, se comparan las diferencias entre las dos opciones.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/UgG17Wh2y0g)
# Uso de Kinesis Data Streams para capturar cambios en DynamoDB
Puede utilizar Amazon Kinesis Data Streams para capturar cambios en Amazon DynamoDB.
Kinesis Data Streams captura modificaciones a nivel de elemento en cualquier tabla de DynamoDB y las replica en una [secuencia de datos de Kinesis](https://docs.aws.amazon.com/streams/latest/dev/introduction.html). Sus aplicaciones pueden acceder a este flujo de datos y ver los cambios a nivel de elemento casi en tiempo real. Puede capturar y almacenar continuamente terabytes de datos por hora. Puede aprovechar el tiempo de retención de datos más prolongado y, con la capacidad de distribución ramificada mejorada, puede llegar simultáneamente a dos o más aplicaciones descendentes. Otros beneficios incluyen una mayor transparencia de auditoría y seguridad.
Kinesis Data Streams también le da acceso a [Amazon Data Firehose](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) y [Amazon Managed Service para Apache Flink](https://docs.aws.amazon.com/kinesisanalytics/latest/dev/what-is.html). Estos servicios pueden ayudarle a crear aplicaciones que alimenten paneles en tiempo real, generen alertas, apliquen precios y publicidad dinámicos y apliquen análisis de datos sofisticados y algoritmos de machine learning.
**nota**
El uso de Kinesis Data Streams para DynamoDB está sujeto a los [Precios de Kinesis Data Streams](https://aws.amazon.com/kinesis/data-streams/pricing/) para el flujo de datos y a los [Precios de DynamoDB](https://aws.amazon.com/dynamodb/pricing/) para la tabla de origen.
Para habilitar la transmisión de Kinesis en una tabla de DynamoDB mediante la consola, la AWS CLI o el SDK de Java, consulte [Introducción a Kinesis Data Streams para Amazon DynamoDB](kds_gettingstarted.md).
**Topics**
+ [Cómo funciona Kinesis Data Streams con DynamoDB](#kds_howitworks)
+ [Introducción a Kinesis Data Streams para Amazon DynamoDB](kds_gettingstarted.md)
+ [Uso de particiones y métricas con DynamoDB Streams y Kinesis Data Streams](kds_using-shards-and-metrics.md)
+ [Uso de políticas de IAM para Amazon Kinesis Data Streams y Amazon DynamoDB](kds_iam.md)
## Cómo funciona Kinesis Data Streams con DynamoDB
Cuando un flujo de datos de Kinesis está habilitado para una tabla de DynamoDB, la tabla envía un registro de datos que captura cualquier cambio en los datos de esa tabla. Este registro de datos incluye:
+ La hora específica en la que se creó, se actualizó o se eliminó recientemente un elemento
+ Clave principal de ese elemento
+ Una instantánea del registro antes de la modificación
+ Una instantánea del registro después de la modificación
Estos registros de datos se capturan y publican casi en tiempo real. Después de escribirlos en el flujo de datos de Kinesis, se pueden leer igual que cualquier otro registro. Puede utilizar la biblioteca de clientes de Kinesis, utilizar AWS Lambda, llamar a la API de Kinesis Data Streams y utilizar otros servicios conectados. Para obtener más información, consulte [Lectura de datos desde Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html) en la Guía para desarrolladores de Amazon Kinesis Data Streams.
Estos cambios en los datos también se capturan de forma asíncrona. Kinesis no tiene ningún impacto en el rendimiento de una tabla desde la que se transmite. Los registros de transmisión almacenados en la secuencia de datos de Kinesis se cifran en reposo. Para obtener más información, consulte [Protección de datos en Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/server-side-encryption.html).
Los registros del flujo de datos de Kinesis podrían aparecer en un orden distinto al de cuando se produjeron los cambios en los elementos. Las mismas notificaciones de elementos también podrían aparecer más de una vez en el flujo. Puede verificar el atributo `ApproximateCreationDateTime` para identificar el orden en el que se produjeron las modificaciones de los elementos e identificar los registros duplicados.
Al activar un flujo de datos de Kinesis como destino de transmisión de una tabla de DynamoDB, puede configurar la precisión de los valores `ApproximateCreationDateTime` en milisegundos o microsegundos. De forma predeterminada, `ApproximateCreationDateTime` indica la hora del cambio en milisegundos. Además, puede cambiar este valor en un destino de transmisión activo. Tras dicha actualización, los registros de flujo escritos en Kinesis tendrán valores `ApproximateCreationDateTime` con la precisión deseada.
Los valores binarios escritos en DynamoDB deben estar codificados en [formato base64](HowItWorks.NamingRulesDataTypes.md). No obstante, cuando los registros de datos se escriben en un flujo de datos Kinesis, estos valores binarios codificados se codifican en base64 por segunda vez. Al leer estos registros de un flujo de datos Kinesis, para recuperar los valores binarios en bruto, las aplicaciones deben descodificar estos valores dos veces.
DynamoDB cobra por el uso de Kinesis Data Streams en unidades de captura de datos de cambio. 1 KB de cambio por elemento único cuenta como una unidad de captura de datos de cambio. El KB de cambio de cada elemento se calcula por la mayor de las imágenes “antes” y “después” del elemento escrito en el flujo, y se utiliza la misma lógica que el [consumo de unidades de capacidad para operaciones de escritura](read-write-operations.md#write-operation-consumption). De manera similar a la que funciona el modo [bajo demanda](capacity-mode.md#capacity-mode-on-demand) de DynamoDB, no es necesario aprovisionar el rendimiento de capacidad para las unidades de captura de datos de cambio.
### Activación de una instancia de flujo de datos de Kinesis para la tabla de DynamoDB
Puede habilitar o desactivar el streaming a Kinesis en su tabla de DynamoDB existente mediante la Consola de administración de AWS, el SDK de AWS o AWS Command Line Interface (AWS CLI).
+ Solo puede transmitir datos de DynamoDB a Kinesis Data Streams en la misma cuenta AWS y región AWS que su tabla.
+ Solo puede transmitir datos desde una tabla de DynamoDB a un flujo de datos de Kinesis.
### Aplicación de cambios en un destino de Kinesis Data Streams de la tabla de DynamoDB
De forma predeterminada, todos los registros de flujos de datos de Kinesis incluyen un atributo `ApproximateCreationDateTime`. Este atributo representa una marca de tiempo en milisegundos del momento aproximado en que se creó cada registro. Puede cambiar la precisión de estos valores en [https://console.aws.amazon.com/kinesis](https://console.aws.amazon.com/kinesis), el SDK o la AWS CLI.
# Introducción a Kinesis Data Streams para Amazon DynamoDB
En esta sección se describe cómo usar las tablas de Kinesis Data Streams para Amazon DynamoDB con la consola de Amazon DynamoDB, la AWS Command Line Interface (AWS CLI) y la API.
## Creación de un flujo de datos de Amazon Kinesis activo
Todos estos ejemplos utilizan la tabla `Music` de DynamoDB que se creó como parte del tutorial [Introducción a DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html).
Para obtener más información sobre cómo crear consumidores y conectar el flujo de datos de Kinesis a otros servicios de AWS, consulte [Lectura de datos de Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html) en la *Guía para desarrolladores de Amazon Kinesis Data Streams*.
**nota**
Cuando utilice particiones de KDS por primera vez, le recomendamos configurar los fragmentos para escalar verticalmente y reducir verticalmente según los patrones de uso. Cuando haya acumulado más datos sobre los patrones de uso, podrá ajustar las particiones de la transmisión para que coincidan.
------
#### [ Console ]
1. Inicie sesión en la Consola de administración de AWS y abra la consola de Kinesis en [https://console.aws.amazon.com/kinesis/](https://console.aws.amazon.com/kinesis/).
1. Seleccionar **Creación de flujos de datos** y siga las instrucciones para crear una transmisión llamada `samplestream`.
1. Abra la consola de DynamoDB en [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/).
1. En el panel de navegación del lado izquierdo de la consola, elija **Tablas**.
1. Elija la tabla **Music**.
1. Elija la pestaña **Exports and streams** (Exportaciones y flujos).
1. (Opcional) En **Detalles de Amazon Kinesis Data Streams**, puede cambiar la precisión de la marca de tiempo del registro de microsegundos (predeterminado) a milisegundos.
1. Elija **samplestream** de la lista desplegable.
1. Seleccione el botón **Activar**.
------
#### [ AWS CLI ]
1. Cree un flujo de datos de Kinesis llamado `samplestream` mediante el uso del [comando create-stream](https://docs.aws.amazon.com/cli/latest/reference/kinesis/create-stream.html).
```
aws kinesis create-stream --stream-name samplestream --shard-count 3
```
Consulte [Consideraciones sobre la administración de particiones para Kinesis Data Streams](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment) antes de configurar el número de fragmentos para el flujo de datos de Kinesis.
1. Verifique que la transmisión de Kinesis esté activa y lista para su uso mediante el [comando describe-stream](https://docs.aws.amazon.com/cli/latest/reference/kinesis/describe-stream.html).
```
aws kinesis describe-stream --stream-name samplestream
```
1. Habilite el streaming de Kinesis en la tabla de DynamoDB mediante el `enable-kinesis-streaming-destination` comando. Reemplace el valor de `stream-arn` por el que `describe-stream` devolvió en el paso anterior. Si lo desea, active la transmisión con una precisión más detallada (microsegundos) de los valores de marca de tiempo devueltos en cada registro.
Active la transmisión con una precisión de marca de tiempo de microsegundos:
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
--enable-kinesis-streaming-configuration ApproximateCreationDateTimePrecision=MICROSECOND
```
O active la transmisión con la precisión de marca de tiempo predeterminada (milisegundos):
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
```
1. Verifique si el streaming de Kinesis está activa en la tabla mediante el comando `describe-kinesis-streaming-destination` de DynamoDB.
```
aws dynamodb describe-kinesis-streaming-destination --table-name Music
```
1. Escribir datos en la tabla de DynamoDB utilizando el comando `put-item`, tal y como se describe en la [Guía para desarrolladores de DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-2.html).
```
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "No One You Know"}, "SongTitle": {"S": "Call Me Today"}, "AlbumTitle": {"S": "Somewhat Famous"}, "Awards": {"N": "1"}}'
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "Acme Band"}, "SongTitle": {"S": "Happy Day"}, "AlbumTitle": {"S": "Songs About Life"}, "Awards": {"N": "10"} }'
```
1. Uso del comando de la CLI [get-records](https://docs.aws.amazon.com/cli/latest/reference/kinesis/get-records.html) para Kinesis para recuperar el contenido del flujo de Kinesis. A continuación, utilice el siguiente fragmento de código para deserializar el contenido de la transmisión.
```
/**
* Takes as input a Record fetched from Kinesis and does arbitrary processing as an example.
*/
public void processRecord(Record kinesisRecord) throws IOException {
ByteBuffer kdsRecordByteBuffer = kinesisRecord.getData();
JsonNode rootNode = OBJECT_MAPPER.readTree(kdsRecordByteBuffer.array());
JsonNode dynamoDBRecord = rootNode.get("dynamodb");
JsonNode oldItemImage = dynamoDBRecord.get("OldImage");
JsonNode newItemImage = dynamoDBRecord.get("NewImage");
Instant recordTimestamp = fetchTimestamp(dynamoDBRecord);
/**
* Say for example our record contains a String attribute named "stringName" and we want to fetch the value
* of this attribute from the new item image. The following code fetches this value.
*/
JsonNode attributeNode = newItemImage.get("stringName");
JsonNode attributeValueNode = attributeNode.get("S"); // Using DynamoDB "S" type attribute
String attributeValue = attributeValueNode.textValue();
System.out.println(attributeValue);
}
private Instant fetchTimestamp(JsonNode dynamoDBRecord) {
JsonNode timestampJson = dynamoDBRecord.get("ApproximateCreationDateTime");
JsonNode timestampPrecisionJson = dynamoDBRecord.get("ApproximateCreationDateTimePrecision");
if (timestampPrecisionJson != null && timestampPrecisionJson.equals("MICROSECOND")) {
return Instant.EPOCH.plus(timestampJson.longValue(), ChronoUnit.MICROS);
}
return Instant.ofEpochMilli(timestampJson.longValue());
}
```
------
#### [ Java ]
1. Siga las instrucciones de la guía para desarrolladores de Kinesis Data Streams para [crear](https://docs.aws.amazon.com/streams/latest/dev/kinesis-using-sdk-java-create-stream.html) una secuencia de datos de Kinesis llamada `samplestream` usando Java.
Consulte [Consideraciones sobre la administración de particiones para Kinesis Data Streams](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment) antes de configurar el número de fragmentos para el flujo de datos de Kinesis.
1. Use el siguiente fragmento de código para habilitar el streaming de Kinesis en la tabla de DynamoDB. Si lo desea, active la transmisión con una precisión más detallada (microsegundos) de los valores de marca de tiempo devueltos en cada registro.
Active la transmisión con una precisión de marca de tiempo de microsegundos:
```
EnableKinesisStreamingConfiguration enableKdsConfig = EnableKinesisStreamingConfiguration.builder()
.approximateCreationDateTimePrecision(ApproximateCreationDateTimePrecision.MICROSECOND)
.build();
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.enableKinesisStreamingConfiguration(enableKdsConfig)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
O active la transmisión con la precisión de marca de tiempo predeterminada (milisegundos):
```
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
1. Siga las instrucciones de la *Guía para desarrolladores de Kinesis Data Streams* para [leer](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html) desde el flujo de datos creado.
1. Utilice el siguiente fragmento de código para deserializar el contenido del flujo.
```
/**
* Takes as input a Record fetched from Kinesis and does arbitrary processing as an example.
*/
public void processRecord(Record kinesisRecord) throws IOException {
ByteBuffer kdsRecordByteBuffer = kinesisRecord.getData();
JsonNode rootNode = OBJECT_MAPPER.readTree(kdsRecordByteBuffer.array());
JsonNode dynamoDBRecord = rootNode.get("dynamodb");
JsonNode oldItemImage = dynamoDBRecord.get("OldImage");
JsonNode newItemImage = dynamoDBRecord.get("NewImage");
Instant recordTimestamp = fetchTimestamp(dynamoDBRecord);
/**
* Say for example our record contains a String attribute named "stringName" and we wanted to fetch the value
* of this attribute from the new item image, the below code would fetch this.
*/
JsonNode attributeNode = newItemImage.get("stringName");
JsonNode attributeValueNode = attributeNode.get("S"); // Using DynamoDB "S" type attribute
String attributeValue = attributeValueNode.textValue();
System.out.println(attributeValue);
}
private Instant fetchTimestamp(JsonNode dynamoDBRecord) {
JsonNode timestampJson = dynamoDBRecord.get("ApproximateCreationDateTime");
JsonNode timestampPrecisionJson = dynamoDBRecord.get("ApproximateCreationDateTimePrecision");
if (timestampPrecisionJson != null && timestampPrecisionJson.equals("MICROSECOND")) {
return Instant.EPOCH.plus(timestampJson.longValue(), ChronoUnit.MICROS);
}
return Instant.ofEpochMilli(timestampJson.longValue());
}
```
------
## Aplicación de cambios en un flujo de datos de Amazon Kinesis activo
En esta sección se describe cómo realizar cambios en una configuración de Kinesis Data Streams para DynamoDB desde la consola, la AWS CLI o la API.
**Consola de administración de AWS**
1. Abra la consola de DynamoDB desde [ttps://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/).
1. Busque su tabla.
1. Elija la pestaña **Exportaciones y flujos**.
**AWS CLI**
1. Llame a `describe-kinesis-streaming-destination` para confirmar que el flujo es `ACTIVE`.
1. Llame a `UpdateKinesisStreamingDestination`, como en este ejemplo:
```
aws dynamodb update-kinesis-streaming-destination --table-name enable_test_table --stream-arn arn:aws:kinesis:us-east-1:12345678901:stream/enable_test_stream --update-kinesis-streaming-configuration ApproximateCreationDateTimePrecision=MICROSECOND
```
1. Llame a `describe-kinesis-streaming-destination` para confirmar que el flujo es `UPDATING`.
1. Llame a `describe-kinesis-streaming-destination` periódicamente hasta que el estado de la transmisión sea `ACTIVE` de nuevo. Las actualizaciones de precisión de la marca de tiempo suelen aplicarse al cabo de unos cinco minutos. Una vez actualizado el estado, significa que la actualización se ha completado y que el nuevo valor de precisión se aplicará a los registros futuros.
1. Escriba en la tabla con `putItem`.
1. Uso el comando `get-records` de Kinesis para recuperar el contenido del flujo.
1. Confirme que el `ApproximateCreationDateTime` de las escrituras tienen la precisión deseada.
**API de Java**
1. Proporcione un fragmento de código que construya una solicitud `UpdateKinesisStreamingDestination` y una respuesta `UpdateKinesisStreamingDestination`.
1. Proporcione un fragmento de código que construya una solicitud `DescribeKinesisStreamingDestination` y una `DescribeKinesisStreamingDestination response`.
1. Llame a `describe-kinesis-streaming-destination` periódicamente hasta que el estado del flujo sea `ACTIVE` de nuevo, lo que significa que la actualización se ha completado y que el nuevo valor de precisión se aplicará a los registros futuros.
1. Realice escrituras en la tabla.
1. Lea el flujo y deserialice el contenido del flujo.
1. Confirme que el `ApproximateCreationDateTime` de las escrituras tienen la precisión deseada.
# Uso de particiones y métricas con DynamoDB Streams y Kinesis Data Streams
## Consideraciones sobre la administración de particiones para Kinesis Data Streams
Un flujo de datos de Kinesis cuenta su rendimiento en [particiones](https://docs.aws.amazon.com/streams/latest/dev/key-concepts.html). En Amazon Kinesis Data Streams, puede elegir entre un modo **bajo demanda** y un modo **aprovisionado** para sus flujos de datos.
Se recomienda utilizar el modo bajo demanda para Kinesis Data Streams si la carga de trabajo de escritura de DynamoDB es muy variable e impredecible. Con el modo bajo demanda, no es necesario planificar la capacidad pues Kinesis Data Streams administra automáticamente las particiones para proporcionar el rendimiento necesario.
Para las cargas de trabajo predecibles, puede usar el modo aprovisionado para su flujo de datos de Kinesis. Con el modo aprovisionado, debe especificar el número de particiones del flujo de datos para adaptar los registros de captura de datos de cambios de DynamoDB. Para determinar el número de particiones que necesitará el flujo de datos de Kinesis para admitir la tabla de DynamoDB, necesitará los siguientes valores de entrada:
+ El tamaño promedio del registro de su tabla de DynamoDB en bytes (`average_record_size_in_bytes`).
+ El número máximo de operaciones de escritura que su tabla de DynamoDB llevará a cabo por segundo. Esto incluye las operaciones de creación, eliminación y actualización realizadas por sus aplicaciones, así como las operaciones generadas automáticamente, como las operaciones de eliminación generadas por Tiempo de vida (`write_throughput`).
+ El porcentaje de operaciones de actualización y sobrescritura que lleva a cabo en la tabla en comparación con las operaciones de creación o eliminación (`percentage_of_updates`). Tenga en cuenta que las operaciones de actualización y sobrescritura replican tanto las imágenes antiguas como las nuevas del elemento modificado en el flujo. Esto genera el doble del tamaño del elemento de DynamoDB.
Puede calcular el número de particiones (`number_of_shards`) que necesita su flujo de datos de Kinesis con los valores de entrada de la siguiente fórmula:
```
number_of_shards = ceiling( max( ((write_throughput * (4+percentage_of_updates) * average_record_size_in_bytes) / 1024 / 1024), (write_throughput/1000)), 1)
```
Por ejemplo, es posible que tenga un rendimiento máximo de 1040 operaciones de escritura por segundo (`write_throughput`) con un tamaño de registro medio de 800 bytes (`average_record_size_in_bytes)`). Si el 25 % de esas operaciones de escritura son operaciones de actualización (`percentage_of_updates`), necesitará dos particiones (`number_of_shards`) para adaptarse a su rendimiento de transmisión de DynamoDB:
```
ceiling( max( ((1040 * (4+25/100) * 800)/ 1024 / 1024), (1040/1000)), 1).
```
Tenga en cuenta lo siguiente antes de utilizar la fórmula para calcular el número de particiones necesarias con el modo aprovisionado para los flujos de datos de Kinesis:
+ Esta fórmula ayuda a realizar una estimación del número de particiones que se necesitará para acomodar los flujos de datos de cambios de DynamoDB. No representa el número total de particiones necesario en el flujo de datos de Kinesis, como el número de particiones necesario para admitir a los consumidores del flujo de datos de Kinesis.
+ En el modo aprovisionado, es posible que se produzcan excepciones en el rendimiento de lectura y escritura si no se configura el flujo de datos para manejar los picos de rendimiento. En este caso, debe escalar manualmente su flujo de datos para acomodar el tráfico de datos.
+ Esta fórmula tiene en cuenta la sobrecarga adicional que genera DynamoDB antes de transmitir los registros de datos de los registros de cambios al flujo de datos de Kinesis.
Para obtener más información sobre los modos de capacidad de Kinesis Data Streams, consulte [Choosing the Data Stream Capacity Mode](https://docs.aws.amazon.com/streams/latest/dev/how-do-i-size-a-stream.html). Para obtener más información sobre la diferencia de precios entre los distintos modos de capacidad, consulte [Precios de Amazon Kinesis Data Streams](https://aws.amazon.com/kinesis/data-streams/pricing/).
## Monitoreo de la captura de datos de cambios con Kinesis Data Streams
DynamoDB proporciona varias métricas de Amazon CloudWatch para ayudarlo a monitorear la replicación de la captura de datos de cambio en Kinesis. Para obtener una lista completa de las métricas de CloudWatch, consulte [Dimensiones y métricas de DynamoDB](metrics-dimensions.md).
Para determinar si el flujo tiene suficiente capacidad, le recomendamos que monitoree los siguientes elementos tanto durante la habilitación del flujo como en la producción:
+ `ThrottledPutRecordCount`: número de registros que el flujo de datos de Kinesis ha limitado porque la capacidad del flujo de datos de Kinesis es insuficiente. Es posible que experimente cierta limitación controlada durante picos de uso excepcionales, pero la `ThrottledPutRecordCount` debería ser lo más baja posible. DynamoDB vuelve a intentar enviar registros limitados al flujo de datos de Kinesis, pero esto podría dar lugar a una mayor latencia de replicación.
Si experimenta una limitación controlada excesiva y regular, es posible que tenga que aumentar el número de fragmentos del flujo de Kinesis proporcionalmente al rendimiento de escritura observado de la tabla. Para obtener más información sobre cómo determinar el tamaño de un flujo de datos de Kinesis, consulte [Determinar el tamaño inicial de un flujo de datos de Kinesis](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-streams.html#how-do-i-size-a-stream).
+ `AgeOfOldestUnreplicatedRecord`: el tiempo transcurrido desde el cambio de nivel de elemento más antiguo que aún no se ha replicado en el flujo de datos de Kinesis apareció en la tabla de DynamoDB. En funcionamiento normal, `AgeOfOldestUnreplicatedRecord` debe estar en el orden de milisegundos. Este número crece según los intentos de replicación fallidos cuando se deben a elecciones de configuración controladas por el cliente.
Si la métrica `AgeOfOldestUnreplicatedRecord` supera 168 horas, la replicación de los cambios en el nivel de elemento de la tabla de DynamoDB al flujo de datos de Kinesis se desactivará automáticamente.
Los ejemplos de las configuraciones controladas por el cliente que provocan intentos de replicación fallidos son una capacidad de flujo de datos de Kinesis no aprovisionada que produce una limitación excesiva o una actualización manual de las políticas de acceso del flujo de datos de Kinesis que evita que DynamoDB agregue datos al flujo de datos. Para mantener esta métrica lo más baja posible, es posible que tenga que garantizar el aprovisionamiento correcto de la capacidad del flujo de datos de Kinesis y asegurarse de que los permisos de DynamoDB no se modifiquen.
+ `FailedToReplicateRecordCount`: número de registros que DynamoDB no pudo replicar en el flujo de datos de Kinesis. Algunos elementos de más de 34 KB podrían expandirse de tamaño para cambiar los registros de datos que superan el límite de tamaño del elemento de 1 MB de Kinesis Data Streams. Esta expansión de tamaño se produce cuando estos elementos mayores a 34 KB incluyen un gran número de valores de atributos booleanos o vacíos. Los valores de atributos booleanos y vacíos se almacenan como 1 byte en DynamoDB, pero se expanden hasta 5 bytes cuando se serializan mediante JSON estándar para la replicación de Kinesis Data Streams. DynamoDB no puede replicar tales registros de cambios en el flujo de datos de Kinesis. DynamoDB omite estos registros de datos de cambios y continúa replicando automáticamente los registros posteriores.
Puede crear alarmas de Amazon CloudWatch que envíen un mensaje de Amazon Simple Notification Service (Amazon SNS) para notificación cuando cualquiera de las métricas anteriores supere un umbral específico.
# Uso de políticas de IAM para Amazon Kinesis Data Streams y Amazon DynamoDB
La primera vez que habilita Amazon Kinesis Data Streams para Amazon DynamoDB, DynamoDB le crea automáticamente un AWS Identity and Access Management (IAM) vinculado a servicio. Esta función, `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication`, permite a DynamoDB administrar la replicación de cambios a nivel de elemento en Kinesis Data Streams en su nombre. No elimine este rol vinculado a un servicio.
Para obtener más información acerca de los roles vinculados a servicios, consulte [Uso de roles vinculados a servicios](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) en la *Guía del usuario de IAM*.
**nota**
DynamoDB no admite condiciones basadas en etiquetas para las políticas de IAM.
Para habilitar Amazon Kinesis Data Streams para Amazon DynamoDB, debe tener los siguientes permisos en la tabla:
+ `dynamodb:EnableKinesisStreamingDestination`
+ `kinesis:ListStreams`
+ `kinesis:PutRecords`
+ `kinesis:DescribeStream`
Para describir Amazon Kinesis Data Streams para Amazon DynamoDB para una tabla de DynamoDB determinada, debe tener los siguientes permisos en la tabla.
+ `dynamodb:DescribeKinesisStreamingDestination`
+ `kinesis:DescribeStreamSummary`
+ `kinesis:DescribeStream`
Para deshabilitar Amazon Kinesis Data Streams para Amazon DynamoDB, debe tener los siguientes permisos en la tabla.
+ `dynamodb:DisableKinesisStreamingDestination`
Para actualizar Amazon Kinesis Data Streams para Amazon DynamoDB, la tabla debe tener los siguientes permisos.
+ `dynamodb:UpdateKinesisStreamingDestination`
En los siguientes ejemplos se muestra cómo utilizar las políticas de IAM para conceder permisos a Amazon Kinesis Data Streams para Amazon DynamoDB.
## Ejemplo: Habilitar Amazon Kinesis Data Streams para Amazon DynamoDB
La siguiente política de IAM otorga permisos para activar Amazon Kinesis Data Streams para Amazon DynamoDB para la tabla `Music`. No concede permisos para desactivar, actualizar ni describir Kinesis Data Streams para DynamoDB para la tabla `Music`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/kinesisreplication.dynamodb.amazonaws.com/AWSServiceRoleForDynamoDBKinesisDataStreamsReplication",
"Condition": {
"StringLike": {
"iam:AWSServiceName": "kinesisreplication.dynamodb.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:EnableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## Ejemplo: Actualizar Amazon Kinesis Data Streams para Amazon DynamoDB
La siguiente política de IAM otorga permisos para actualizar Amazon Kinesis Data Streams para Amazon DynamoDB para la tabla `Music`. No concede permisos para activar, desactivar ni describir Amazon Kinesis Data Streams para Amazon DynamoDB para la tabla `Music`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:UpdateKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## Ejemplo: Deshabilite Amazon Kinesis Data Streams para Amazon DynamoDB
La siguiente política de IAM otorga permisos para desactivar Amazon Kinesis Data Streams para Amazon DynamoDB para la tabla `Music`. No concede permisos para activar, actualizar ni describir Amazon Kinesis Data Streams para Amazon DynamoDB para la tabla `Music`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## Ejemplo: aplicar permisos de forma selectiva para Amazon Kinesis Data Streams para Amazon DynamoDB basados en recursos
La siguiente política de IAM concede permisos para activar y describir Amazon Kinesis Data Streams para Amazon DynamoDB para la tabla `Music` y deniega permisos para desactivar Amazon Kinesis Data Streams para Amazon DynamoDB para la tabla `Orders`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:EnableKinesisStreamingDestination",
"dynamodb:DescribeKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
},
{
"Effect": "Deny",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Orders"
}
]
}
```
------
## Uso de roles vinculados a servicios para Kinesis Data Streams para DynamoDB
Amazon Kinesis Data Streams para Amazon DynamoDB utiliza [roles vinculados a servicios](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role) de AWS Identity and Access Management (IAM). Un rol vinculado a un servicio es un tipo único de rol de IAM que está vinculado directamente a Kinesis Data Streams para DynamoDB. Los roles vinculados a servicios están predefinidos por Kinesis Data Streams para DynamoDB e incluyen todos los permisos que el servicio requiere para llamar a otros servicios de AWS en su nombre.
Un rol vinculado a un servicio simplifica la configuración de Kinesis Data Streams para DynamoDB porque ya no tendrá que agregar manualmente los permisos necesarios. Kinesis Data Streams para DynamoDB define los permisos de sus roles vinculados a servicios y, a menos que esté definido de otra manera, solo Kinesis Data Streams puede asumir sus roles. Los permisos definidos incluyen las políticas de confianza y de permisos, y que la política de permisos no se pueda asociar a ninguna otra entidad de IAM.
Para obtener información acerca de otros servicios que admiten roles vinculados a servicios, consulte [Servicios de AWS que funcionan con IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) y busque los servicios que muestran **Sí** en la columna **Rol vinculado a un servicio**. Elija una opción **Sí** con un enlace para ver la documentación acerca del rol vinculado al servicio en cuestión.
### Permisos de roles vinculados a servicios para Kinesis Data Streams para DynamoDB
Kinesis Data Streams para DynamoDB utiliza el rol vinculado a servicio denominado **AWSServiceRoleForDynamodBkinesisDataStreamsReplication**. El propósito del rol vinculado a servicios es permitir que Amazon DynamoDB administre la replicación de cambios a nivel de elemento en Kinesis Data Streams, en su nombre.
El rol vinculado al servicio `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` depende de los siguientes servicios para asumir el rol:
+ `kinesisreplication.dynamodb.amazonaws.com`
La política de permisos del rol permite que Kinesis Data Streams para DynamoDB realice las siguientes acciones en los recursos especificados:
+ Acción: `Put records and describe` en `Kinesis stream`
+ Acción: `Generate data keys` en `AWS KMS` para poner datos en las transmisiones de Kinesis cifrados mediante claves de AWS KMS generadas por el usuario.
Para conocer el contenido exacto del documento de política, consulte [DynamoDBKinesisReplicationServiceRolePolicy](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/aws-service-role/DynamoDBKinesisReplicationServiceRolePolicy).
Debe configurar permisos para permitir a una entidad de IAM (como un usuario, grupo o rol) crear, editar o eliminar un rol vinculado a servicios. Para obtener más información, consulte [Permisos de roles vinculados a servicios](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#service-linked-role-permissions) en la *Guía del usuario de IAM*.
### Creación de un rol vinculado a un servicio para Kinesis Data Streams para DynamoDB
No necesita crear manualmente un rol vinculado a servicios. Cuando habilita Kinesis Data Streams para DynamoDB en la Consola de administración de AWS, la AWS CLI, o la API de AWS, Kinesis Data Streams para DynamoDB crea automáticamente el rol vinculado al servicio.
Si elimina este rol vinculado a servicios y necesita crearlo de nuevo, puede utilizar el mismo proceso para volver a crear el rol en su cuenta. Cuando habilita Kinesis Data Streams para DynamoDB, Kinesis Data Streams para DynamoDB vuelve a crear el rol vinculado al servicio.
### Edición de un rol vinculado a un servicio para Kinesis Data Streams para DynamoDB
Kinesis Data Streams para DynamoDB no permite editar el rol vinculado al servicio `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication`. Después de crear un rol vinculado al servicio, no podrá cambiar el nombre del rol, ya que varias entidades podrían hacer referencia al rol. Sin embargo, sí puede editar la descripción del rol con IAM. Para obtener más información, consulte [Edición de un rol vinculado a servicios](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#edit-service-linked-role) en la *Guía del usuario de IAM*.
### Eliminación de un rol vinculado a un servicio para Kinesis Data Streams para DynamoDB
También puede utilizar la consola de IAM, la AWS CLI o la API de AWS para eliminar manualmente el rol vinculado al servicio. Para ello, primero debe limpiar manualmente los recursos del rol vinculado al servicio para poder eliminarlo después manualmente.
**nota**
Si el servicio Kinesis Data Streams para DynamoDB está utilizando el rol cuando intenta eliminar los recursos, la eliminación podría producir un error. En tal caso, espere unos minutos e intente de nuevo la operación.
**Para eliminar manualmente el rol vinculado a servicios mediante IAM**
Puede usar la consola de IAM, la AWS CLI o la API de AWS para eliminar el rol vinculado a un servicio de `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication`. Para más información, consulte [Eliminación de un rol vinculado a servicios](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) en la *Guía del usuario de IAM*.
# Captura de datos de cambios para DynamoDB Streams
DynamoDB Streams captura una secuencia en orden cronológico de las modificaciones de los elementos en una tabla de DynamoDB y almacena esta información en un log durante un máximo de 24 horas. Las aplicaciones pueden obtener acceso a este registro y ver los elementos de datos tal y como se encontraban antes y después de la modificación, prácticamente en tiempo real.
El cifrado en reposo cifra los datos en DynamoDB streams. Para obtener más información, consulte [Cifrado en reposo en DynamoDB](EncryptionAtRest.md).
Una *transmisión de DynamoDB* es un flujo ordenado de información sobre los cambios que se realizan en los elementos de una tabla de DynamoDB. Cuando se habilita una transmisión en una tabla, DynamoDB obtiene información sobre cada modificación de los elementos de datos de esa tabla.
Cada vez que una aplicación crea, actualiza o elimina elementos en la tabla, DynamoDB Streams escribe un registro de transmisión con los atributos de clave principal de los elementos modificados. Un *registro de transmisión* contiene información sobre una modificación de los datos de un solo elemento de una tabla de DynamoDB. Puede configurar la secuencia de tal forma que sus registros capturen información adicional; por ejemplo, las imágenes de "antes" y "después" de los elementos modificados.
DynamoDB Streams ayuda a garantizar lo siguiente:
+ Cada registro de secuencia aparece una única vez en la secuencia.
+ Para cada elemento que se modifica de una tabla de DynamoDB, los registros de transmisión aparecen en el mismo orden en que se han realizado las modificaciones del elemento.
DynamoDB Streams escribe los registros de transmisión prácticamente en tiempo real, para que pueda crear aplicaciones que consuman estas transmisiones y adopten medidas en función de su contenido.
**Topics**
+ [Endpoints para DynamoDB Streams](#Streams.Endpoints)
+ [Habilitación de una secuencia](#Streams.Enabling)
+ [Lectura y procesamiento de un flujo](#Streams.Processing)
+ [DynamoDB Streams y período de vida](time-to-live-ttl-streams.md)
+ [Uso del adaptador Kinesis de DynamoDB Streams para procesar registros de transmisión](Streams.KCLAdapter.md)
+ [API de bajo nivel de DynamoDB Streams: ejemplo en Java](Streams.LowLevel.Walkthrough.md)
+ [DynamoDB Streams y disparadores de AWS Lambda](Streams.Lambda.md)
+ [DynamoDB Streams y Apache Flink](StreamsApacheFlink.xml.md)
## Endpoints para DynamoDB Streams
AWS mantiene puntos de enlace distintos para DynamoDB y DynamoDB Streams. Para usar las tablas y los índices de la base de datos, la aplicación tendrá que acceder a un punto de enlace de DynamoDB. Para leer y procesar los registros de DynamoDB Streams, la aplicación tendrá que obtener acceso a un punto de enlace de DynamoDB Streams situado en la misma región.
DynamoDB Streams ofrece dos conjuntos de puntos de conexión. Son los siguientes:
+ **Puntos de conexión exclusivos para IPv4**: puntos de conexión con la convención de nomenclatura de `streams.dynamodb..amazonaws.com`.
+ **Puntos de conexión de doble pila**: puntos de conexión nuevos que son compatibles con IPv4 e IPv6 y que siguen la convención de nomenclatura de `streams-dynamodb..api.aws`.
**nota**
Para obtener una lista completa de las regiones y puntos de conexión de DynamoDB y DynamoDB Streams, consulte [Regiones y puntos de conexión](https://docs.aws.amazon.com/general/latest/gr/rande.html) en la *Referencia general de AWS*.
Los SDK de AWS proporcionan clientes independientes para DynamoDB y DynamoDB Streams. Según cuáles sean sus necesidades, la aplicación puede obtener acceso a un punto de enlace de DynamoDB, a un punto de enlace de DynamoDB Streams o a ambos al mismo tiempo. Para conectarse a ambos puntos de enlace, la aplicación tendrá que crear instancias de dos clientes: uno para DynamoDB y otro para DynamoDB Streams.
## Habilitación de una secuencia
Puede habilitar una transmisión en una nueva tabla al crearla mediante la AWS CLI o uno de los SDK de AWS. También puede habilitar o deshabilitar una transmisión en una tabla existente, así como cambiar la configuración de una transmisión. DynamoDB Streams opera de forma asincrónica, por lo que el rendimiento de una tabla no se vea afectado al habilitar una transmisión.
La forma más sencilla de administrar DynamoDB Streams es usar la Consola de administración de AWS.
1. Inicie sesión en la Consola de administración de AWS y abra la consola de DynamoDB en [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/).
1. En el panel de la consola de DynamoDB, elija **Tablas** y seleccione una tabla existente.
1. Elija la pestaña **Exports and streams** (Exportaciones y flujos).
1. En la sección **Detalles del flujo de DynamoDB**, seleccione **Activar**.
1. En la ventana **Activar el flujo de DynamoDB**, elija la información que se escribirá en el flujo cada vez que se modifiquen los datos de la tabla:
+ **Key attributes only** (Solo atributos clave): solo los atributos clave del elemento modificado.
+ **New image (Nueva imagen)**: el elemento completo tal y como aparece después de modificarlo.
+ **Old image (Imagen anterior)**: el elemento completo tal y como aparecía antes de modificarlo.
+ **New and old images (Imágenes nuevas y anteriores)**: ambas imágenes del elemento, la nueva y la anterior.
Cuando la configuración sea la que desea, elija **Activar flujo**.
1. (Opcional) Para desactivar un flujo existente, elija **Desactivar** bajo **Detalles del flujo de DynamoDB**.
También puede usar las operaciones de la API `CreateTable` o `UpdateTable` para habilitar o modificar una secuencia, respectivamente. El parámetro `StreamSpecification` determina cómo se configura la secuencia:
+ `StreamEnabled`: especifica si una transmisión está habilitada (`true`) o deshabilitada (`false`) para la tabla.
+ `StreamViewType`: especifica la información que se escribirá en la transmisión cada vez que se modifiquen los datos de la tabla:
+ `KEYS_ONLY`: solo los atributos de clave del elemento modificado.
+ `NEW_IMAGE`: el elemento completo tal y como aparece después de modificarlo.
+ `OLD_IMAGE`: el elemento completo tal y como aparecía antes de modificarlo.
+ `NEW_AND_OLD_IMAGES`: ambas imágenes del elemento, la nueva y la anterior.
Puede habilitar o deshabilitar una secuencia en cualquier momento. Sin embargo, tenga en cuenta que recibirá una excepción `ValidationException` si intenta habilitar una secuencia en una tabla que ya tiene una. Recibirá una `ValidationException` si intenta desactivar una secuencia en una tabla que no tiene ninguna.
Cuando se establece `StreamEnabled` en `true`, DynamoDB crea una nueva transmisión con un descriptor de transmisión único asignado a ella. Si deshabilita y vuelve a habilitar una secuencia en la tabla, se crea una secuencia nueva con un descriptor de secuencia distinto.
Cada secuencia se identifica de forma exclusiva mediante un nombre de recurso de Amazon (ARN). A continuación se muestra un ejemplo de ARN de una transmisión de una tabla de DynamoDB denominada `TestTable`.
```
arn:aws:dynamodb:us-west-2:111122223333:table/TestTable/stream/2015-05-11T21:21:33.291
```
Para determinar el último descriptor de transmisión de una tabla, se emite una solicitud `DescribeTable` de DynamoDB y se busca el elemento `LatestStreamArn` en la respuesta.
**nota**
No es posible editar un `StreamViewType` una vez que se ha configurado un flujo. Si necesita realizar cambios en un flujo después de haberlo configurado, debe desactivar el flujo actual y crear uno nuevo.
## Lectura y procesamiento de un flujo
Para leer y procesar una transmisión, la aplicación tiene que conectarse a un punto de enlace de DynamoDB Streams y emitir solicitudes de API.
Una secuencia consta de *registros de secuencia*. Cada registro de transmisión representa una única modificación de datos de la tabla de DynamoDB a la que pertenece la secuencia. A cada registro de secuencia se le asigna un número de secuencia que refleja el orden en que el registro se ha publicado en la secuencia.
Los registros de secuencia se organizan en grupos, o *fragmentos*. Cada fragmento actúa como contenedor de varios registros de secuencia y contiene la información necesaria para obtener acceso a estos registros y recorrerlos en iteración. Los registros de secuencia de un fragmento se eliminan automáticamente transcurridas de 24 horas.
Los fragmentos son efímeros: se crean y eliminan automáticamente, según sea necesario. Además, cualquier fragmento se puede dividir en varios fragmentos nuevos; esto también sucede automáticamente. (Cabe destacar que un fragmento principal puede tener un solo fragmento secundario). Un fragmento se puede dividir en respuesta a niveles de actividad de escritura elevados en la tabla principal, para que las aplicaciones puedan procesar en paralelo los registros de varios fragmentos.
Si se deshabilita una secuencia, todos fragmentos que estén abiertos se cerrarán. Los datos de la transmisión continuarán disponibles para leerlos durante 24 horas.
Como los fragmentos poseen un parentesco (principales y secundarios), las aplicaciones siempre deben procesar los fragmentos principales antes de procesar los secundarios. Esto ayuda a garantizar que los registros de secuencia se procesen también en el orden correcto. (Si utiliza DynamoDB Streams Kinesis Adapter, esto se lleva a cabo de forma automatizada: la aplicación procesará los fragmentos y registros de transmisión en el orden correcto y también administrará automáticamente los fragmentos nuevos o vencidos, así como aquellos que se dividan mientras se ejecuta la aplicación. Para obtener más información, consulte ). [Uso del adaptador Kinesis de DynamoDB Streams para procesar registros de transmisión](Streams.KCLAdapter.md).)
En el siguiente diagrama se muestra la relación entre una secuencia, sus fragmentos y los registros de secuencia contenidos en los fragmentos.
![\[Estructura de DynamoDB Streams. Los registros de secuencia que representan modificaciones de datos se organizan en particiones.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/streams-terminology.png)
**nota**
Si lleva a cabo una operación `PutItem` o `UpdateItem` que no modifica ningún dato de un elemento, DynamoDB Streams *no* escribe ningún registro de transmisión de esa operación.
Para obtener acceso a una secuencia y procesar los registros que contiene, proceda como sigue:
+ Determine el ARN único de la secuencia a la que desea obtener acceso.
+ Determine qué fragmentos de la secuencia contienen los registros de secuencia que le interesan.
+ Obtenga acceso a los fragmentos y recupere los registros de secuencia que desee.
**nota**
Nunca debe haber más de dos procesos leyendo la misma partición de flujo a la vez. Usar más de dos procesos de lectura por fragmento puede provocar que se aplique la limitación controlada.
La API de DynamoDB Streams ofrece las siguientes acciones para usarlas en los programas de aplicación:
+ `[ListStreams](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_ListStreams.html)`: devuelve una lista de descriptores de transmisión de la cuenta y el punto de enlace actuales. Si lo desea, puede solicitar únicamente los descriptores de secuencia de un nombre de tabla concreto.
+ `[DescribeStream](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_DescribeStream.html)`: devuelve información sobre un flujo, incluido el estado actual del flujo, su nombre de recurso de Amazon (ARN), la composición de sus particiones y su tabla de DynamoDB correspondiente. Puede utilizar opcionalmente el campo `ShardFilter` para recuperar la partición secundaria existente asociada a la partición principal.
+ `[GetShardIterator](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetShardIterator.html)`: devuelve un *iterador de fragmentos* que describe una ubicación en el fragmento. Puede solicitar que el iterador proporcione acceso al punto más antiguo, al punto más reciente o a un punto concreto de la secuencia.
+ `[GetRecords](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetRecords.html)`: devuelve los registros de secuencia de un fragmento determinado. Debe proporcionar el iterador de fragmentos devuelto por una solicitud `GetShardIterator`.
Para obtener descripciones completas de estas operaciones de la API, así como ejemplos de solicitudes y respuestas, consulte la [Referencia de API de Amazon DynamoDB Streams](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Operations_Amazon_DynamoDB_Streams.html).
### Detección de particiones
Descubra nuevas particiones en el flujo de DynamoDB con dos métodos potentes. Como usuario de Amazon DynamoDB Streams, dispone de dos formas efectivas de rastrear e identificar nuevas particiones:
**Sondeo de toda la topología del flujo**
Use la API de `DescribeStream` para sondear el flujo con regularidad. Esto devuelve todas las particiones de la transmisión, incluidas las nuevas particiones que se hayan creado. Al comparar los resultados a lo largo del tiempo, puede detectar las particiones recién agregadas.
**Detección de particiones secundarias**
Use la API de `DescribeStream` con el parámetro `ShardFilter` para encontrar un subconjunto de particiones. Al especificar una partición principal en la solicitud, los flujos de DynamoDB devolverán sus particiones secundarias inmediatas. Este enfoque resulta útil cuando solo se necesita rastrear el linaje de las particiones sin escanear todo el flujo.
Las aplicaciones que consumen datos de los flujos de DynamoDB pueden pasar de manera eficiente de leer una partición cerrada a su partición secundaria mediante este parámetro `ShardFilter`, lo que evita llamadas repetidas a la API de `DescribeStream` para recuperar y recorrer el mapa de particiones de todas las particiones cerradas y abiertas. Esto ayuda a detectar rápidamente las particiones secundarias después de cerrar la partición principal, lo que hace que las aplicaciones de procesamiento de flujos sean más receptivas y rentables.
Ambos métodos le permiten mantenerse al tanto de la estructura en evolución de los flujos de DynamoDB, lo que garantiza que nunca se pierda las actualizaciones de datos importantes ni las modificaciones de las particiones.
### Límite de retención de datos para DynamoDB Streams
Todos los datos de DynamoDB Streams están sujetos a una vida útil de 24 horas. Puede recuperar y analizar las últimas 24 horas de actividad de cada tabla. Sin embargo, los datos de más de 24 horas se pueden recortar (eliminar) en cualquier momento.
Si deshabilita una secuencia en una tabla, los datos de esa secuencia continuarán disponibles para leerlos durante 24 horas. Transcurrido ese tiempo, los datos vencen y los registros de secuencia se eliminan automáticamente. No existe ningún mecanismo para eliminar manualmente las secuencias. Tiene que esperar hasta que se alcance el límite de retención (24 horas) para que se eliminen los registros de secuencia.
# DynamoDB Streams y período de vida
Puede realizar copias de seguridad o bien procesar los elementos eliminados por [período de vida](TTL.md) (TTL, por sus siglas en inglés) habilitando Amazon DynamoDB Streams en la tabla y procesando los registros de transmisión de los elementos vencidos. Para obtener más información, consulte [Lectura y procesamiento de un flujo](Streams.md#Streams.Processing).
El registro de secuencias contiene el campo de identidad del usuario `Records[].userIdentity`.
Los elementos que el proceso período de vida elimina tras su vencimiento tienen los siguientes campos:
+ `Records[].userIdentity.type`
`"Service"`
+ `Records[