query ( $opt )

Gets the values of one or more items and its attributes by primary key (composite primary key, only).

Narrow the scope of the query using comparison operators on the RangeKeyValue of the composite key. Use the ScanIndexForward parameter to get results in forward or reverse order by range key.

Access

public

Parameters

Parameter

Type

Required

Description

$opt

array

Optional

An associative array of parameters that can have the following keys:

  • TableName - string - Required - The name of the table in which you want to query. Allowed characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and . (period). [Constraints: The value must be between 3 and 255 characters, and must match the following regular expression pattern: [a-zA-Z0-9_.-]+]
  • AttributesToGet - string|array - Optional - List of Attribute names. If attribute names are not specified then all attributes will be returned. If some attributes are not found, they will not appear in the result. Pass a string for a single value, or an indexed array for multiple values.
  • Limit - integer - Optional - The maximum number of items to return. If Amazon DynamoDB hits this limit while querying the table, it stops the query and returns the matching values up to the limit, and a LastEvaluatedKey to apply in a subsequent operation to continue the query. Also, if the result set size exceeds 1MB before Amazon DynamoDB hits this limit, it stops the query and returns the matching values, and a LastEvaluatedKey to apply in a subsequent operation to continue the query.
  • ConsistentRead - boolean - Optional - If set to true, then a consistent read is issued. Otherwise eventually-consistent is used.
  • Count - boolean - Optional - If set to true, Amazon DynamoDB returns a total number of items that match the query parameters, instead of a list of the matching items and their attributes. Do not set Count to true while providing a list of AttributesToGet, otherwise Amazon DynamoDB returns a validation error.
  • HashKeyValue - array - Required - Attribute value of the hash component of the composite primary key.
    • S - string - Optional - Strings are Unicode with UTF-8 binary encoding. The maximum size is limited by the size of the primary key (1024 bytes as a range part of a key or 2048 bytes as a single part hash key) or the item size (64k).
    • N - string - Optional - Numbers are positive or negative exact-value decimals and integers. A number can have up to 38 digits precision and can be between 10^-128 to 10^+126.
    • B - blob - Optional - Binary attributes are sequences of unsigned bytes.
    • SS - string|array - Optional - A set of strings. Pass a string for a single value, or an indexed array for multiple values.
    • NS - string|array - Optional - A set of numbers. Pass a string for a single value, or an indexed array for multiple values.
    • BS - blob - Optional - A set of binary attributes.
  • RangeKeyCondition - array - Optional - A container for the attribute values and comparison operators to use for the query.
    • AttributeValueList - array - Optional - A list of attribute values to be used with a comparison operator for a scan or query operation. For comparisons that require more than one value, such as a BETWEEN comparison, the AttributeValueList contains two attribute values and the comparison operator.
      • x - array - Optional - This represents a simple array index.
        • S - string - Optional - Strings are Unicode with UTF-8 binary encoding. The maximum size is limited by the size of the primary key (1024 bytes as a range part of a key or 2048 bytes as a single part hash key) or the item size (64k).
        • N - string - Optional - Numbers are positive or negative exact-value decimals and integers. A number can have up to 38 digits precision and can be between 10^-128 to 10^+126.
        • B - blob - Optional - Binary attributes are sequences of unsigned bytes.
        • SS - string|array - Optional - A set of strings. Pass a string for a single value, or an indexed array for multiple values.
        • NS - string|array - Optional - A set of numbers. Pass a string for a single value, or an indexed array for multiple values.
        • BS - blob - Optional - A set of binary attributes.
    • ComparisonOperator - string - Required - A comparison operator is an enumeration of several operations:
      • EQ for equal.
      • NE for not equal.
      • IN checks for exact matches.
      • LE for less than or equal to.
      • LT for less than.
      • GE for greater than or equal to.
      • GT for greater than.
      • BETWEEN for between.
      • NOT_NULL for exists.
      • NULL for not exists.
      • CONTAINS for substring or value in a set.
      • NOT_CONTAINS for absence of a substring or absence of a value in a set.
      • BEGINS_WITH for a substring prefix.
      Scan operations support all available comparison operators. Query operations support a subset of the available comparison operators: EQ, LE, LT, GE, GT, BETWEEN, and BEGINS_WITH. [Allowed values: EQ, NE, IN, LE, LT, GE, GT, BETWEEN, NOT_NULL, NULL, CONTAINS, NOT_CONTAINS, BEGINS_WITH]
  • ScanIndexForward - boolean - Optional - Specifies forward or backward traversal of the index. Amazon DynamoDB returns results reflecting the requested order, determined by the range key. The default value is true (forward).
  • ExclusiveStartKey - array - Optional - Primary key of the item from which to continue an earlier query. An earlier query might provide this value as the LastEvaluatedKey if that query operation was interrupted before completing the query; either because of the result set size or the Limit parameter. The LastEvaluatedKey can be passed back in a new query request to continue the operation from that point.
    • HashKeyElement - array - Required - A hash key element is treated as the primary key, and can be a string or a number. Single attribute primary keys have one index value. The value can be String, Number, StringSet, NumberSet.
      • S - string - Optional - Strings are Unicode with UTF-8 binary encoding. The maximum size is limited by the size of the primary key (1024 bytes as a range part of a key or 2048 bytes as a single part hash key) or the item size (64k).
      • N - string - Optional - Numbers are positive or negative exact-value decimals and integers. A number can have up to 38 digits precision and can be between 10^-128 to 10^+126.
      • B - blob - Optional - Binary attributes are sequences of unsigned bytes.
      • SS - string|array - Optional - A set of strings. Pass a string for a single value, or an indexed array for multiple values.
      • NS - string|array - Optional - A set of numbers. Pass a string for a single value, or an indexed array for multiple values.
      • BS - blob - Optional - A set of binary attributes.
    • RangeKeyElement - array - Optional - A range key element is treated as a secondary key (used in conjunction with the primary key), and can be a string or a number, and is only used for hash-and-range primary keys. The value can be String, Number, StringSet, NumberSet.
      • S - string - Optional - Strings are Unicode with UTF-8 binary encoding. The maximum size is limited by the size of the primary key (1024 bytes as a range part of a key or 2048 bytes as a single part hash key) or the item size (64k).
      • N - string - Optional - Numbers are positive or negative exact-value decimals and integers. A number can have up to 38 digits precision and can be between 10^-128 to 10^+126.
      • B - blob - Optional - Binary attributes are sequences of unsigned bytes.
      • SS - string|array - Optional - A set of strings. Pass a string for a single value, or an indexed array for multiple values.
      • NS - string|array - Optional - A set of numbers. Pass a string for a single value, or an indexed array for multiple values.
      • BS - blob - Optional - A set of binary attributes.
  • curlopts - array - Optional - A set of values to pass directly into curl_setopt(), where the key is a pre-defined CURLOPT_* constant.
  • returnCurlHandle - boolean - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.

