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>
property computer

Return the computer associated with this instance.

Returns

aiida.orm.implementation.computers.BackendComputer

property 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

property id

Get the id of this entity

Returns

the entity id

property 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

property 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>
property authinfos

Return the collection of authorisation information objects

Returns

the authinfo collection

Return type

aiida.orm.implementation.BackendAuthInfoCollection

property comments

Return the collection of comments

Returns

the comment collection

Return type

aiida.orm.implementation.BackendCommentCollection

property 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

property groups

Return the collection of groups

Returns

the groups collection

Return type

aiida.orm.implementation.BackendGroupCollection

property 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.

property 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

property 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.

property 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>
property content
property ctime
property mtime
property 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.

property 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.

property 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]
property hostname
property id

Get the id of this entity

Returns

the entity id

property is_stored

Is this entity stored?

Returns

True if stored, False otherwise

property name
property 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.

property 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
property 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

property id

Get the id of this entity

Returns

the entity id

property is_stored

Is this entity stored?

Returns

True if stored, False otherwise

property 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

property description
Returns

the description of the group as a string

property is_stored

Is this entity stored?

Returns

True if stored, False otherwise

property label
Returns

the name of the group as a string

property nodes

Get an iterator to all the nodes in the group

property 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

property type_string
Returns

the string defining the type of the group

property user
Returns

a backend user object, representing the user associated to this group.

Return type

aiida.orm.implementation.BackendUser

property 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>
property dbnode_id

Get the id of the object that created the log entry

property levelname

The name of the log level

property loggername

The name of the logger that created this entry

property message

Get the message corresponding to the entry

property metadata

Get the metadata corresponding to the entry

property time

Get the time corresponding to the entry

property 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

property 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

property 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

property 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

property 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

property AuthInfo

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

property Comment

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

property Computer

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

property Group

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

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

property Log

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

property 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.

property 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

property 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>
property email

Get the email address of the user

Returns

the email address

property first_name

Get the user’s first name

Returns

the first name

Return type

str

property institution

Get the user’s institution

Returns

the institution

Return type

str

property 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