CRUD Objects

The CrudObject class is a parent class of all entity classes in the ursa library, and need not be interacted with directly. CrudObject provides the primary interface between all of our entity classes, and the RDBMS.

CrudObjects provide interfaces for reading from, writing to, deleting from, and updating the database. The database methods provided by CrudObject may not be used directly on a CrudObject itself, as we do not maintain a table of “CrudObjects” but rather these methods may be invoked on any child class of CrudObject including:

  • TimeSeries

  • DataTable

  • Source

  • Underlying

All entity classes inherit the following operations from CrudObjects:

load

Load provides the main interface for loading entitys from the database by id.

Arguments:

  • id: int – The ID of the entity to load

  • db: sqlalchemy.orm.session.Session – the database session

Returns:

  • CrudObject: the entity loaded from the database

Example:


# Import required objects
from ursa_sync.backend import TimeSeries 
from ursa_sync import session 

# Open a session with the database
db = session() 

# Load the TimeSeries object with id=1 from the database
TS = TimeSeries.load(1, db)

# print the name of the timeseries
print(TS) 

# Always close the database session when you're done. 
db.close()

load_all

Loads all entities of the specific class from the database as a list.

Arguments:

  • db: sqlalchemy.orm.session.Session – the database session

Returns:

  • List[CrudObject]: A list of all the CrudObjects of the specified entity class.

Example:


# Import required objects
from ursa_sync.backend import TimeSeries 
from ursa_sync import session 

# Open a session with the database
db = session() 

# Load all timeseries objects from the database
TSS = TimeSeries.load_all(db)

# print the number of timeseries objects stored in your instance.
print(len(TSS)) 

# Always close the database session when you're done. 
db.close()

load_by

Provides an interface for loading based on specific critereon.

Arguments

  • columns: List[str] – the list of column names for filtering as strings

  • values: List[str] – list of values to condition on the corresponding columns

  • db: sqlalchemy.orm.session.Session – the database session

Returns

  • List[CrudObject]: A list of all the CrudObjects of the specified entity class, matching the specified criterion.

Example


# Import required objects
from ursa_sync.backend import TimeSeries 
from ursa_sync import session 

# Open a session with the database
db = session() 

# Load all timeseries objects TS from the database such that TS.underlying_id == 10
TSS = TimeSeries.load_by(['underlying_id'], [10], db)

# print the number of timeseries objects with underlying_id equal to 10.
print(len(TSS)) 

# Always close the database session when you're done. 
db.close()

bulk_load

Provides an interface for loading multiple CrudObjects of the same type from the database simultaneously, by a list of ids.

Arguments

  • ids: List[int] – a list of ids of objects to load from the database

  • db: sqlalchemy.orm.session.Session – the database session

Returns

  • List[CrudObject] – a list of CrudObjects with ids matching those passed to the function

Example


# Import required objects
from ursa_sync.backend import TimeSeries 
from ursa_sync import session 

# Open a session with the database
db = session() 

# Load the a list of TimeSeries objects from the db with ids 1, 2 and 3.
TSS = TimeSeries.bulk_load([1,2,3], db)

# print the number of timeseries objects returned
print(len(TSS)) 

# Always close the database session when you're done. 
db.close()

delete

Provides an interface for deleting CrudObjects.

Arguments

  • db: sqlalchemy.orm.session.Session = None – the database session. If None, the attached session will be used.

Returns

  • CrudObject: Returns the CrudObject which has now been removed from the database.

Example


# Supposing you already have a TimeSeries object loaded in your session, assigned to TS:
deletedTS = TS.delete()

save

Provides an interface for saving CrudObjects.

Arguments

  • db: sqlalchemy.orm.session.Session = None – the database session. If None, the attached session will be used.

Returns

  • CrudObject: Returns the CrudObject which has now been saved or updated in the database.

Example


# Show the existing name of the timeseries
print(TS.name)

# Set the variable TS.name
TS.name = "My New Name" 

# Save the updated TimeSeries object's new name to the database
updatedTS = TS.save()

bulk_save

In high-throughput situations where many CrudObjects need to be saved at once, iteratively calling CrudObject.save() becomes inefficient. This is due to the repeated database interactions. A more efficient way to save many CrudObjects at once is with bulk_save, which first adds all the objects to the database session, and only executes one final commit to save everything at the end.

Arguments

  • objects: List[CrudObject]

  • db: sqlalchemy.orm.session.Session – the database session.

Returns

  • CrudObject: Returns the list of CrudObjects which have now been saved or updated in the database.

Example


# Import required objects
from ursa_sync.backend import TimeSeries 
from ursa_sync import session 

# Open a session with the database
db = session() 

# Load the a list of TimeSeries objects from the db with ids 1, 2 and 3.
TSS = TimeSeries.bulk_load([1,2,3], db)

for TS in TSS: 
    TS.name = f"ID: {TS.id} -- NAME: {TS.name}" 

# Save the objects in bulk
new_objects = TimeSeries.bulk_save(TSS, db)

# Always close the database session when you're done. 
db.close()