In [1]:
from deriva.core import ErmrestCatalog, get_credential
This example uses a development server with a throw away catalog. You will not have sufficient permissions to be able to run this example. This notebook is for documentation purpose only.
In [2]:
scheme = 'https'
hostname = 'dev.facebase.org'
catalog_number = 1
Use DERIVA-Auth to get a credential or use None if your catalog allows anonymous access.
In [3]:
credential = get_credential(hostname)
Now, connect to your catalog and the pathbuilder interface for the catalog.
In [4]:
assert scheme == 'http' or scheme == 'https', "Invalid http scheme used."
assert isinstance(hostname, str), "Hostname not set."
assert isinstance(catalog_number, int), "Invalid catalog number"
catalog = ErmrestCatalog(scheme, hostname, catalog_number, credential)
pb = catalog.getPathBuilder()
For this example, we will create or modify entities of the "Dataset" table of a catalog that uses the FaceBase data model.
In [5]:
dataset = pb.isa.dataset
dataset
Out[5]:
In [6]:
new_entity = {
'title': 'A test dataset by derivapy',
'description': 'This was created by the deriva-py API.',
'project': 311
}
entities = dataset.insert([new_entity], defaults={'id', 'accession'})
The insert operation returns the inserted entities, which now have any system generated attributes filled in.
In [7]:
list(entities)
Out[7]:
In [8]:
entities[0]['description'] = 'A test dataset that was updated by derivapy'
In [9]:
updated_entities = dataset.update(entities)
Similar to the insert operation, the update operation also returns the updated entities. Notice that the system-managed 'RMT' (Row Modified Timestamp) attribute has been update too.
In [10]:
list(updated_entities)
Out[10]:
You can also specify which columns to use to correlate the input with the existing rows in the table and which columsn to be the targets of the update. Per the ERMrest protocol, extra data in the update payload (entities) will be ignored. The inputs must be iterables of strings or objects that implement the __str__ method.
In [11]:
entities[0]['description'] = 'Yet another update using derivapy'
entities[0]['title'] = 'And a title change'
updated_entities = dataset.update(entities, [dataset.id], [dataset.description, 'title'])
In [12]:
list(updated_entities)
Out[12]:
Unlike insert and update which are performed within the context of a table, the delete operation is performed within the context of a data path.
We know the RID from above, which is a single-column key for the entities in the dataset (and any other EMRrest) table. We can use this attribute to form a path to the newly inserted and updated entity.
Note: Any filters could be used in this example; we do not have to use a key column only. We use the key only because we want to delete that specific entity which we just created. If we wanted to, we could link addition tables and apply additional filters to delete entities computed from a complex path.
In [13]:
path = dataset.filter(dataset.RID == entities[0]['RID'])
On successful delete, no content will be returned.
In [14]:
path.delete()