# Consultar **importante** ***Esta sección se refiere a la versión 2011-12-05 del API, que está obsoleta y no debe utilizarse para nuevas aplicaciones.*** **Para consultar la documentación sobre la API de bajo nivel actual, consulte la [Referencia de la API de Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).** ## Descripción Una operación `Query` obtiene los valores de uno o varios elementos y sus atributos mediante su clave principal (`Query` solo está disponible para tablas con clave principal compuesta por una clave hash y una clave de rango). Debe proporcionar un `HashKeyValue` específico y puede delimitar el alcance de la consulta mediante operadores de comparación en el `RangeKeyValue` de la clave principal. Utilice el parámetro `ScanIndexForward` para obtener los resultados por orden ascendente o descendente según su clave de rango. Las consultas que no devuelven resultados consumen las unidades de capacidad de lectura mínimas, según el tipo de lectura. **nota** Si la cantidad total de elementos que cumplen los parámetros de la consulta supera el límite de 1 MB, la consulta se detiene y se devuelven los resultados al usuario; en este caso, se facilita un `LastEvaluatedKey` para que pueda continuar la consulta en una operación posterior. A diferencia de una operación de análisis, una operación de consulta nunca devuelve un conjunto de resultados vacío *y* un valor `LastEvaluatedKey`. El valor de `LastEvaluatedKey` solamente se proporciona si los resultados superan 1 MB o si se ha utilizado el parámetro `Limit`. El resultado se puede establecer para una lectura consistente con el parámetro `ConsistentRead`. ## Solicitudes ### Sintaxis ``` // This header is abbreviated. // For a sample of a complete header, see API de bajo nivel de DynamoDB. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Query content-type: application/x-amz-json-1.0 {"TableName":"Table1", "Limit":2, "ConsistentRead":true, "HashKeyValue":{"S":"AttributeValue1":}, "RangeKeyCondition": {"AttributeValueList":[{"N":"AttributeValue2"}],"ComparisonOperator":"GT"} "ScanIndexForward":true, "ExclusiveStartKey":{ "HashKeyElement":{"S":"AttributeName1"}, "RangeKeyElement":{"N":"AttributeName2"} }, "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]}, } ``` **** | Nombre | Descripción | Obligatorio | | --- | --- | --- | | TableName | Nombre de la tabla que contiene los elementos solicitados. Tipo: cadena | Sí | | AttributesToGet | Matriz de nombres de atributo. Si no se especifican sus nombres, se devuelven todos los atributos. Si algún atributo no se encuentra, no aparecerá en los resultados.Tipo: matriz | No | | Limit | Cantidad máxima de elementos que se devolverán, que no es necesariamente el número de elementos coincidentes. Si DynamoDB alcanza el límite de la cantidad de elementos mientras consulta la tabla, detiene la consulta y devuelve los valores coincidentes hasta ese punto, junto con un `LastEvaluatedKey`, que puede aplicarse en una operación ulterior para continuar con la consulta. Además, si el tamaño del conjunto de resultados supera 1 MB antes de que DynamoDB alcance este límite, detiene la consulta y devuelve los valores coincidentes, junto con el `LastEvaluatedKey`, que puede aplicarse en una operación ulterior para continuar con la consulta.Tipo: Number | No | | ConsistentRead | Si se establece en `true`, se emite una lectura consistente; en caso contrario, se utiliza una lectura consistente final.Tipo: Booleano | No | | Count | Si se establece en `true`, DynamoDB devuelve la cantidad total de elementos que coinciden con los parámetros de la consulta, en lugar de una lista de elementos coincidentes y sus atributos. Puede aplicar el parámetro `Limit` a las consultas que son solo de recuento. No establezca `Count` en `true` si proporciona una lista de `AttributesToGet`; si así lo hiciera, DynamoDB devolverá un error de validación. Para obtener más información, consulte [Recuento de los elementos en los resultados](Query.Other.md#Query.Count).Tipo: Booleano | No | | HashKeyValue | Valor de atributo del componente hash de la clave principal compuesta.Tipo: String, Number o Binary | Sí | | RangeKeyCondition | Contenedor de los valores de los atributos y operadores de comparación que se usarán en la consulta. Una solicitud de consulta no requiere una condición `RangeKeyCondition`. Si se proporciona solo el `HashKeyValue`, DynamoDB devuelve todos los elementos que tienen el valor especificado de clave hash.Tipo: mapa | No | | RangeKeyCondition:​ AttributeValueList | Valores de los atributos que se van a evaluar para los parámetros de la consulta. La `AttributeValueList` contiene un solo valor de atributo, a no ser que se especifique una comparación `BETWEEN`. Para la comparación `BETWEEN`, la lista `AttributeValueList` contiene dos valores de atributos. Tipo: Map, mapa de `AttributeValue` a un `ComparisonOperator`. | No | | RangeKeyCondition:​ ComparisonOperator | Criterios para evaluar los atributos proporcionados, tales como igual que, mayor que, etc. A continuación se muestran los operadores de comparación válidos para una operación Query. Las comparaciones de valores de cadenas de tipo mayor que, igual que o menor que se basan en sus valores según el código de caracteres ASCII. Por ejemplo, `a` es mayor que `A` y `aa` es mayor que `B`. Para obtener una lista de valores de códigos, consulte [http://en.wikipedia.org/wiki/ASCII\$1ASCII\$1printable\$1characters](http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters). En el tipo Binary, al comparar valores binarios DynamoDB trata cada byte como datos sin signo; por ejemplo, al evaluar expresiones de consulta. Tipo: String o Binary | No | |   | `EQ`: igual que. Para `EQ`, `AttributeValueList` puede contener un solo `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). Si un elemento contiene un `AttributeValue` de un tipo distinto del especificado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco es igual que `{"NS":["6", "2", "1"]}`. |   | |   | `LE`: menor o igual que. Para `LE`, `AttributeValueList` puede contener un solo `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). Si un elemento contiene un `AttributeValue` de un tipo distinto del especificado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`. |   | |   | `LT` : Menor que. Para `LT`, `AttributeValueList` puede contener un solo `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). Si un elemento contiene un `AttributeValue` de un tipo distinto del especificado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`. |   | |   | `GE`: mayor o igual que. Para `GE`, `AttributeValueList` puede contener un solo `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). Si un elemento contiene un `AttributeValue` de un tipo distinto del especificado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`. |   | |   | `GT` : Mayor que. Para `GT`, `AttributeValueList` puede contener un solo `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). Si un elemento contiene un `AttributeValue` de un tipo distinto del especificado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`. |   | |   | `BEGINS_WITH`: comprueba si hay un prefijo. Para `BEGINS_WITH`, `AttributeValueList` puede contener un solo `AttributeValue` de tipo String (cadena) o Binary (binario) (no de tipo Number [número] ni un conjunto). El atributo de destino de la comparación debe ser un valor de tipo String o Binary (no de tipo Number ni un conjunto). |   | |   | `BETWEEN`: mayor o igual que el primer valor y menor o igual que el segundo valor. Para `BETWEEN`, `AttributeValueList` debe contener dos elemento `AttributeValue` del mismo tipo, que puede ser String (cadena), Number (número) o Binary (binario) (pero no un conjunto). Un atributo de destino coincide si el valor de destino es mayor o igual que el primer elemento y menor o igual que el segundo elemento. Si un elemento contiene un `AttributeValue` de un tipo distinto del especificado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no se compara con `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`. |   | | ScanIndexForward | Especifica si el índice se recorrerá en sentido ascendente o descendente. DynamoDB devuelve los resultados según el orden solicitado en función de la clave de rango: si el tipo de datos es Number (número), los resultados se devuelven en orden numérico; de lo contrario, el recorrido se basa en los valores del código de caracteres ASCII.Tipo: BooleanoEl valor predeterminado es `true` (ascendente). | No | | ExclusiveStartKey | Clave principal del elemento a partir del cual se continuará una consulta anterior. Una consulta anterior puede proporcionar este valor en `LastEvaluatedKey` si esa operación se interrumpió antes de completar la consulta, ya sea debido al tamaño del conjunto de resultados o al parámetro `Limit`. El valor de `LastEvaluatedKey` se puede pasar a una nueva solicitud de consulta para continuar la operación a partir de ese punto.Tipo: `HashKeyElement`, o bien `HashKeyElement` y `RangeKeyElement` si se trata de una clave principal compuesta. | No | ## Respuestas ### Sintaxis ``` HTTP/1.1 200 x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 content-type: application/x-amz-json-1.0 content-length: 308 {"Count":2,"Items":[{ "AttributeName1":{"S":"AttributeValue1"}, "AttributeName2":{"N":"AttributeValue2"}, "AttributeName3":{"S":"AttributeValue3"} },{ "AttributeName1":{"S":"AttributeValue3"}, "AttributeName2":{"N":"AttributeValue4"}, "AttributeName3":{"S":"AttributeValue3"}, "AttributeName5":{"B":"dmFsdWU="} }], "LastEvaluatedKey":{"HashKeyElement":{"AttributeValue3":"S"}, "RangeKeyElement":{"AttributeValue4":"N"} }, "ConsumedCapacityUnits":1 } ``` **** | Nombre | Descripción | | --- | --- | | Items | Atributos de elementos que cumplen los parámetros de la consulta.Tipo: Map, mapa de los nombres de atributos y sus tipos de datos y valores. | | Count | Cantidad de elementos de la respuesta. Para obtener más información, consulte [Recuento de los elementos en los resultados](Query.Other.md#Query.Count). Tipo: Number | | LastEvaluatedKey | Clave principal del elemento en el que se ha detenido la operación de consulta, incluido el conjunto de resultados anterior. Utilice este valor para iniciar una nueva operación excluyendo este valor en la nueva solicitud.El valor de `LastEvaluatedKey` es `null` cuando se ha completado todo el conjunto de resultados de la consulta (es decir, cuando la operación ha procesado la “última página”). Tipo: `HashKeyElement`, o bien `HashKeyElement` y `RangeKeyElement` si se trata de una clave principal compuesta. | | ConsumedCapacityUnits | Cantidad de unidades de capacidad de lectura consumidas por la operación. Este valor muestra el número aplicado al rendimiento aprovisionado. Para obtener más información, consulte [Modo de capacidad aprovisionada de DynamoDB](provisioned-capacity-mode.md). Tipo: Number | ## Errores especiales **** | Error | Descripción | | --- | --- | | ResourceNotFoundException | No se encontró la tabla especificada. | ## Ejemplos Para obtener ejemplos sobre cómo usar el SDK de AWS, consulte [Consulta de tablas en DynamoDB](Query.md). ### Solicitud de ejemplo ``` // This header is abbreviated. For a sample of a complete header, see API de bajo nivel de DynamoDB. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Query content-type: application/x-amz-json-1.0 {"TableName":"1-hash-rangetable", "Limit":2, "HashKeyValue":{"S":"John"}, "ScanIndexForward":false, "ExclusiveStartKey":{ "HashKeyElement":{"S":"John"}, "RangeKeyElement":{"S":"The Matrix"} } } ``` ### Respuesta de ejemplo ``` HTTP/1.1 200 x-amzn-RequestId: 3647e778-71eb-11e0-a498-71d736f27375 content-type: application/x-amz-json-1.0 content-length: 308 {"Count":2,"Items":[{ "fans":{"SS":["Jody","Jake"]}, "name":{"S":"John"}, "rating":{"S":"***"}, "title":{"S":"The End"} },{ "fans":{"SS":["Jody","Jake"]}, "name":{"S":"John"}, "rating":{"S":"***"}, "title":{"S":"The Beatles"} }], "LastEvaluatedKey":{"HashKeyElement":{"S":"John"},"RangeKeyElement":{"S":"The Beatles"}}, "ConsumedCapacityUnits":1 } ``` ### Solicitud de ejemplo ``` // This header is abbreviated. For a sample of a complete header, see API de bajo nivel de DynamoDB. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Query content-type: application/x-amz-json-1.0 {"TableName":"1-hash-rangetable", "Limit":2, "HashKeyValue":{"S":"Airplane"}, "RangeKeyCondition":{"AttributeValueList":[{"N":"1980"}],"ComparisonOperator":"EQ"}, "ScanIndexForward":false} ``` ### Respuesta de ejemplo ``` HTTP/1.1 200 x-amzn-RequestId: 8b9ee1ad-774c-11e0-9172-d954e38f553a content-type: application/x-amz-json-1.0 content-length: 119 {"Count":1,"Items":[{ "fans":{"SS":["Dave","Aaron"]}, "name":{"S":"Airplane"}, "rating":{"S":"***"}, "year":{"N":"1980"} }], "ConsumedCapacityUnits":1 } ``` ## Acciones relacionadas + [Examen](API_Scan_v20111205.md)