SDB Reference — boto v2.27.0

### Navigation

- index
- modules |
- next |
- previous |
- boto v2.27.0 »

# SDB Reference

In addition to what is seen below, boto includes an abstraction layer for SimpleDB that may be used:

- SimpleDB DB (Maintained, but little documentation)

## boto.sdb

`boto.sdb.` `connect_to_region`(region_name, **kw_params)

  Given a valid region name, return a `boto.sdb.connection.SDBConnection`.

  Type : | str
  Parameters: | region_name – The name of the region to connect to.
  Return type: | `boto.sdb.connection.SDBConnection` or `None`
  Returns: | A connection to the given region, or None if an invalid region name is given

`boto.sdb.` `regions`()

  Get all available regions for the SDB service.

  Return type: | list
  Returns: | A list of `boto.sdb.regioninfo.RegionInfo` instances

## boto.sdb.connection

class `boto.sdb.connection.` `ItemThread`(name, domain_name, item_names)

  A threaded `Item` retriever utility class. Retrieved `Item` objects are stored in the `items` instance variable after `run()` is called.

  Tip

  The item retrieval will not start until the `run()` method is called.

  Parameters: | name (str) – A thread name. Used for identification. domain_name (str) – The name of a SimpleDB `Domain` item_names (string or list of strings) – The name(s) of the items to retrieve from the specified `Domain`.
  Variables: | items (list) – A list of items retrieved. Starts as empty list.

  `run`()

    Start the threaded retrieval of items. Populates the `items` list with `Item` objects.

