aiida.orm.implementation.sqlalchemy package

Submodules

Module for the SqlAlchemy backend implementation of the AuthInfo ORM class.

class aiida.orm.implementation.sqlalchemy.authinfos.SqlaAuthInfo(backend, computer, user)[source]

Bases: aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity, aiida.orm.implementation.authinfos.BackendAuthInfo

SqlAlchemy backend implementation for the AuthInfo ORM class.

MODEL_CLASS

alias of aiida.backends.sqlalchemy.models.authinfo.DbAuthInfo

__abstractmethods__ = frozenset()
__init__(backend, computer, user)[source]

Construct a new instance.

Parameters:
Returns:

an aiida.orm.implementation.authinfos.BackendAuthInfo instance

__module__ = 'aiida.orm.implementation.sqlalchemy.authinfos'
__orig_bases__ = (aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity[aiida.backends.sqlalchemy.models.authinfo.DbAuthInfo], <class 'aiida.orm.implementation.authinfos.BackendAuthInfo'>)
__parameters__ = ()
_abc_impl = <_abc_data object>
computer

Return the computer associated with this instance.

Returns:aiida.orm.implementation.computers.BackendComputer
enabled

Return whether this instance is enabled.

Returns:boolean, True if enabled, False otherwise
get_auth_params()[source]

Return the dictionary of authentication parameters

Returns:a dictionary with authentication parameters
get_metadata()[source]

Return the dictionary of metadata

Returns:a dictionary with metadata
id

Get the id of this entity

Returns:the entity id
is_stored

Return whether the entity is stored.

Returns:True if stored, False otherwise
Return type:bool
set_auth_params(auth_params)[source]

Set the dictionary of authentication parameters

Parameters:auth_params – a dictionary with authentication parameters
set_metadata(metadata)[source]

Set the dictionary of metadata

Parameters:metadata – a dictionary with metadata
user

Return the user associated with this instance.

Returns:aiida.orm.implementation.users.BackendUser
class aiida.orm.implementation.sqlalchemy.authinfos.SqlaAuthInfoCollection(backend)[source]

Bases: aiida.orm.implementation.authinfos.BackendAuthInfoCollection

The collection of SqlAlchemy backend AuthInfo entries.

ENTITY_CLASS

alias of SqlaAuthInfo

__abstractmethods__ = frozenset()
__module__ = 'aiida.orm.implementation.sqlalchemy.authinfos'
__parameters__ = ()
_abc_impl = <_abc_data object>
delete(pk)[source]

Delete an entry from the collection.

Parameters:pk – the pk of the entry to delete
get(computer, user)[source]

Return an entry from the collection that is configured for the given computer and user

Parameters:
Returns:

aiida.orm.implementation.authinfos.BackendAuthInfo

Raises:

SqlAlchemy implementation of aiida.orm.implementation.backends.Backend.

class aiida.orm.implementation.sqlalchemy.backend.SqlaBackend[source]

Bases: aiida.orm.implementation.sql.backends.SqlBackend

SqlAlchemy implementation of aiida.orm.implementation.backends.Backend.

__abstractmethods__ = frozenset()
__init__()[source]

Construct the backend instance by initializing all the collections.

__module__ = 'aiida.orm.implementation.sqlalchemy.backend'
__orig_bases__ = (aiida.orm.implementation.sql.backends.SqlBackend[sqlalchemy.ext.declarative.api.Model],)
__parameters__ = ()
_abc_impl = <_abc_data object>
authinfos

Return the collection of authorisation information objects

Returns:the authinfo collection
Return type:aiida.orm.implementation.BackendAuthInfoCollection
comments

Return the collection of comments

Returns:the comment collection
Return type:aiida.orm.implementation.BackendCommentCollection
computers

Return the collection of computers

Returns:the computers collection
Return type:aiida.orm.implementation.BackendComputerCollection
cursor()[source]

Return a psycopg cursor to be used in a context manager.

Returns:a psycopg cursor
Return type:psycopg2.extensions.cursor
static execute_raw(query)[source]

Execute a raw SQL statement and return the result.

Parameters:query – a string containing a raw SQL statement
Returns:the result of the query
get_backend_entity(model)[source]

Return a BackendEntity instance from a DbModel instance.

static get_connection()[source]

Get the SQLA database connection

Returns:the SQLA database connection
groups

Return the collection of groups

Returns:the groups collection
Return type:aiida.orm.implementation.BackendGroupCollection
logs

Return the collection of logs

Returns:the log collection
Return type:aiida.orm.implementation.BackendLogCollection
static migrate()[source]

Migrate the database to the latest schema version.

nodes

Return the collection of nodes

Returns:the nodes collection
Return type:aiida.orm.implementation.BackendNodeCollection
query()[source]

Return an instance of a query builder implementation for this backend

Returns:a new query builder instance
Return type:aiida.orm.implementation.BackendQueryBuilder
query_manager

Return the query manager for the objects stored in the backend

