Abstract Data Structures

AbstractSet

Definition of the AbstractSet.

An AbstractSet is represented in Neo4j as follows:

• Where PersistentElement can be ANY entity in the data model deriving from PersistentElement. For more details please see Class Diagrams & Data Modeling

author:

Athanasios Anastasiou

date:

Mar 2023

class neoads.ads_abstractset.AbstractSet(name=None, **kwargs)

A Set of UNIQUE elements.

DoesNotExist

alias of AbstractSetDoesNotExist

add(an_item)

Adds an item to the set. Similar to Python’s set.add().

Warning

The item must be hashable.

Parameters:

an_item (PersistentElement) – An object to be added to the AbstractSet.

Returns:

AbstractSet (self)

add_with_hash(an_item, a_hash)

Adds an item to the set with a particular hash value.

Warning

Not meant to be called directly. Used by the AbstractMap.

Parameters:

• an_item (PersistentElement) – An object that is to be added to the set

• a_hash (int) – A hash value

Returns:

clear()

Clears the set.

contains_hash(a_hash)

Determines if the set contains a specific hash value.

Parameters:

a_hash (int) – The hash value to test

Returns:

bool

destroy()

Clears the set and removes it from the DBMS completely.

from_abstractset(an_abstractSet, auto_reset=False)

Initialises an abstract set from another abstract set.

Parameters:

• an_abstractSet –

• auto_reset –

Returns:

AbstractSet (self)

from_hash_nodeid_list(a_hash_nodeid_list, auto_reset=False)

Initialises an abstract set from a list of hash, Node ID tuples

Warning

Not to be called directly.

Parameters:

• a_hash_nodeid_list (list) – A list of tuples

• auto_reset (boolean) – Whether to clear the contents of the set automatically

Returns:

AbstractSet (self)

from_query(query, auto_reset=False)

Populates a Set from a query at server side.

Warning

Use of this function requires the Neo4j server to be using APOC. If APOC is not available, see AbstractSet’s .add()

Note

The set’s elements are the entities that are “selected” by query. The query MUST bind a SetElement entity which itself would have to be a PersistentElement and should be an incomplete CYPHER READ query.

EXAMPLE:

"MATCH (SetElement: CompositeString)"
          with a possible WHERE clause too

Notice here:

• This query would create a Set of all the unique CompositeString entities in the database.

• This query is incompete. It only contains the MATCH statement without the usually necessary return clause.

Parameters:

• query (str) – A CYPHER READ query WITHOUT the return clause. The elements of the set should be bind as SetElement.

• auto_reset (bool) – Whether to re-use the set node by first clearing the contents of the Set prior to populating it.

Raises:

ContainerNotEmpty – When from_query is called on an already populated Set. Use auto_reset=True to discard the current Set elements and reset it to the result of from_query.

Returns:

AbstractSet (self)

remove_by_hash(a_hash)

Removes an element from the set, given its hash value.

Warning

Not meant to be called directly. Used by AbstractMap.

Parameters:

a_hash (int) – An object’s hash value

Returns:

AbstractSet (self)

retrieve_by_hash(a_hash)

Retrieves the value that the set element points to given the set element’s hash value.

Warning

Not meant to be called directly. Used by AbstractMap.

Parameters:

a_hash (int) – An object’s hash value

Returns:

PersistentElement

class neoads.ads_abstractset.SetItem(hash_value, **kwargs)

A struct item that is an element of a set.

A set item maintains its item’s hash_value for fast lookups.

DoesNotExist

alias of SetItemDoesNotExist

AbstractMap

Definitions for the abstract set (AbstractSet) data structure.

An AbstractMap is represented in Neo4j as follows:

• Where AbstractSet is expanded as depicted here

author:

Athanasios Anastasiou

date:

Jan 2018

class neoads.ads_abstractmap.AbstractMap(name=None, **kwargs)

A very simple mapping that maps a hash value (that can be computed by any hashable) to an entity.

Note

The abstract map is implemented via two neoads.AbstractSets, one for the keys and one for the values.

DoesNotExist

alias of AbstractMapDoesNotExist

clear()

Clears the map.

destroy()

Clears the map and completely removes it from the DBMS.

from_keyvalue_node_query(a_query, auto_reset=False)

Instantiates an AbstractMap via a query.

Note

The query must have a specific structure and return two arrays, one for the keys and one for the values. For example:

SimpleNumber(1).save()
SimpleNumber(2).save()
SimpleNumber(3).save()

CompositeString("One").save()
CompositeString("Two").save()
CompositeString("Three").save()

Q = AbstractSet(name="ASET").save()