class `boto.sdb.connection.` `SDBConnection`(aws_access_key_id=None, aws_secret_access_key=None, is_secure=True, port=None, proxy=None, proxy_port=None, proxy_user=None, proxy_pass=None, debug=0, https_connection_factory=None, region=None, path='/', converter=None, security_token=None, validate_certs=True, profile_name=None)

  This class serves as a gateway to your SimpleDB region (defaults to us-east-1). Methods within allow access to SimpleDB `Domain` objects and their associated `Item` objects.

  Tip

  While you may instantiate this class directly, it may be easier to go through `boto.connect_sdb()`.

  For any keywords that aren’t documented, refer to the parent class, `boto.connection.AWSAuthConnection`. You can avoid having to worry about these keyword arguments by instantiating these objects via `boto.connect_sdb()`.

  Parameters: | region (`boto.sdb.regioninfo.SDBRegionInfo`) – Explicitly specify a region. Defaults to `us-east-1` if not specified. You may also specify the region in your `boto.cfg`:
      [SDB]
      region = eu-west-1

  `APIVersion` = '2009-04-15'
  `DefaultRegionEndpoint` = 'sdb.us-east-1.amazonaws.com'
  `DefaultRegionName` = 'us-east-1'
  `ResponseError`

    alias of `SDBResponseError`

  `batch_delete_attributes`(domain_or_name, items)

    Delete multiple items in a domain.

    Parameters: | domain_or_name (string or `boto.sdb.domain.Domain` object.) – Either the name of a domain or a Domain object items (dict or dict-like object) – A dictionary-like object. The keys of the dictionary are the item names and the values are either: dictionaries of attribute names/values, exactly the same as the attribute_names parameter of the scalar put_attributes call. The attribute name/value pairs will only be deleted if they match the name/value pairs passed in. None which means that all attributes associated with the item should be deleted.
    Returns: | True if successful

  `batch_put_attributes`(domain_or_name, items, replace=True)

    Store attributes for multiple items in a domain.

    Parameters: | domain_or_name (string or `boto.sdb.domain.Domain` object.) – Either the name of a domain or a Domain object items (dict or dict-like object) – A dictionary-like object. The keys of the dictionary are the item names and the values are themselves dictionaries of attribute names/values, exactly the same as the attribute_names parameter of the scalar put_attributes call. replace (bool) – Whether the attribute values passed in will replace existing values or will be added as addition values. Defaults to True.
    Return type: | bool
    Returns: | True if successful

  `create_domain`(domain_name)

    Create a SimpleDB domain.

    Parameters: | domain_name (string) – The name of the new domain
    Return type: | `boto.sdb.domain.Domain` object
    Returns: | The newly created domain

  `delete_attributes`(domain_or_name, item_name, attr_names=None, expected_value=None)

    Delete attributes from a given item in a domain.

    Parameters: | domain_or_name (string or `boto.sdb.domain.Domain` object.) – Either the name of a domain or a Domain object item_name (string) – The name of the item whose attributes are being deleted. attributes (dict, list or `boto.sdb.item.Item`) – Either a list containing attribute names which will cause all values associated with that attribute name to be deleted or a dict or Item containing the attribute names and keys and list of values to delete as the value. If no value is supplied, all attribute name/values for the item will be deleted. expected_value (list) – If supplied, this is a list or tuple consisting of a single attribute name and expected value. The list can be of the form: [‘name’, ‘value’] In which case the call will first verify that the attribute “name” of this item has a value of “value”. If it does, the delete will proceed, otherwise a ConditionalCheckFailed error will be returned. The list can also be of the form: [‘name’, True|False] which will simply check for the existence (True) or non-existence (False) of the attribute.
    Return type: | bool
    Returns: | True if successful

  `delete_domain`(domain_or_name)

    Delete a SimpleDB domain.

    Caution

    This will delete the domain and all items within the domain.

    Parameters: | domain_or_name (string or `boto.sdb.domain.Domain` object.) – Either the name of a domain or a Domain object
    Return type: | bool
    Returns: | True if successful

  `domain_metadata`(domain_or_name)

    Get the Metadata for a SimpleDB domain.

    Parameters: | domain_or_name (string or `boto.sdb.domain.Domain` object.) – Either the name of a domain or a Domain object
    Return type: | `boto.sdb.domain.DomainMetaData` object
    Returns: | The newly created domain metadata object

  `get_all_domains`(max_domains=None, next_token=None)

    Returns a `boto.resultset.ResultSet` containing all `boto.sdb.domain.Domain` objects associated with this connection’s Access Key ID.

    Parameters: | max_domains (int) – Limit the returned `ResultSet` to the specified number of members. next_token (str) – A token string that was returned in an earlier call to this method as the `next_token` attribute on the returned `ResultSet` object. This attribute is set if there are more than Domains than the value specified in the `max_domains` keyword. Pass the `next_token` value from you earlier query in this keyword to get the next ‘page’ of domains.

  `get_attributes`(domain_or_name, item_name, attribute_names=None, consistent_read=False, item=None)

    Retrieve attributes for a given item in a domain.

    Parameters: | domain_or_name (string or `boto.sdb.domain.Domain` object.) – Either the name of a domain or a Domain object item_name (string) – The name of the item whose attributes are being retrieved. attribute_names (string or list of strings) – An attribute name or list of attribute names. This parameter is optional. If not supplied, all attributes will be retrieved for the item. consistent_read (bool) – When set to true, ensures that the most recent data is returned. item (`boto.sdb.item.Item`) – Instead of instantiating a new Item object, you may specify one to update.
    Return type: | `boto.sdb.item.Item`
    Returns: | An Item with the requested attribute name/values set on it

  `get_domain`(domain_name, validate=True)

    Retrieves a `boto.sdb.domain.Domain` object whose name matches `domain_name`.

    Parameters: | domain_name (str) – The name of the domain to retrieve validate (bool) – When `True`, check to see if the domain actually exists. If `False`, blindly return a `Domain` object with the specified name set.
    Raises : | `boto.exception.SDBResponseError` if `validate` is `True` and no match could be found.
    Return type: | `boto.sdb.domain.Domain`
    Returns: | The requested domain

  `get_domain_and_name`(domain_or_name)

    Given a `str` or `boto.sdb.domain.Domain`, return a `tuple` with the following members (in order):

    > - In instance of `boto.sdb.domain.Domain` for the requested domain
    > - The domain’s name as a `str`

    Parameters: | domain_or_name (`str` or `boto.sdb.domain.Domain`) – The domain or domain name to get the domain and name for.
    Raises : | `boto.exception.SDBResponseError` when an invalid domain name is specified.
    Return type: | tuple
    Returns: | A `tuple` with contents outlined as per above.

  `get_usage`()

    Returns the BoxUsage (in USD) accumulated on this specific SDBConnection instance.

    Tip

    This can be out of date, and should only be treated as a rough estimate. Also note that this estimate only applies to the requests made on this specific connection instance. It is by no means an account-wide estimate.

    Return type: | float
    Returns: | The accumulated BoxUsage of all requests made on the connection.

  `lookup`(domain_name, validate=True)

    Lookup an existing SimpleDB domain. This differs from `get_domain()` in that `None` is returned if `validate` is `True` and no match was found (instead of raising an exception).

    Parameters: | domain_name (str) – The name of the domain to retrieve validate (bool) – If `True`, a `None` value will be returned if the specified domain can’t be found. If `False`, a `Domain` object will be dumbly returned, regardless of whether it actually exists.
    Return type: | `boto.sdb.domain.Domain` object or `None`
    Returns: | The Domain object or `None` if the domain does not exist.

  `print_usage`()

    Print the BoxUsage and approximate costs of all requests made on this specific SDBConnection instance.

    Tip

    This can be out of date, and should only be treated as a rough estimate. Also note that this estimate only applies to the requests made on this specific connection instance. It is by no means an account-wide estimate.

  `put_attributes`(domain_or_name, item_name, attributes, replace=True, expected_value=None)

    Store attributes for a given item in a domain.

    Parameters: | domain_or_name (string or `boto.sdb.domain.Domain` object.) – Either the name of a domain or a Domain object item_name (string) – The name of the item whose attributes are being stored. attribute_names (dict or dict-like object) – The name/value pairs to store as attributes expected_value (list) – If supplied, this is a list or tuple consisting of a single attribute name and expected value. The list can be of the form: [‘name’, ‘value’] In which case the call will first verify that the attribute “name” of this item has a value of “value”. If it does, the delete will proceed, otherwise a ConditionalCheckFailed error will be returned. The list can also be of the form: [‘name’, True|False] which will simply check for the existence (True) or non-existence (False) of the attribute. replace (bool) – Whether the attribute values passed in will replace existing values or will be added as addition values. Defaults to True.
    Return type: | bool
    Returns: | True if successful

  `select`(domain_or_name, query='', next_token=None, consistent_read=False)

    Returns a set of Attributes for item names within domain_name that match the query. The query must be expressed in using the SELECT style syntax rather than the original SimpleDB query language. Even though the select request does not require a domain object, a domain object must be passed into this method so the Item objects returned can point to the appropriate domain.

    Parameters: | domain_or_name (string or `boto.sdb.domain.Domain` object) – Either the name of a domain or a Domain object query (string) – The SimpleDB query to be performed. consistent_read (bool) – When set to true, ensures that the most recent data is returned.
    Return type: | ResultSet
    Returns: | An iterator containing the results.

  `set_item_cls`(cls)

    While the default item class is `boto.sdb.item.Item`, this default may be overridden. Use this method to change a connection’s item class.

    Parameters: | cls (object) – The new class to set as this connection’s item class. See the default item class for inspiration as to what your replacement should/could look like.