Returns

Type

Description

CFResponse

A CFResponse object containing a parsed HTTP response.

Examples

Scan the database for information.

Examples for Scan.

// Instantiate the class
$dynamodb = new AmazonDynamoDB();

$table_name = 'my-table' . time();

####################################################################
# Create a new DynamoDB table

$response = $dynamodb->create_table(array(
	'TableName' => $table_name,
	'KeySchema' => array(
		'HashKeyElement' => array(
			'AttributeName' => 'id',
			'AttributeType' => AmazonDynamoDB::TYPE_NUMBER,
		),
		'RangeKeyElement' => array(
			'AttributeName' => 'date',
			'AttributeType' => AmazonDynamoDB::TYPE_NUMBER,
		),
	),
	'ProvisionedThroughput' => array(
		'ReadCapacityUnits' => 10,
		'WriteCapacityUnits' => 5,
	),
));

var_dump($response->isOK());

if (!$response->isOK())
{
	die('Table creation failed.');
}

// Sleep and poll during table creation
do
{
	sleep(1);

	$response = $dynamodb->describe_table(array(
		'TableName' => $table_name
	));
}
while ((string) $response->body->Table->TableStatus !== 'ACTIVE');

####################################################################
# Add data to the table

// Add items to the batch
$response = $dynamodb->batch_write_item(array(
	'RequestItems' => array(
		$table_name => array(
			array(
				'PutRequest' => array(
					'Item' => $dynamodb->attributes(array(
						'id'   => 1, // Primary (Hash) Key
						'date' => time(),
						'key1' => 'value1',
						'key2' => 'value2',
						'key3' => array('sub-value1', 'sub-value2'),
					))
				)
			),
			array(
				'PutRequest' => array(
					'Item' => $dynamodb->attributes(array(
						'id'   => 2, // Primary (Hash) Key
						'date' => time(),
						'key1' => 'value3',
						'key2' => 'value4',
						'key3' => array('sub-value1', 'sub-value2'),
					))
				)
			),
			array(
				'PutRequest' => array(
					'Item' => $dynamodb->attributes(array(
						'id'   => 3, // Primary (Hash) Key
						'date' => time(),
						'key1' => 'value5',
						'key2' => 'value6',
						'key3' => array('sub-value1', 'sub-value2'),
					))
				)
			),
		)
	)
));

var_dump($response->isOK());

sleep(1);

####################################################################
# Scan the database

// Scan the database for matches
$response = $dynamodb->scan(array(
	'TableName'       => $table_name,
	'AttributesToGet' => array('id', 'key1', 'key2', 'key3'),
	'ScanFilter'      => array(
		'key1' => array(
			'ComparisonOperator' => AmazonDynamoDB::CONDITION_EQUAL,
			'AttributeValueList' => array(
				array( AmazonDynamoDB::TYPE_STRING => 'value5' )
			)
		),
	)
));

// Did we get back what we expected?
var_dump((integer) $response->body->Items->id->{AmazonDynamoDB::TYPE_NUMBER});

####################################################################
# Query the database

$response = $dynamodb->query(array(
	'TableName'    => $table_name,
	'HashKeyValue' => array(
		AmazonDynamoDB::TYPE_NUMBER => '1'
	),
	'RangeKeyCondition' => array(
		'ComparisonOperator' => AmazonDynamoDB::CONDITION_GREATER_THAN_OR_EQUAL,
		'AttributeValueList' => array(
			array(AmazonDynamoDB::TYPE_NUMBER => '0')
		),
	)
));

// Did we get back what we expected?
var_dump((string) $response->body->Items->key1->{AmazonDynamoDB::TYPE_STRING});

####################################################################
# Deleting the table

$response = $dynamodb->delete_table(array(
	'TableName' => $table_name
));

var_dump($response->isOK());

// Sleep and poll until table is deleted
do
{
	sleep(1);

	$response = $dynamodb->describe_table(array(
		'TableName' => $table_name
	));
}
while ((integer) $response->status !== 400);
Result:
bool(true)
bool(true)
int(3)
string(6) "value1"
bool(true)

Source

Method defined in services/dynamodb.class.php | Toggle source view (12 lines) | View on GitHub

public function query($opt = null)
{
    if (!$opt) $opt = array();
    
    // List (non-map)
    if (isset($opt['AttributesToGet']))
    {
        $opt['AttributesToGet'] = (is_array($opt['AttributesToGet']) ? $opt['AttributesToGet'] : array($opt['AttributesToGet']));
    }

    return $this->authenticate('Query', $opt);
}

Copyright © 2010–2013 Amazon Web Services, LLC


Feedback