Q.from_keyvalue_node_query("MATCH (a:ElementVariable) WHERE a.value IN [1,2,3] WITH collect(a) AS Keys
MATCH (b:ElementVariable) WHERE b.value IN ["One","Two","Three"] WITH Keys, collect(b) as Values")

The objects in the array will have to be inflated in to Python, their hash calculated and then used to construct the sets.

Parameters:

• a_query (str) – A COMPLETE CYPHER query.

• auto_reset –

Returns:

AbstractMap (self)

property keys

Return an iterator to keys.

Returns:

An iterator to the neoads elements that make up the AbstractSet of keys.

Return type:

list

property values

Return an iterator to values.

Returns:

An iterator to the neoads elements that make up the AbstractSet of values.

Return type:

list

AbstractDLList

Definitions for the abstract double linked list (AbstractDLList).

An AbstractDLList is represented in Neo4j with the following object diagram:

• This diagram shows a double linked list with two elements.

• Where PersistentElement can be ANY entity in the data model deriving from PersistentElement.

• The module defines both end-user data structures as well as intermediate (or helper) data structures.

For more details please see Class Diagrams & Data Modeling

author:

Athanasios Anastasiou

date:

Jan 2018

class neoads.ads_abstractdllist.AbstractDLList(name=None, **kwargs)

A doubly linked list with indexing.

Note

Although the list is Doubly Linked, only the list’s head is preserved with the List entry.

DoesNotExist

alias of AbstractDLListDoesNotExist

append(an_element)

Appends any PersistentElement to the Doubly Linked List.

Parameters:

an_element – PersistentElement

Returns:

AbstractDLList (self)

clear()

Clears the list.

Note

To delete the list itself, use destroy()

destroy()

Clears the list and completely removes it from the DBMS.

extend_by_merging(another_dlList)

Concatenates this list with another_dlList and ERASES another_dlList as a separate list from the backend.

Parameters:

another_dlList (str or AbstractDLList.) – The identifier or object of a list that already exists on the DBMS.

Returns:

AbstractDLList

from_id_array(array_of_ids, auto_reset=False)

Initialises the doubly linked list from a numeric array of node IDs.

Note

This array_of_ids is usually constructed via a call to CompositeArrayNumber.from_query_IDs(). Because of the dangers associated with maintaining IDs for long intervals it is best if these two are called in quick succession.

Parameters:

array_of_ids (str or CompositeArrayNumber) – The name or actual object of an array of IDs.

Returns:

AbstractDLList (self)

from_query(query, auto_reset=False)

Populates a doubly linked list at server side.

Note

The list’s items are the entities that are “selected” by query. The query MUST bind a ListItem entity which itself would have to be a PersistentElement and should be an incomplete CYPHER READ query.

Warning

At the moment, the way the CYPHER queries that build the list are expressed, they seem to “explode” with the number of items returned by from_query(…, query). So use with caution.

If the query returns duplicates, these are retained in the list because a list does not behave like a set.

EXAMPLE:

"MATCH (ListItem:Institute)-[:CITY]-(:City)-[:IN_COUNTRY]-(:Country{countryName:'Australia'})"
          with a possible WHERE clause too

Notice here, this query is incompete. It only contains the MATCH statement without the usually necessary return clause.

Parameters:

• query (str) – A CYPHER READ query WITHOUT the return clause. The entity that is to be pointed to by list items should be bind as ListItem.

• auto_reset (bool) – Whether to re-use the list node by first clearing the contents of the list prior to populating it.

Raises:

ContainerNotEmpty – When from_query is called on an already populated List. Use auto_reset=True to discard the current list items and reset it to the result of from_query.

Returns:

AbstractDLList (self)

get_head()

Returns the list’s wrapper object at the head of the list

get_tail()

Returns the list’s wrapper object at the tail of the list

iterate_by_query(this_list_known_as)

Generates a query that iterates over all items of the list.

Note

This can be used to “trigger” further queries / operations over each item within the list.

Warning

These are the ACTUAL ITEMS that the list is holding. If this list is pointing to other lists, those lists are not automatically UNWINDED!!!!

EXAMPLE:

neomodel.db.cypher_query(list1.iterate_by_query("pubmed")+"MATCH (Author1:Author)-[:AUTHOR]-
                                                (pubmed_listItemValue)-[:AUTHOR]-(Author2:Author)
                                                where Author1<>Author2 return count(Author1)")

Parameters:

this_list_known_as (str) – An identifier by which this list will be known within the query. It is possible to concatenate many of these from different lists and therefore should not have name collisions.

project_as(this_list_known_as, projection_known_as, projected_field=None, pass_through=None)

Returns a query that converts the Doubly Linked List to a native neo4j list so that it can participate in subsequent queries. This function returns part of a query that can be concatenated with other lists as part of a bigger query.

Note

Collects the values of projected_field from this list into a new, sequential array that is being known as projection_known_as.

This is the only way to implement “IN” at server side as somehow CYPHER has to iterate the array to extract specific values from it.

Parameters:

• pass_through (list) – List of other parameters that have to be propagated through this part of the query.

• this_list_known_as (str) – The logical name that this list will be made known as, server-side.

• projected_field (str) – The list item value field that is to be extracted from this list.

• projection_known_as (str) – The logical name that the generated list will be made known as, server-side.

Returns:

str (CYPHER query fragment)

with_this_list_as(this_list_known_as, other_lists=None)

Starts a CYPHER query in which an AbstractDLList is exposed with a given name.

Parameters:

• this_list_known_as (str) – The name that this list will be made known as, server-side.

• other_lists (list) – Other lists that may precede this particular list.

Returns:

str (CYPHER query fragment)

class neoads.ads_abstractdllist.AbstractDLListForwardIterator(dllist_to_iterate)

A forward iterator that returns a DL list’s elements in head to tail order.

class neoads.ads_abstractdllist.AbstractDLListReverseIterator(dllist_to_iterate)

A reverse iterator that returns a DL list’s elements in tail to head order.

class neoads.ads_abstractdllist.DLListItem(*args, **kwargs)

A struct item of a doubly linked list.

DoesNotExist

alias of DLListItemDoesNotExist