Amazon DynamoDB
Guía para desarrolladores (Versión de API 2012-08-10)

Uso de consultas en DynamoDB

La operación Query en Amazon DynamoDB busca elementos según los valores de clave principal. Puede consultar cualquier tabla o índice secundario que cuenta con una clave principal compuesta (una clave de partición y una clave de ordenación).

Debe proporcionar el nombre del atributo de clave de partición y un único valor para dicho atributo. Query devuelve todos los elementos que contengan ese valor de clave de partición. Si lo desea, puede proporcionar un atributo de clave de ordenación y utilizar un operador de comparación para limitar los resultados de búsqueda.

Expresiones de condición de clave

Para especificar los criterios de búsqueda, se utiliza una expresión de condición de clave; se trata de una cadena que determina los elementos que se van a leer en la tabla o el índice.

Debe especificar el nombre y valor de la clave de partición como una condición de igualdad.

Si lo desea, puede proporcionar una segunda condición para la clave de ordenación (en caso de incluirse). En la condición de clave de ordenación se debe utilizar uno de los siguientes operadores de comparación:

  • a = b: es true si el atributo a es igual al valor b.

  • a < b: es true si a es menor que b.

  • a <= b: es true si a es menor o igual que b.

  • a > b: es true si a es mayor que b.

  • a >= b: es true si a es mayor o igual que b.

  • a BETWEEN b AND c: es true si a es mayor o igual que b y menor o igual que c.

También se admite la siguiente función:

  • begins_with (a, substr): es true si el valor del atributo a comienza por una subcadena determinada.

En los siguientes ejemplos de la AWS Command Line Interface (AWS CLI) se muestra el uso de expresiones de condición de clave. Estas expresiones utilizan marcadores de posición (como :name y :sub) en lugar de los valores reales. Para obtener más información, consulte Nombres de atributos de expresión y Valores de los atributos de expresión.

ejemplo

Consulta la tabla Thread para buscar un valor concreto de ForumName (clave de partición). La consulta leerá todos los elementos que tengan ese valor de ForumName, porque la clave de ordenación (Subject) no se incluye en KeyConditionExpression.

aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :name" \ --expression-attribute-values '{":name":{"S":"Amazon DynamoDB"}}'

ejemplo

Consulta la tabla Thread para buscar un valor concreto de ForumName (clave de partición), pero esta vez devuelve solo los elementos que tienen un valor determinado de Subject (clave de ordenación).

aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :name and Subject = :sub" \ --expression-attribute-values file://values.json

Los argumentos de --expression-attribute-values se almacenan en el archivo values.json.

{ ":name":{"S":"Amazon DynamoDB"}, ":sub":{"S":"DynamoDB Thread 1"} }

ejemplo

Consulta la tabla Reply para buscar un valor concreto de Id (clave de partición), pero solo devuelve los elementos cuyo valor de ReplyDateTime (clave de ordenación) comienza por determinados caracteres.

aws dynamodb query \ --table-name Reply \ --key-condition-expression "Id = :id and begins_with(ReplyDateTime, :dt)" \ --expression-attribute-values file://values.json

Los argumentos de --expression-attribute-values se almacenan en el archivo values.json.

{ ":id":{"S":"Amazon DynamoDB#DynamoDB Thread 1"}, ":dt":{"S":"2015-09"} }

Puede utilizar cualquier nombre de atributo en una expresión de condición de clave, siempre y cuando el primer carácter sea a-z o A-Z y el segundo carácter (si lo hay) sea a-z, A-Z o 0-9. Además, el nombre de atributo no debe ser una palabra reservada de DynamoDB. Para obtener una lista completa de estas palabras, consulte Palabras reservadas en DynamoDB. Si un nombre de atributo no cumple estos requisitos, debe definir un nombre de atributo de expresión como marcador de posición. Para obtener más información, consulte Nombres de atributos de expresión.

DynamoDB almacena cerca unos de otros y ordenados según su clave de ordenación aquellos elementos que tienen un valor de clave de partición determinado. En una operación Query, DynamoDB recupera los elementos de forma ordenada y, a continuación, los procesa mediante las expresiones KeyConditionExpression y FilterExpression que estén presentes. Solo entonces devuelve los resultados de Query al cliente.

Una operación Query siempre devuelve un conjunto de resultados. Si no se encuentran elementos coincidentes, el conjunto de resultados está vacío.

Los resultados de Query siempre se ordenan según el valor de la clave de ordenación. Si el tipo de datos de la clave de ordenación es Number, los resultados se devuelven en orden numérico. De lo contrario, los resultados se devuelven según el orden de los bytes UTF-8. De forma predeterminada, el orden es ascendente. Para invertirlo, establezca el parámetro ScanIndexForward en false.

En una sola operación Query se puede recuperar un máximo de 1 MB de datos. Este límite se aplica antes de aplicar cualquier expresión FilterExpression a los resultados. Si LastEvaluatedKey está presente en la respuesta y su valor no es null, debe paginar el conjunto de resultados (consulte Paginación de los resultados).