## boto.sdb.domain

Represents an SDB Domain

class `boto.sdb.domain.` `Domain`(connection=None, name=None)
  `batch_delete_attributes`(items)

    Delete multiple items in this domain.

    Parameters: | items (dict or dict-like object) – A dictionary-like object. The keys of the dictionary are the item names and the values are either: dictionaries of attribute names/values, exactly the same as the attribute_names parameter of the scalar put_attributes call. The attribute name/value pairs will only be deleted if they match the name/value pairs passed in. None which means that all attributes associated with the item should be deleted.
    Return type: | bool
    Returns: | True if successful

  `batch_put_attributes`(items, replace=True)

    Store attributes for multiple items.

    Parameters: | items (dict or dict-like object) – A dictionary-like object. The keys of the dictionary are the item names and the values are themselves dictionaries of attribute names/values, exactly the same as the attribute_names parameter of the scalar put_attributes call. replace (bool) – Whether the attribute values passed in will replace existing values or will be added as addition values. Defaults to True.
    Return type: | bool
    Returns: | True if successful

  `delete`()

    Delete this domain, and all items under it

  `delete_attributes`(item_name, attributes=None, expected_values=None)

    Delete attributes from a given item.

    Parameters: | item_name (string) – The name of the item whose attributes are being deleted. attributes (dict, list or `boto.sdb.item.Item`) – Either a list containing attribute names which will cause all values associated with that attribute name to be deleted or a dict or Item containing the attribute names and keys and list of values to delete as the value. If no value is supplied, all attribute name/values for the item will be deleted. expected_value (list) – If supplied, this is a list or tuple consisting of a single attribute name and expected value. The list can be of the form: [‘name’, ‘value’] In which case the call will first verify that the attribute “name” of this item has a value of “value”. If it does, the delete will proceed, otherwise a ConditionalCheckFailed error will be returned. The list can also be of the form: [‘name’, True|False] which will simply check for the existence (True) or non-existence (False) of the attribute.
    Return type: | bool
    Returns: | True if successful

  `delete_item`(item)
  `endElement`(name, value, connection)
  `from_xml`(doc)

    Load this domain based on an XML document

  `get_attributes`(item_name, attribute_name=None, consistent_read=False, item=None)

    Retrieve attributes for a given item.

    Parameters: | item_name (string) – The name of the item whose attributes are being retrieved. attribute_names (string or list of strings) – An attribute name or list of attribute names. This parameter is optional. If not supplied, all attributes will be retrieved for the item.
    Return type: | `boto.sdb.item.Item`
    Returns: | An Item mapping type containing the requested attribute name/values

  `get_item`(item_name, consistent_read=False)

    Retrieves an item from the domain, along with all of its attributes.

    Parameters: | item_name (string) – The name of the item to retrieve. consistent_read (bool) – When set to true, ensures that the most recent data is returned.
    Return type: | `boto.sdb.item.Item` or `None`
    Returns: | The requested item, or `None` if there was no match found

  `get_metadata`()
  `new_item`(item_name)
  `put_attributes`(item_name, attributes, replace=True, expected_value=None)

    Store attributes for a given item.

    Parameters: | item_name (string) – The name of the item whose attributes are being stored. attribute_names (dict or dict-like object) – The name/value pairs to store as attributes expected_value (list) – If supplied, this is a list or tuple consisting of a single attribute name and expected value. The list can be of the form: [‘name’, ‘value’] In which case the call will first verify that the attribute “name” of this item has a value of “value”. If it does, the delete will proceed, otherwise a ConditionalCheckFailed error will be returned. The list can also be of the form: [‘name’, True|False] which will simply check for the existence (True) or non-existence (False) of the attribute. replace (bool) – Whether the attribute values passed in will replace existing values or will be added as addition values. Defaults to True.
    Return type: | bool
    Returns: | True if successful

  `select`(query='', next_token=None, consistent_read=False, max_items=None)

    Returns a set of Attributes for item names within domain_name that match the query. The query must be expressed in using the SELECT style syntax rather than the original SimpleDB query language.

    Parameters: | query (string) – The SimpleDB query to be performed.
    Return type: | iter
    Returns: | An iterator containing the results. This is actually a generator function that will iterate across all search results, not just the first page.

  `startElement`(name, attrs, connection)
  `to_xml`(f=None)

    Get this domain as an XML DOM Document :param f: Optional File to dump directly to :type f: File or Stream

    Returns: | File object where the XML has been dumped to
    Return type: | file