Returns:The query manger
Return type:aiida.backends.general.abstractqueries.AbstractQueryManager
static transaction()[source]

Open a transaction to be used as a context manager.

users

Return the collection of users

Returns:the users collection
Return type:aiida.orm.implementation.BackendUserCollection

SQLA implementations for the Comment entity and collection.

class aiida.orm.implementation.sqlalchemy.comments.SqlaComment(backend, node, user, content=None, ctime=None, mtime=None)[source]

Bases: aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity, aiida.orm.implementation.comments.BackendComment

Comment implementation for Sqla.

MODEL_CLASS

alias of aiida.backends.sqlalchemy.models.comment.DbComment

__abstractmethods__ = frozenset()
__init__(backend, node, user, content=None, ctime=None, mtime=None)[source]

Construct a SqlaComment.

Parameters:
  • node – a Node instance
  • user – a User instance
  • content – the comment content
  • ctime – The creation time as datetime object
  • mtime – The modification time as datetime object
Returns:

a Comment object associated to the given node and user

__module__ = 'aiida.orm.implementation.sqlalchemy.comments'
__orig_bases__ = (aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity[aiida.backends.sqlalchemy.models.comment.DbComment], <class 'aiida.orm.implementation.comments.BackendComment'>)
__parameters__ = ()
_abc_impl = <_abc_data object>
content
ctime
mtime
node
set_content(value)[source]
set_mtime(value)[source]
set_user(value)[source]
store()[source]

Can only store if both the node and user are stored as well.

user
class aiida.orm.implementation.sqlalchemy.comments.SqlaCommentCollection(backend)[source]

Bases: aiida.orm.implementation.comments.BackendCommentCollection

SqlAlchemy implementation for the CommentCollection.

ENTITY_CLASS

alias of SqlaComment

__abstractmethods__ = frozenset()
__module__ = 'aiida.orm.implementation.sqlalchemy.comments'
__parameters__ = ()
_abc_impl = <_abc_data object>
create(node, user, content=None, **kwargs)[source]

Create a Comment for a given node and user

Parameters:
  • node – a Node instance
  • user – a User instance
  • content – the comment content
Returns:

a Comment object associated to the given node and user

delete(comment_id)[source]

Remove a Comment from the collection with the given id

Parameters:

comment_id (int) – the id of the comment to delete

Raises:
  • TypeError – if comment_id is not an int
  • NotExistent – if Comment with ID comment_id is not found
delete_all()[source]

Delete all Comment entries.

Raises:IntegrityError – if all Comments could not be deleted
delete_many(filters)[source]

Delete Comments based on filters

Parameters:

filters (dict) – similar to QueryBuilder filter

Returns:

(former) PK s of deleted Comments

Return type:

list

Raises:
  • TypeError – if filters is not a dict
  • ValidationError – if filters is empty

SqlAlchemy implementations for the Computer entity and collection.

class aiida.orm.implementation.sqlalchemy.computers.SqlaComputer(backend, **kwargs)[source]

Bases: aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity, aiida.orm.implementation.computers.BackendComputer

SqlAlchemy implementation for BackendComputer.

MODEL_CLASS

alias of aiida.backends.sqlalchemy.models.computer.DbComputer