Expresiones de filtro para Query

Si tiene que refinar más los resultados de Query, si lo desea puede indicar una expresión de filtro. Una expresión de filtro determina qué elementos de los resultados de Query se deben devolver al usuario. Todos los demás resultados se descartan.

Una expresión de filtro se aplica después de que la operación Query haya finalizado, pero antes de devolver los resultados. Por consiguiente, Query consume la misma cantidad de capacidad de lectura aunque se especifique una expresión de filtro.

En una operación Query se puede recuperar un máximo de 1 MB de datos. Este límite se aplica antes de evaluar la expresión de filtro.

Una expresión de filtro no puede contener atributos de clave de partición ni de clave de ordenación. Esos atributos se deben especificar en la expresión de condición de clave, no en la expresión de filtro.

La sintaxis de una expresión de filtro es la misma que la de una expresión de condición. Las expresiones de filtro pueden utilizar los comparadores, funciones y operadores lógicos que las expresiones de condición. Para obtener más información, Expresiones de condición.

ejemplo

En el siguiente ejemplo de la AWS CLI, se consulta la tabla Thread para buscar un valor concreto de ForumName (clave de partición) y Subject (clave de ordenación). De los elementos encontrados, solo se devuelven las conversaciones más populares; es decir, solo aquellas que tienen un valor de Views mayor que el número especificado.

aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :fn and Subject = :sub" \ --filter-expression "#v >= :num" \ --expression-attribute-names '{"#v": "Views"}' \ --expression-attribute-values file://values.json

Los argumentos de --expression-attribute-values se almacenan en el archivo values.json.

{ ":fn":{"S":"Amazon DynamoDB"}, ":sub":{"S":"DynamoDB Thread 1"}, ":num":{"N":"3"} }

Tenga en cuenta que Views es una palabra reservada en DynamoDB (consulte Palabras reservadas en DynamoDB), por lo que en este ejemplo se utiliza #v como marcador de posición. Para obtener más información, consulte Nombres de atributos de expresión.

nota

Una expresión de filtro elimina los elementos del conjunto de resultados de Query. Si es posible, evite usar Query cuando prevea que va a recuperar gran cantidad de elementos, pero que tendrá que descartar la mayoría de ellos.

Limitación del número de elementos del conjunto de resultados

La operación Query permite limitar el número de elementos que devuelve en el resultado. Para ello, establezca el parámetro Limit en el número máximo de elementos que desee.

Por ejemplo, suponga que utiliza Query en una tabla con un valor de Limit de 6 y sin expresión de filtro. El resultado de Query contendrá los seis primeros elementos de la tabla que coincidan con la expresión de condición de clave de la solicitud.

Ahora, suponga que agrega una expresión de filtro a Query. En este caso, DynamoDB aplica la expresión de filtro a los seis elementos que se hayan devuelto y descarta los que no coincidan. El resultado de Query final contendrá 6 elementos o menos, según el número de elementos que el filtro elimine.

Paginación de los resultados

DynamoDB pagina los resultados de las operaciones Query. La paginación permite dividir los resultados de Query en "páginas" de datos con un tamaño de 1 MB (o menos). Una aplicación puede procesar la primera página de resultados, luego la segunda página, y así sucesivamente.

Una operación Query única devuelve solamente un conjunto de resultados que se ajuste al límite de tamaño de 1 MB. Para determinar si hay más resultados y para recuperarlos de página en página, las aplicaciones deben hacer lo siguiente:

  1. Examinar el resultado de Query de bajo nivel:

    • Si el resultado contiene una entrada LastEvaluatedKey, vaya al paso 2.

    • Si no figura LastEvaluatedKey en el resultado, no hay más elementos que recuperar.

  2. Crear una nueva solicitud Query con los mismos parámetros que la anterior. Sin embargo, esta vez, se toma el valor LastEvaluatedKey del paso 1 y se usa como parámetro ExclusiveStartKey en la nueva solicitud Query.

  3. Ejecutar la nueva solicitud Query.

  4. Ir al paso 1.

Es decir, el valor de LastEvaluatedKey de la respuesta de Query debe utilizarse como valor de ExclusiveStartKey en la siguiente solicitud Query. Si no hay una entrada LastEvaluatedKey en una respuesta de Query, significa que se ha recuperado la última página de resultados. Si LastEvaluatedKey no está vacía, no significa necesariamente que haya más datos en el conjunto de resultados. La única forma de saber que se ha alcanzado el final del conjunto de resultados es cuando LastEvaluatedKey está vacío.

Puede utilizar la AWS CLI para ver este comportamiento. La CLI envía solicitudes Query de bajo nivel a DynamoDB una y otra vez hasta que LastEvaluatedKey ya no esté presente en los resultados. Considere el siguiente ejemplo de la AWS CLI que recupera títulos de películas de un determinado año:

aws dynamodb query --table-name Movies \ --projection-expression "title" \ --key-condition-expression "#y = :yyyy" \ --expression-attribute-names '{"#y":"year"}' \ --expression-attribute-values '{":yyyy":{"N":"1993"}}' \ --page-size 5 \ --debug

