Overview¶

A collection provides an iterable interface to a group of resources.Collections behave similarly toDjango QuerySetsand expose a similar API. A collection seamlessly handles pagination foryou, making it possible to easily iterate over all items from all pages ofdata. Example of a collection:

# SQS list all queuessqs=boto3.resource('sqs')forqueueinsqs.queues.all():print(queue.url)

Filtering¶

Some collections support extra arguments to filter the returned data set,which are passed into the underlying service operation. Use thefilter() method to filterthe results:

# S3 list all keys with the prefix 'photos/'s3=boto3.resource('s3')forbucketins3.buckets.all():forobjinbucket.objects.filter(Prefix='photos/'):print('{0}:{1}'.format(bucket.name,obj.key))

Chainability¶

Collection methods are chainable. They return copies of the collectionrather than modifying the collection, including a deep copy of anyassociated operation parameters. For example, this allows youto build up multiple collections from a base which they all havein common:

# EC2 find instancesec2=boto3.resource('ec2')base=ec2.instances.filter(InstanceIds=['id1','id2','id3'])filters=[{'Name':'tenancy','Values':['dedicated']}]filtered1=base.filter(Filters=filters)# Note, this does NOT modify the filters in ``filtered1``!filters.append({'name':'instance-type','value':'t1.micro'})filtered2=base.filter(Filters=filters)print('All instances:')forinstanceinbase:print(instance.id)print('Dedicated instances:')forinstanceinfiltered1:print(instance.id)print('Dedicated micro instances:')forinstanceinfiltered2:print(instance.id)

Limiting results¶

It is possible to limit the number of items returned from a collectionby using either thelimit() method:

# S3 iterate over first ten bucketsforbucketins3.buckets.limit(10):print(bucket.name)

In both cases, up to 10 items total will be returned. If you do nothave 10 buckets, then all of your buckets will be returned.

Controlling page size¶

Collections automatically handle paging through results, but you may wantto control the number of items returned from a single service operationcall. You can do so using thepage_size() method:

# S3 iterate over all objects 100 at a timeforobjinbucket.objects.page_size(100):print(obj.key)

By default, S3 will return 1000 objects at a time, so the above codewould let you process the items in smaller batches, which could bebeneficial for slow or unreliable internet connections.

Batch actions¶

Some collections support batch actions, which are actions that operateon an entire page of results at a time. They will automatically handlepagination:

# S3 delete everything in `amzn-s3-demo-bucket`s3=boto3.resource('s3')s3.Bucket('amzn-s3-demo-bucket').objects.delete()