# Consulta de tablas en DynamoDB Puede usar la operación de la API `Query` en Amazon DynamoDB para buscar elementos según los valores de clave principal. 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. Para obtener más información sobre cómo usar `Query`, como la sintaxis de la solicitud, los parámetros de respuesta y ejemplos adicionales, consulte [Query](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html) en la *Referencia de la API de Amazon DynamoDB*. **Topics** + [ # Expresiones de condición de clave para la operación Query en DynamoDB ](Query.KeyConditionExpressions.md) + [ # Expresiones de filtro para la operación Query en DynamoDB ](Query.FilterExpression.md) + [ # Paginación de los resultados de consulta de tabla en DynamoDB ](Query.Pagination.md) + [ # Otros aspectos del trabajo con la operación Query en DynamoDB ](Query.Other.md) # Expresiones de condición de clave para la operación Query en DynamoDB 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 resto de los caracteres (a partir del 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](ReservedWords.md).) 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 (Alias) en DynamoDB](Expressions.ExpressionAttributeNames.md). 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. `Query`Los resultados de 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 que `FilterExpression` o `ProjectionExpression` se apliquen 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 de consulta de tabla en DynamoDB](Query.Pagination.md)). ## Ejemplos de expresión 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. No puede utilizar un atributo no clave en una expresión de condición clave. 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 (Alias) en DynamoDB](Expressions.ExpressionAttributeNames.md) y [Uso de valores de atributos de expresión en DynamoDB](Expressions.ExpressionAttributeValues.md). **Example** 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"}}' ``` **Example** 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"} } ``` **Example** 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"} } ``` # Expresiones de filtro para la operación Query en DynamoDB 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 similar a la de una expresión de condición de clave. Las expresiones de filtro pueden utilizar los mismos comparadores, funciones y operadores lógicos que las expresiones de condición de clave. Además, las expresiones de filtro pueden usar los operadores “no es igual” (`<>`), `OR`, `CONTAINS`, `IN`, `BEGINS_WITH`, `BETWEEN`, `EXISTS` y `SIZE`. Para obtener más información, consulte [Expresiones de condición de clave para la operación Query en DynamoDB](Query.KeyConditionExpressions.md) y [Sintaxis de las expresiones de filtro y condición](Expressions.OperatorsAndFunctions.md#Expressions.OperatorsAndFunctions.Syntax). **Example** 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 mayor que el número especificado `Views`. ``` aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :fn and Subject begins_with :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](ReservedWords.md)), 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 (Alias) en DynamoDB](Expressions.ExpressionAttributeNames.md). **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. # Paginación de los resultados de consulta de tabla en DynamoDB 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. 1. Construya una `Query` con la misma `KeyConditionExpression`. Sin embargo, esta vez, se toma el valor `LastEvaluatedKey` del paso 1 y se usa como parámetro `ExclusiveStartKey` en la nueva solicitud `Query`. 1. Ejecutar la nueva solicitud `Query`. 1. 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 AWS 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 AWS CLI de la `--page-size` 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 inicio de Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/gettingstartedguide/) y la documentación del SDK de AWS correspondiente a su lenguaje. También puede reducir el tamaño de página limitando el número de elementos del conjunto de resultados, con el parámetro de `Limit` de la operación de `Query`. Para obtener más información sobre cómo realizar consultas en DynamoDB, consulte [Consulta de tablas en DynamoDB](Query.md). # Otros aspectos del trabajo con la operación Query en DynamoDB En esta sección se tratan aspectos adicionales de la operación Query de DynamoDB, como la limitación del tamaño del resultado, el recuento de elementos analizados frente a los devueltos, la supervisión del consumo de capacidad de lectura y el control de la coherencia de lectura. ## Limitación del número de elementos del conjunto de resultados Con la operación `Query`, puede limitar el número de elementos que lee. 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 lee hasta seis elementos y, a continuación, devuelve solo aquellos que coinciden con la expresión de filtro. El resultado final de `Query` contiene seis elementos o menos, aunque más elementos hubieran coincidido con la expresión de filtro si DynamoDB hubiera seguido leyendo más elementos. ## Recuento de los elementos en 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 de consulta de tabla en DynamoDB](Query.Pagination.md)). 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 consumidas por la consulta Puede utilizar cualquier tabla o índice secundario `Query`, siempre que proporcione el nombre del atributo de clave de partición y un valor único para ese atributo. `Query` devuelve todos los elementos que contienen ese valor de clave de partición. Opcionalmente, puede proporcionar un atributo de clave de clasificación y utilizar un operador de comparación para limitar los resultados de la búsqueda. `Query` Las operaciones de la API 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. | | Índice secundario global | 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 número de elementos y el tamaño de dichos elementos, no según la cantidad de datos que se devuelven a una 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 es el mismo tanto si se utiliza una expresión de filtro como si no. `Query`consume una unidad de capacidad de lectura mínima para realizar una lectura altamente coherente por segundo o dos lecturas coherentes posteriores por segundo para un elemento de hasta 4 KB. Para leer un elemento mayor que 4 KB, DynamoDB necesita unidades de solicitud de lectura adicionales. Con las tablas vacías y las tablas muy grandes con una cantidad escasa de claves de partición, es posible que se cobren algunas RCU adicionales además de la cantidad de datos consultados. Esto cubre el costo de atender la solicitud `Query`, incluso si no hay datos. ## Coherencia de lectura para la consulta 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 [Coherencia de lectura de DynamoDB](HowItWorks.ReadConsistency.md). Si requiere lecturas de consistencia alta, establezca el parámetro `ConsistentRead` en `true` en la solicitud `Query`.