Consultar - Amazon DynamoDB
DescripciónSolicitudesRespuestasErrores especialesEjemplosAcciones relacionadas

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.

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.

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.

nota

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#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: Booleano

El 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.

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.

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.

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
}