Normalmente, la AWS CLI se encarga de la paginación automáticamente. No obstante, en este ejemplo, el parámetro --page-size de la AWS CLI limita el número de elementos por página. El parámetro --debug muestra información de bajo nivel de las solicitudes y las respuestas.

Si ejecuta el ejemplo, la primera respuesta de DynamoDB será similar a la siguiente.

2017-07-07 11:13:15,603 - MainThread - botocore.parsers - DEBUG - Response body: b'{"Count":5,"Items":[{"title":{"S":"A Bronx Tale"}}, {"title":{"S":"A Perfect World"}},{"title":{"S":"Addams Family Values"}}, {"title":{"S":"Alive"}},{"title":{"S":"Benny & Joon"}}], "LastEvaluatedKey":{"year":{"N":"1993"},"title":{"S":"Benny & Joon"}}, "ScannedCount":5}'

El elemento LastEvaluatedKey de la respuesta indica que no se han recuperado todos los elementos. La AWS CLI envía entonces otra solicitud Query a DynamoDB. Este patrón de solicitud y respuesta continúa hasta la respuesta final.

2017-07-07 11:13:16,291 - MainThread - botocore.parsers - DEBUG - Response body: b'{"Count":1,"Items":[{"title":{"S":"What\'s Eating Gilbert Grape"}}],"ScannedCount":1}'

La ausencia de LastEvaluatedKey indica que no hay más elementos que recuperar.

nota

Los SDK de AWS se encargan también de las respuestas de DynamoDB de bajo nivel (incluida la presencia o ausencia de LastEvaluatedKey) y proporcionan varias abstracciones para paginar los resultados de Query. Por ejemplo, la interfaz de documentos de SDK para Java proporciona compatibilidad con java.util.Iterator para que pueda examinar los resultados de uno en uno.

Para ver ejemplos de código en diversos lenguajes de programación, consulte la Guía de introducción a Amazon DynamoDB y la documentación del SDK de AWS correspondiente a su lenguaje.

Recuento de los elementos de los resultados

Además de los elementos que coinciden con los criterios, la respuesta de Query contiene las entradas siguientes:

  • ScannedCount: número de elementos que coinciden con la expresión de condición de clave antes de aplicar una expresión de filtro (si la hay).

  • Count: número de elementos restantes después de aplicar una expresión de filtro (si la hay).

nota

Si no se utiliza una expresión de filtro, ScannedCount y Count tendrán el mismo valor.

Si el tamaño del conjunto de resultados de Query es mayor que 1 MB, entonces ScannedCount y Count representarán únicamente un recuento parcial de los elementos totales. Deberá llevar a cabo varias operaciones Query para recuperar todos los resultados (consulte Paginación de los resultados).

Cada respuesta de Query contendrá los valores de ScannedCount y Count de los elementos que se han procesado en esa solicitud Query concreta. Para obtener totales globales para todas las solicitudes Query, puede llevar un recuento total de ScannedCount y Count.

Unidades de capacidad que Query consume

Puede consultar con Query cualquier tabla o índice secundario, siempre y cuando tengan una clave principal compuesta (una clave de partición y una clave de ordenación). Las operaciones Query consumen unidades de capacidad de lectura, como se indica a continuación.

Si Query se aplica a... DynamoDB consume unidades de capacidad de lectura de...
Tabla La capacidad de lectura aprovisionada de la tabla.
Global secondary index La capacidad de lectura aprovisionada del índice.
Índice secundario local La capacidad de lectura aprovisionada de la tabla base.

De forma predeterminada, una operación Query no devuelve datos sobre la cantidad de capacidad de lectura que consume. Sin embargo, puede especificar el parámetro ReturnConsumedCapacity en una solicitud Query para obtener esta información. A continuación se muestran los ajustes válidos de ReturnConsumedCapacity:

  • NONE: no se devuelven datos de capacidad consumida. (Esta es la opción predeterminada.)

  • TOTAL: la respuesta incluye el número total de unidades de capacidad de lectura consumidas.

  • INDEXES: la respuesta muestra el número total de unidades de capacidad de lectura consumidas, así como la capacidad consumida de cada tabla e índice a los que se ha obtenido acceso.

DynamoDB calcula el número de unidades de capacidad de lectura consumidas según el tamaño de los elementos y no según la cantidad de datos que se devuelven a la aplicación. Por este motivo, el número de unidades de capacidad consumidas es el mismo si se solicitan todos los atributos (el comportamiento predeterminado) o solo algunos de ellos (mediante una expresión de proyección). El número también será el mismo tanto si se utiliza una expresión de filtro como si no.

Consistencia de lectura de Query

De forma predeterminada, una operación Query lleva a cabo lecturas consistentes finales. Esto significa que los resultados de Query podrían no reflejar los cambios provocados por operaciones PutItem o UpdateItem realizadas recientemente. Para obtener más información, consulte Consistencia de lectura.

Si requiere lecturas de consistencia alta, establezca el parámetro ConsistentRead en true en la solicitud Query.