class `boto.sdb.domain.` `DomainDumpParser`(domain)

  SAX parser for a domain that has been dumped

  `characters`(ch)
  `endElement`(name)
  `startElement`(name, attrs)

class `boto.sdb.domain.` `DomainMetaData`(domain=None)
  `endElement`(name, value, connection)
  `startElement`(name, attrs, connection)

class `boto.sdb.domain.` `UploaderThread`(domain)

  Uploader Thread

  `run`()

## boto.sdb.item

class `boto.sdb.item.` `Item`(domain, name='', active=False)

  A `dict` sub-class that serves as an object representation of a SimpleDB item. An item in SDB is similar to a row in a relational database. Items belong to a `Domain`, which is similar to a table in a relational database.

  The keys on instances of this object correspond to attributes that are stored on the SDB item.

  Tip

  While it is possible to instantiate this class directly, you may want to use the convenience methods on `boto.sdb.domain.Domain` for that purpose. For example, `boto.sdb.domain.Domain.get_item()`.

  Parameters: | domain (`boto.sdb.domain.Domain`) – The domain that this item belongs to. name (str) – The name of this item. This name will be used when querying for items using methods like `boto.sdb.domain.Domain.get_item()`

  `add_value`(key, value)

    Helps set or add to attributes on this item. If you are adding a new attribute that has yet to be set, it will simply create an attribute named `key` with your given `value` as its value. If you are adding a value to an existing attribute, this method will convert the attribute to a list (if it isn’t already) and append your new value to said list.

    For clarification, consider the following interactive session:

        >>> item = some_domain.get_item('some_item')
        >>> item.has_key('some_attr')
        False
        >>> item.add_value('some_attr', 1)
        >>> item['some_attr']
        1
        >>> item.add_value('some_attr', 2)
        >>> item['some_attr']
        [1, 2]

    Parameters: | key (str) – The attribute to add a value to. value (object) – The value to set or append to the attribute.

  `decode_value`(value)
  `delete`()

    Deletes this item in SDB.

    Note

    This local Python object remains in its current state after deletion, this only deletes the remote item in SDB.

  `endElement`(name, value, connection)
  `load`()

    Loads or re-loads this item’s attributes from SDB.

    Warning

    If you have changed attribute values on an Item instance, this method will over-write the values if they are different in SDB. For any local attributes that don’t yet exist in SDB, they will be safe.

  `save`(replace=True)

    Saves this item to SDB.

    Parameters: | replace (bool) – If `True`, delete any attributes on the remote SDB item that have a `None` value on this object.

  `startElement`(name, attrs, connection)

## boto.sdb.queryresultset

class `boto.sdb.queryresultset.` `QueryResultSet`(domain=None, query='', max_items=None, attr_names=None)

class `boto.sdb.queryresultset.` `SelectResultSet`(domain=None, query='', max_items=None, next_token=None, consistent_read=False)
  `next`()

`boto.sdb.queryresultset.` `query_lister`(domain, query='', max_items=None, attr_names=None)

`boto.sdb.queryresultset.` `select_lister`(domain, query='', max_items=None)

### Navigation

- index
- modules |
- next |
- previous |
- boto v2.27.0 »