Introduction to Amazon SQS

SQS makes a best effort to preserve order in messages, but due to the distributed nature of the queue, we cannot guarantee you will receive messages in the exact order you sent them. If your system requires that order be preserved, we recommend you place sequencing information in each message so you can reorder the messages upon receipt.

SQS stores copies of your messages on multiple servers for redundancy and high availability. On rare occasions, one of the servers storing a copy of a message might be unavailable when you receive or delete the message. If that occurs, the copy of the message will not be deleted on that unavailable server, and you might get that message copy again when you receive messages. Because of this, you must design your application to be idempotent (i.e., it must not be adversely affected if it processes the same message more than once).

When you retrieve messages from the queue, SQS samples a subset of the servers (based on a weighted random distribution) and returns messages from just those servers. This means that a particular receive request might not return all your messages. Or, if you have a small number of messages in your queue (less than 1000), it means a particular request might not return any of your messages, whereas a subsequent request will. If you keep retrieving from your queues, SQS will sample all of the servers, and you will receive all of your messages.

The following figure shows messages being returned after one of your system components makes a receive request. SQS samples several of the servers (in gray) and returns the messages from those servers (Message A, C, D, and B). Message E is not returned to this particular request, but it would be returned to a subsequent request.

When creating a new queue, you must provide a queue name that is unique within the scope of all your queues. If you create queues using both the 2008-01-01 WSDL and a previous version, you still have a single namespace for all your queues. SQS assigns each queue you create an identifier called a queue URL, which includes the queue name and other components that SQS determines. Whenever you want to perform an action on a queue, you provide its queue URL.

The following is the queue URL for a queue named "queue2" owned by a person with the AWS account number "123456789012".

http://sqs.us-east-1.amazonaws.com/123456789012/queue2

	Important
	In your system, always store the entire queue URL as Amazon SQS returned it to you when you created the queue (for example, http://sqs.us-east-1.amazonaws.com/123456789012/queue2). Don't build the queue URL from its separate components each time you need to specify the queue URL in a request because Amazon SQS could change the components that make up the queue URL.

You can also get the queue URL for a queue by listing your queues. Even though you have a single namespace for all your queues, the list of queues returned depends on the WSDL you use for the request. For more information, see ListQueues.

In versions of Amazon SQS prior to 2009-02-01, each message received a system-assigned identifier that you needed in order to delete the message from the queue. SQS still returns this message ID to you in the SendMessage response, but you can no longer use the message ID to delete the message. Instead you need a receipt handle.

Each time you receive a message from a queue, you receive a receipt handle for that message. The handle is associated with the act of receiving the message, not with the message itself. To delete the message or to change the message visibility, you must provide the receipt handle and not the message ID. This means you must always receive a message before you can delete it (you can't put a message into the queue and then recall it).

	Important
	If you receive a message more than once, each time you receive it, you get a different receipt handle. You must provide the most recently received receipt handle when you request to delete the message or the message might not be deleted.

Following is an example of a receipt handle.

MbZj6wDWli+JvwwJaBV+3dcjk2YW2vA3+STFFljTM8tJJg6HRG6PYSasuWXPJB+Cw
Lj1FjgXUv1uSj1gUPAWV66FU/WeR4mq2OKpEGYWbnLmpRCJVAyeMjeU5ZBdtcQ+QE
auMZc8ZRv37sIW2iJKq3M9MFx1YvV11A2x/KSbkJ0=

The visibility timeout clock starts ticking once Amazon SQS returns the message. During that time, the component processes and deletes the message. But what happens if the component fails before deleting the message? If your system doesn't call DeleteMessage for that message before the visibility timeout expires, the message again becomes visible to the ReceiveMessage calls placed by the components in your system and it will be received again. If a message should only be received once, your system should delete it within the duration of the visibility timeout.

Each queue starts with a default setting of 30 seconds for the visibility timeout. You can change that setting for the entire queue. Typically, you'll set the visibility timeout to the average time it takes to process and delete a message from the queue. When receiving messages, you can also set a special visibility timeout for the returned messages without changing the overall queue timeout.

We recommend that if you have a system that produces messages that require varying amounts of time to process and delete, you create multiple queues, each with a different visibility timeout setting. Your system can then send all messages to a single queue that forwards each message to another queue with the appropriate visibility timeout based on the expected processing and deletion time for that message.

When you receive a message from the queue, you might find the visibility timeout for the queue is insufficient to fully process and delete that message. Amazon SQS allows you to extend the visibility timeout for that particular message. When you extend the visibility timeout, Amazon SQS overwrites the original timeout value and the new value begins at the time you changed it.

For example, let's say the timeout for the queue is 30 seconds, and you receive a message. Once you're 20 seconds into the timeout for that message (i.e., you have 10 seconds left), you extend it by 60 seconds by calling ChangeMessageVisibility with VisibilityTimeoutset to 60 seconds. You have then changed the remaining visibility timeout from 10 seconds to 60 seconds.

The extension you request is not stored in memory for that message. If for some reason you don't delete the message and the message is received again, the visibility timeout for the message the next time it's received is the overall value for the queue and not the extended value you previously set.

When you receive a message from the queue, you might find that you actually don't want to process and delete that message. Amazon SQS allows you to terminate the visibility timeout for a specific message, which immediately makes the message visible to other components in the system to process. To do this, you call ChangeMessageVisibility with VisibilityTimeout=0 seconds.

The following table lists the API actions to use to manipulate the visibility timeout.