__abstractmethods__ = frozenset()
__init__(backend, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'aiida.orm.implementation.sqlalchemy.computers'
__orig_bases__ = (aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity[aiida.backends.sqlalchemy.models.computer.DbComputer], <class 'aiida.orm.implementation.computers.BackendComputer'>)
__parameters__ = ()
_abc_impl = <_abc_data object>
copy()[source]

Create an unstored clone of an already stored Computer.

description
get_description()[source]
get_hostname()[source]

Get this computer hostname :rtype: str

get_metadata()[source]
get_name()[source]
get_scheduler_type()[source]
get_transport_type()[source]
hostname
id

Get the id of this entity

Returns:the entity id
is_stored

Is this entity stored?

Returns:True if stored, False otherwise
name
pk

Get the principal key for this entry

Returns:the principal key
set_description(val)[source]
set_hostname(val)[source]

Set the hostname of this computer :param val: The new hostname :type val: str

set_metadata(metadata)[source]

Set the metadata.

set_name(val)[source]
set_scheduler_type(scheduler_type)[source]
set_transport_type(transport_type)[source]
store()[source]

Store the Computer instance.

uuid
class aiida.orm.implementation.sqlalchemy.computers.SqlaComputerCollection(backend)[source]

Bases: aiida.orm.implementation.computers.BackendComputerCollection

Collection of Computer instances.

ENTITY_CLASS

alias of SqlaComputer

__abstractmethods__ = frozenset()
__module__ = 'aiida.orm.implementation.sqlalchemy.computers'
__parameters__ = ()
_abc_impl = <_abc_data object>
delete(pk)[source]

Delete an entry with the given pk

Parameters:pk – the pk of the entry to delete
static list_names()[source]

Module to get the backend instance from the Models instance

aiida.orm.implementation.sqlalchemy.convert.get_backend_entity(dbmodel, backend)[source]

Default get_backend_entity

Classes and methods for Django specific backend entities

class aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity(*args, **kwargs)[source]

Bases: typing.Generic

A mixin that adds some common SQLA backend entity methods

MODEL_CLASS = None
__dict__ = mappingproxy({'__module__': 'aiida.orm.implementation.sqlalchemy.entities', '__doc__': 'A mixin that adds some common SQLA backend entity methods', 'MODEL_CLASS': None, '_dbmodel': None, '_class_check': <classmethod object>, 'from_dbmodel': <classmethod object>, 'get_dbmodel_attribute_name': <classmethod object>, '__init__': <function SqlaModelEntity.__init__>, 'dbmodel': <property object>, 'id': <property object>, 'pk': <property object>, 'is_stored': <property object>, 'store': <function SqlaModelEntity.store>, '__orig_bases__': (typing.Generic[~ModelType],), '__dict__': <attribute '__dict__' of 'SqlaModelEntity' objects>, '__weakref__': <attribute '__weakref__' of 'SqlaModelEntity' objects>, '__parameters__': (~ModelType,)})
__init__(*args, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'aiida.orm.implementation.sqlalchemy.entities'
__orig_bases__ = (typing.Generic[~ModelType],)
__parameters__ = (~ModelType,)
__weakref__

list of weak references to the object (if defined)

classmethod _class_check()[source]

Assert that the class is correctly configured

_dbmodel = None
dbmodel

Get the underlying database model instance

Returns:the database model instance
classmethod from_dbmodel(dbmodel, backend)[source]

Create a DjangoEntity from the corresponding db model class

Parameters:
  • dbmodel – the model to create the entity from
  • backend – the corresponding backend
Returns:

the Django entity

classmethod get_dbmodel_attribute_name(attr_name)[source]

Given the name of an attribute of the entity class give the corresponding name of the attribute in the db model. It if doesn’t exit this raises a ValueError

Parameters:attr_name
Returns:the dbmodel attribute name
Return type:str
id

Get the id of this entity

Returns:the entity id
is_stored

Is this entity stored?

Returns:True if stored, False otherwise
pk

Get the principal key for this entry

Returns:the principal key
store()[source]

Store this entity

Returns:the entity itself

SQLA groups

class aiida.orm.implementation.sqlalchemy.groups.SqlaGroup(backend, label, user, description='', type_string='')[source]

Bases: aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity, aiida.orm.implementation.groups.BackendGroup

The SQLAlchemy Group object

MODEL_CLASS

alias of aiida.backends.sqlalchemy.models.group.DbGroup

__abstractmethods__ = frozenset()
__init__(backend, label, user, description='', type_string='')[source]

Construct a new SQLA group

Parameters:
  • backend – the backend to use
  • label – the group label
  • user – the owner of the group
  • description – an optional group description
  • type_string – an optional type for the group to contain
__int__()[source]

Convert the class to an integer. This is needed to allow querying with Django. Be careful, though, not to pass it to a wrong field! This only returns the local DB principal key (pk) value.

Returns:the integer pk of the node or None if not stored.
__module__ = 'aiida.orm.implementation.sqlalchemy.groups'
__orig_bases__ = (aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity[aiida.backends.sqlalchemy.models.group.DbGroup], <class 'aiida.orm.implementation.groups.BackendGroup'>)
__parameters__ = ()
_abc_impl = <_abc_data object>
add_nodes(nodes, **kwargs)[source]

Add a node or a set of nodes to the group.

Note:

all the nodes and the group itself have to be stored.

Parameters:
  • nodes – a list of BackendNode instance to be added to this group
  • kwargs – skip_orm: When the flag is on, the SQLA ORM is skipped and SQLA is used to create a direct SQL INSERT statement to the group-node relationship table (to improve speed).
clear()[source]

Remove all the nodes from this group.

count()[source]

Return the number of entities in this group.

Returns:integer number of entities contained within the group
description
Returns:the description of the group as a string
is_stored

Is this entity stored?

Returns:True if stored, False otherwise
label
Returns:the name of the group as a string
nodes

Get an iterator to all the nodes in the group

pk

Get the principal key for this entry

Returns:the principal key
remove_nodes(nodes)[source]

Remove a node or a set of nodes from the group.

Note:all the nodes and the group itself have to be stored.
Parameters:nodes – a list of BackendNode instance to be added to this group
store()[source]

Store this entity

Returns:the entity itself
type_string
Returns:the string defining the type of the group
user
Returns:a backend user object, representing the user associated to this group.
Return type:aiida.orm.implementation.BackendUser
uuid
Returns:a string with the uuid
class aiida.orm.implementation.sqlalchemy.groups.SqlaGroupCollection(backend)[source]

Bases: aiida.orm.implementation.groups.BackendGroupCollection

The SLQA collection of groups

ENTITY_CLASS

alias of SqlaGroup

__abstractmethods__ = frozenset()
__module__ = 'aiida.orm.implementation.sqlalchemy.groups'
__parameters__ = ()
_abc_impl = <_abc_data object>
delete(id)[source]

Delete a group with the given id

Parameters:id – the id of the group to delete
query(label=None, type_string=None, pk=None, uuid=None, nodes=None, user=None, node_attributes=None, past_days=None, label_filters=None, **kwargs)[source]

Query for groups.

Note:

By default, query for user-defined groups only (type_string==”“). If you want to query for all type of groups, pass type_string=None. If you want to query for a specific type of groups, pass a specific string as the type_string argument.

Parameters:
  • name – the name of the group
  • nodes – a node or list of nodes that belongs to the group (alternatively, you can also pass a DbNode or list of DbNodes)
  • pk – the pk of the group
  • uuid – the uuid of the group
  • type_string – the string for the type of node; by default, look only for user-defined groups (see note above).
  • user – by default, query for groups of all users; if specified, must be a DbUser object, or a string for the user email.
  • past_days – by default, query for all groups; if specified, query the groups created in the last past_days. Must be a datetime object.
  • name_filters – dictionary that can contain ‘startswith’, ‘endswith’ or ‘contains’ as keys
  • node_attributes – if not None, must be a dictionary with format {k: v}. It will filter and return only groups where there is at least a node with an attribute with key=k and value=v. Different keys of the dictionary are joined with AND (that is, the group should satisfy all requirements. v can be a base data type (str, bool, int, float, …) If it is a list or iterable, that the condition is checked so that there should be at least a node in the group with key=k and value=each of the values of the iterable.
  • kwargs

    any other filter to be passed to DbGroup.objects.filter

    Example: if node_attributes = {'elements': ['Ba', 'Ti'], 'md5sum': 'xxx'},
    it will find groups that contain the node with md5sum = ‘xxx’, and moreover contain at least one node for element ‘Ba’ and one node for element ‘Ti’.

SQLA Log and LogCollection module

class aiida.orm.implementation.sqlalchemy.logs.SqlaLog(backend, time, loggername, levelname, dbnode_id, message='', metadata=None)[source]

Bases: aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity, aiida.orm.implementation.logs.BackendLog

SQLA Log backend entity

MODEL_CLASS

alias of aiida.backends.sqlalchemy.models.log.DbLog

__abstractmethods__ = frozenset()
__init__(backend, time, loggername, levelname, dbnode_id, message='', metadata=None)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'aiida.orm.implementation.sqlalchemy.logs'
__orig_bases__ = (aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity[aiida.backends.sqlalchemy.models.log.DbLog], <class 'aiida.orm.implementation.logs.BackendLog'>)
__parameters__ = ()
_abc_impl = <_abc_data object>
dbnode_id

Get the id of the object that created the log entry

levelname

The name of the log level

loggername

The name of the logger that created this entry

message

Get the message corresponding to the entry

metadata

Get the metadata corresponding to the entry

time

Get the time corresponding to the entry

uuid

Get the string representation of the UUID of the log entry

class aiida.orm.implementation.sqlalchemy.logs.SqlaLogCollection(backend)[source]

Bases: aiida.orm.implementation.logs.BackendLogCollection

The SQLA collection for logs

ENTITY_CLASS

alias of SqlaLog

__abstractmethods__ = frozenset()
__module__ = 'aiida.orm.implementation.sqlalchemy.logs'
__parameters__ = ()
_abc_impl = <_abc_data object>
delete(log_id)[source]

Remove a Log entry from the collection with the given id

Parameters:

log_id (int) – id of the Log to delete

Raises:
  • TypeError – if log_id is not an int
  • NotExistent – if Log with ID log_id is not found
delete_all()[source]

Delete all Log entries.

Raises:IntegrityError – if all Logs could not be deleted
delete_many(filters)[source]

Delete Logs based on filters

Parameters:

filters (dict) – similar to QueryBuilder filter

Returns:

(former) PK s of deleted Logs

Return type:

list

Raises:
  • TypeError – if filters is not a dict
  • ValidationError – if filters is empty

SqlAlchemy implementation of the BackendNode and BackendNodeCollection classes.

class aiida.orm.implementation.sqlalchemy.nodes.SqlaNode(backend, node_type, user, computer=None, process_type=None, label='', description='', ctime=None, mtime=None)[source]

Bases: aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity, aiida.orm.implementation.nodes.BackendNode

SQLA Node backend entity

MODEL_CLASS

alias of aiida.backends.sqlalchemy.models.node.DbNode

__abstractmethods__ = frozenset()
__init__(backend, node_type, user, computer=None, process_type=None, label='', description='', ctime=None, mtime=None)[source]

Construct a new BackendNode instance wrapping a new DbNode instance.

Parameters:
  • backend – the backend
  • node_type – the node type string
  • user – associated BackendUser
  • computer – associated BackendComputer
  • label – string label
  • description – string description
  • ctime – The creation time as datetime object
  • mtime – The modification time as datetime object
__module__ = 'aiida.orm.implementation.sqlalchemy.nodes'
__orig_bases__ = (aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity[aiida.backends.sqlalchemy.models.node.DbNode], <class 'aiida.orm.implementation.nodes.BackendNode'>)
__parameters__ = ()
_abc_impl = <_abc_data object>

Add a link of the given type from a given node to ourself.

Parameters:
  • source – the node from which the link is coming
  • link_type – the link type
  • link_label – the link label
_flag_field(field)[source]
_flush_if_stored()[source]
add_incoming(source, link_type, link_label)[source]

Add a link of the given type from a given node to ourself.

Parameters:
  • source – the node from which the link is coming
  • link_type – the link type
  • link_label – the link label
Returns:

True if the proposed link is allowed, False otherwise

Raises:

aiida.common.ModificationNotAllowed – if either source or target node is not stored

attributes

Return the complete attributes dictionary.

Warning

While the node is unstored, this will return references of the attributes on the database model, meaning that changes on the returned values (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the node is stored, the returned attributes will be a deep copy and mutations of the database attributes will have to go through the appropriate set methods. Therefore, once stored, retrieving a deep copy can be a heavy operation. If you only need the keys or some values, use the iterators attributes_keys and attributes_items, or the getters get_attribute and get_attribute_many instead.

Returns:the attributes as a dictionary
attributes_items()[source]

Return an iterator over the attributes.

Returns:an iterator with attribute key value pairs
attributes_keys()[source]

Return an iterator over the attribute keys.

Returns:an iterator with attribute keys
clean_values()[source]
clear_attributes()[source]

Delete all attributes.

clear_extras()[source]

Delete all extras.

clone()[source]

Return an unstored clone of ourselves.

Returns:an unstored BackendNode with the exact same attributes and extras as self
computer

Return the computer of this node.

Returns:the computer or None
Return type:BackendComputer or None
delete_attribute(key)[source]

Delete an attribute.

Parameters:key – name of the attribute
Raises:AttributeError – if the attribute does not exist
delete_attribute_many(keys)[source]

Delete multiple attributes.

Parameters:keys – names of the attributes to delete
Raises:AttributeError – if at least one of the attribute does not exist
delete_extra(key)[source]

Delete an extra.

Parameters:key – name of the extra
Raises:AttributeError – if the extra does not exist
delete_extra_many(keys)[source]

Delete multiple extras.

Parameters:keys – names of the extras to delete
Raises:AttributeError – if at least one of the extra does not exist
extras

Return the complete extras dictionary.

Warning

While the node is unstored, this will return references of the extras on the database model, meaning that changes on the returned values (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the node is stored, the returned extras will be a deep copy and mutations of the database extras will have to go through the appropriate set methods. Therefore, once stored, retrieving a deep copy can be a heavy operation. If you only need the keys or some values, use the iterators extras_keys and extras_items, or the getters get_extra and get_extra_many instead.

Returns:the extras as a dictionary
extras_items()[source]

Return an iterator over the extras.

Returns:an iterator with extra key value pairs
extras_keys()[source]

Return an iterator over the extra keys.

Returns:an iterator with extra keys
get_attribute(key)[source]

Return the value of an attribute.

Warning

While the node is unstored, this will return a reference of the attribute on the database model, meaning that changes on the returned value (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the node is stored, the returned attribute will be a deep copy and mutations of the database attributes will have to go through the appropriate set methods.

Parameters:key – name of the attribute
Returns:the value of the attribute
Raises:AttributeError – if the attribute does not exist and no default is specified
get_attribute_many(keys)[source]

Return the values of multiple attributes.

Warning

While the node is unstored, this will return references of the attributes on the database model, meaning that changes on the returned values (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the node is stored, the returned attributes will be a deep copy and mutations of the database attributes will have to go through the appropriate set methods. Therefore, once stored, retrieving a deep copy can be a heavy operation. If you only need the keys or some values, use the iterators attributes_keys and attributes_items, or the getters get_attribute and get_attribute_many instead.

Parameters:keys – a list of attribute names
Returns:a list of attribute values
Raises:AttributeError – if at least one attribute does not exist
get_extra(key)[source]

Return the value of an extra.

Warning

While the node is unstored, this will return a reference of the extra on the database model, meaning that changes on the returned value (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the node is stored, the returned extra will be a deep copy and mutations of the database extras will have to go through the appropriate set methods.

Parameters:key – name of the extra
Returns:the value of the extra
Raises:AttributeError – if the extra does not exist and no default is specified
get_extra_many(keys)[source]

Return the values of multiple extras.

Warning

While the node is unstored, this will return references of the extras on the database model, meaning that changes on the returned values (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the node is stored, the returned extras will be a deep copy and mutations of the database extras will have to go through the appropriate set methods. Therefore, once stored, retrieving a deep copy can be a heavy operation. If you only need the keys or some values, use the iterators extras_keys and extras_items, or the getters get_extra and get_extra_many instead.

Parameters:keys – a list of extra names
Returns:a list of extra values
Raises:AttributeError – if at least one extra does not exist
reset_attributes(attributes)[source]

Reset the attributes.

Note

This will completely clear any existing attributes and replace them with the new dictionary.

Parameters:attributes – a dictionary with the attributes to set
reset_extras(extras)[source]

Reset the extras.

Note

This will completely clear any existing extras and replace them with the new dictionary.

Parameters:extras – a dictionary with the extras to set
set_attribute(key, value)[source]

Set an attribute to the given value.

Parameters:
  • key – name of the attribute
  • value – value of the attribute
set_attribute_many(attributes)[source]

Set multiple attributes.

Note

This will override any existing attributes that are present in the new dictionary.

Parameters:attributes – a dictionary with the attributes to set
set_extra(key, value)[source]

Set an extra to the given value.

Parameters:
  • key – name of the extra
  • value – value of the extra
set_extra_many(extras)[source]

Set multiple extras.

Note

This will override any existing extras that are present in the new dictionary.

Parameters:extras – a dictionary with the extras to set
store(links=None, with_transaction=True, clean=True)[source]

Store the node in the database.

Parameters:
  • links – optional links to add before storing
  • with_transaction – if False, do not use a transaction because the caller will already have opened one.
  • clean – boolean, if True, will clean the attributes and extras before attempting to store
user

Return the user of this node.

Returns:the user
Return type:BackendUser
class aiida.orm.implementation.sqlalchemy.nodes.SqlaNodeCollection(backend)[source]

Bases: aiida.orm.implementation.nodes.BackendNodeCollection

The collection of Node entries.

ENTITY_CLASS

alias of SqlaNode

__abstractmethods__ = frozenset()
__module__ = 'aiida.orm.implementation.sqlalchemy.nodes'
__parameters__ = ()
_abc_impl = <_abc_data object>
delete(pk)[source]

Remove a Node entry from the collection with the given id

Parameters:pk – id of the node to delete
get(pk)[source]

Return a Node entry from the collection with the given id

Parameters:pk – id of the node

Sqla query builder implementation

class aiida.orm.implementation.sqlalchemy.querybuilder.SqlaQueryBuilder(backend)[source]

Bases: aiida.orm.implementation.querybuilder.BackendQueryBuilder

QueryBuilder to use with SQLAlchemy-backend and schema defined in backends.sqlalchemy.models

AuthInfo

A property, decorated with @property. Returns the implementation for the AuthInfo

Comment

A property, decorated with @property. Returns the implementation for the Comment

Computer

A property, decorated with @property. Returns the implementation for the Computer

Group

A property, decorated with @property. Returns the implementation for the Group

A property, decorated with @property. Returns the implementation for the DbLink

Log

A property, decorated with @property. Returns the implementation for the Log

Node

Decorated as a property, returns the implementation for DbNode. It needs to return a subclass of sqlalchemy.Base, which means that for different ORM’s a corresponding dummy-model must be written.

User

A property, decorated with @property. Returns the implementation for the User

__abstractmethods__ = frozenset()
__init__(backend)[source]
Parameters:backend – the backend
__module__ = 'aiida.orm.implementation.sqlalchemy.querybuilder'
_abc_impl = <_abc_data object>
count(query)[source]
Returns:the number of results
first(query)[source]

Executes query in the backend asking for one instance.

Returns:One row of aiida results
get_aiida_res(key, res)[source]

Some instance returned by ORM (django or SA) need to be converted to AiiDA instances (eg nodes). Choice (sqlalchemy_utils) will return their value

Parameters:
  • key – The key
  • res – the result returned by the query
Returns:

an aiida-compatible instance

get_column_names(alias)[source]

Given the backend specific alias, return the column names that correspond to the aliased table.

get_filter_expr(operator, value, attr_key, is_attribute, alias=None, column=None, column_name=None)[source]

Applies a filter on the alias given. Expects the alias of the ORM-class on which to filter, and filter_spec. Filter_spec contains the specification on the filter. Expects:

Parameters:
  • operator – The operator to apply, see below for further details
  • value – The value for the right side of the expression, the value you want to compare with.
  • path – The path leading to the value
  • attr_key – Boolean, whether the value is in a json-column, or in an attribute like table.

Implemented and valid operators:

  • for any type: * == (compare single value, eg: ‘==’:5.0) * in (compare whether in list, eg: ‘in’:[5, 6, 34]

  • for floats and integers:
    • >
    • <
    • <=
    • >=
  • for strings:
    • like (case - sensitive), for example ‘like’:’node.calc.%’ will match node.calc.relax and node.calc.RELAX and node.calc. but not node.CALC.relax
    • ilike (case - unsensitive) will also match node.CaLc.relax in the above example

    Note

    The character % is a reserved special character in SQL, and acts as a wildcard. If you specifically want to capture a % in the string, use: _%

  • for arrays and dictionaries (only for the SQLAlchemy implementation):

    • contains: pass a list with all the items that the array should contain, or that should be among the keys, eg: ‘contains’: [‘N’, ‘H’])
    • has_key: pass an element that the list has to contain or that has to be a key, eg: ‘has_key’:’N’)
  • for arrays only (SQLAlchemy version):
    • of_length
    • longer
    • shorter

All the above filters invoke a negation of the expression if preceded by ~:

# first example:
filter_spec = {
    'name' : {
        '~in':[
            'halle',
            'lujah'
        ]
    } # Name not 'halle' or 'lujah'
}

# second example:
filter_spec =  {
    'id' : {
        '~==': 2
    }
} # id is not 2
get_filter_expr_from_attributes(operator, value, attr_key, column=None, column_name=None, alias=None)[source]

Returns an valid SQLAlchemy expression.

Parameters:
  • operator – The operator provided by the user (‘==’, ‘>’, …)
  • value – The value to compare with, e.g. (5.0, ‘foo’, [‘a’,’b’])
  • attr_key (str) – The path to that attribute as a tuple of values. I.e. if that attribute I want to filter by is the 2nd element in a list stored under the key ‘mylist’, this is (‘mylist’, ‘2’).
  • column – Optional, an instance of sqlalchemy.orm.attributes.InstrumentedAttribute or
  • column_name (str) – The name of the column, and the backend should get the InstrumentedAttribute.
  • alias – The aliased class.
Returns:

An instance of sqlalchemy.sql.elements.BinaryExpression

get_projectable_attribute(alias, column_name, attrpath, cast=None, **kwargs)[source]
Returns:An attribute store in a JSON field of the give column
get_session()[source]
Returns:a valid session, an instance of sqlalchemy.orm.session.Session
iterall(query, batch_size, tag_to_index_dict)[source]
Returns:An iterator over all the results of a list of lists.
iterdict(query, batch_size, tag_to_projected_properties_dict, tag_to_alias_map)[source]
Returns:An iterator over all the results of a list of dictionaries.
modify_expansions(alias, expansions)[source]

In SQLA, the metadata should be changed to _metadata to be in-line with the database schema

table_groups_nodes

A property, decorated with @property. Returns the implementation for the many-to-many relationship between group and nodes.

yield_per(query, batch_size)[source]
Parameters:count – Number of rows to yield per step

Yields count rows at a time

Returns:a generator
class aiida.orm.implementation.sqlalchemy.querybuilder.array_length(*clauses, **kwargs)[source]

Bases: sqlalchemy.sql.functions.FunctionElement

__module__ = 'aiida.orm.implementation.sqlalchemy.querybuilder'
_compiler_dispatch(**kw)
_compiler_dispatcher = <sqlalchemy.ext.compiler._dispatcher object>
name = 'array_len'
aiida.orm.implementation.sqlalchemy.querybuilder.compile(element, compiler, **_kw)[source]

Get length of array defined in a JSONB column

class aiida.orm.implementation.sqlalchemy.querybuilder.jsonb_array_length(*clauses, **kwargs)[source]

Bases: sqlalchemy.sql.functions.FunctionElement

__module__ = 'aiida.orm.implementation.sqlalchemy.querybuilder'
_compiler_dispatch(**kw)
_compiler_dispatcher = <sqlalchemy.ext.compiler._dispatcher object>
name = 'jsonb_array_len'
class aiida.orm.implementation.sqlalchemy.querybuilder.jsonb_typeof(*clauses, **kwargs)[source]

Bases: sqlalchemy.sql.functions.FunctionElement

__module__ = 'aiida.orm.implementation.sqlalchemy.querybuilder'
_compiler_dispatch(**kw)
_compiler_dispatcher = <sqlalchemy.ext.compiler._dispatcher object>
name = 'jsonb_typeof'

SQLA user

class aiida.orm.implementation.sqlalchemy.users.SqlaUserCollection(backend)[source]

Bases: aiida.orm.implementation.users.BackendUserCollection

Collection of SQLA Users

ENTITY_CLASS

alias of SqlaUser

__module__ = 'aiida.orm.implementation.sqlalchemy.users'
__parameters__ = ()
create(email, first_name='', last_name='', institution='')[source]

Create a user with the provided email address

Returns:A new user object
Return type:aiida.orm.User
find(email=None, id=None)[source]

Find a user in matching the given criteria

Parameters:
  • email – the email address
  • id – the id
Returns:

the matching user

Return type:

aiida.orm.implementation.sqlalchemy.users.SqlaUser

class aiida.orm.implementation.sqlalchemy.users.SqlaUser(backend, email, first_name, last_name, institution)[source]

Bases: aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity, aiida.orm.implementation.users.BackendUser

SQLA user

MODEL_CLASS

alias of aiida.backends.sqlalchemy.models.user.DbUser

__abstractmethods__ = frozenset()
__init__(backend, email, first_name, last_name, institution)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'aiida.orm.implementation.sqlalchemy.users'
__orig_bases__ = (aiida.orm.implementation.sqlalchemy.entities.SqlaModelEntity[aiida.backends.sqlalchemy.models.user.DbUser], <class 'aiida.orm.implementation.users.BackendUser'>)
__parameters__ = ()
_abc_impl = <_abc_data object>
email

Get the email address of the user

Returns:the email address
first_name

Get the user’s first name

Returns:the first name
Return type:str
institution

Get the user’s institution

Returns:the institution
Return type:str
last_name

Get the user’s last name

Returns:the last name
Return type:str

Utilities for the implementation of the SqlAlchemy backend.

class aiida.orm.implementation.sqlalchemy.utils.ModelWrapper(model, auto_flush=())[source]

Bases: object

Wrap a database model instance to correctly update and flush the data model when getting or setting a field.

If the model is not stored, the behavior of the get and set attributes is unaltered. However, if the model is stored, which is to say, it has a primary key, the getattr and setattr are modified as follows:

  • getattr: if the item corresponds to a mutable model field, the model instance is refreshed first
  • setattr: if the item corresponds to a mutable model field, changes are flushed after performing the change
__dict__ = mappingproxy({'__module__': 'aiida.orm.implementation.sqlalchemy.utils', '__doc__': 'Wrap a database model instance to correctly update and flush the data model when getting or setting a field.\n\n If the model is not stored, the behavior of the get and set attributes is unaltered. However, if the model is\n stored, which is to say, it has a primary key, the `getattr` and `setattr` are modified as follows:\n\n * `getattr`: if the item corresponds to a mutable model field, the model instance is refreshed first\n * `setattr`: if the item corresponds to a mutable model field, changes are flushed after performing the change\n ', '__init__': <function ModelWrapper.__init__>, '__getattr__': <function ModelWrapper.__getattr__>, '__setattr__': <function ModelWrapper.__setattr__>, 'is_saved': <function ModelWrapper.is_saved>, 'save': <function ModelWrapper.save>, '_is_mutable_model_field': <function ModelWrapper._is_mutable_model_field>, '_is_model_field': <function ModelWrapper._is_model_field>, '_flush': <function ModelWrapper._flush>, '_ensure_model_uptodate': <function ModelWrapper._ensure_model_uptodate>, '_in_transaction': <staticmethod object>, '__dict__': <attribute '__dict__' of 'ModelWrapper' objects>, '__weakref__': <attribute '__weakref__' of 'ModelWrapper' objects>})
__getattr__(item)[source]

Get an attribute of the model instance.

If the model is saved in the database, the item corresponds to a mutable model field and the current scope is not in an open database connection, then the field’s value is first refreshed from the database.

Parameters:item – the name of the model field
Returns:the value of the model’s attribute
__init__(model, auto_flush=())[source]

Construct the ModelWrapper.

Parameters:
  • model – the database model instance to wrap
  • auto_flush – an optional tuple of database model fields that are always to be flushed, in addition to the field that corresponds to the attribute being set through __setattr__.
__module__ = 'aiida.orm.implementation.sqlalchemy.utils'
__setattr__(key, value)[source]

Set the attribute on the model instance.

If the field being set is a mutable model field and the model is saved, the changes are flushed.

Parameters:
  • key – the name of the model field
  • value – the value to set
__weakref__

list of weak references to the object (if defined)

_ensure_model_uptodate(fields=None)[source]

Refresh all fields of the wrapped model instance by fetching the current state of the database instance.

Parameters:fields – optionally refresh only these fields, if None all fields are refreshed.
_flush(fields=())[source]

Flush the fields of the model to the database.

Note

If the wrapped model is not actually save in the database yet, this method is a no-op.

Parameters:fields – the model fields whose currently value to flush to the database
static _in_transaction()[source]

Return whether the current scope is within an open database transaction.

Returns:boolean, True if currently in open transaction, False otherwise.
_is_model_field(field)[source]

Return whether the field is a field of the model.

Returns:boolean, True if the field is a model field, False otherwise.
_is_mutable_model_field(field)[source]

Return whether the field is a mutable field of the model.

Returns:boolean, True if the field is a model field and is not in the IMMUTABLE_MODEL_FIELDS set.
is_saved()[source]

Retun whether the wrapped model instance is saved in the database.

Returns:boolean, True if the model is saved in the database, False otherwise
save()[source]

Store the model instance.

Note

If one is currently in a transaction, this method is a no-op.

Raises:aiida.common.IntegrityError – if a database integrity error is raised during the save.
aiida.orm.implementation.sqlalchemy.utils.disable_expire_on_commit(session)[source]

Context manager that disables expire_on_commit and restores the original value on exit

Parameters:session (sqlalchemy.orm.session.Session) – The SQLA session