UConDB Web API

class webapi.UConDBClient(server_url, timeout=5, username=None, password=None)

UConDB client constructor

Parameters:

  • server_url – str - the server endpoint URL, default: value of the UCONDB_SERVER_URL environment variable

  • timeout – float - timeout to use communicating with the server, default = 5 seconds

  • username – str - username, required only for “put”

  • password – str - password, required only for “put”

folders()

Returns list of UConDB folders found in the database

Returns:

list of strings - names of the folders found in the database

get(folder_name, object_name, tv=None, tr=None, tag=None, key=None, id=None, meta_only=True)

Retrieves single version metadata, possibly including the data BLOB

Parameters:

  • folder_name – str - name of the folder

  • object_name – str - name of the object

  • tv – float - validity time

  • tr – float - record time

  • tag – str - tag

  • key – str - version key

  • id – int - version id

  • meta_only – boolean - if False, data BLOB will be also returned

Returns:

dict - version metadata. If meta_only is False, the dictionary will contain “data” element pointing to the BLOB as bytes

get_data(folder_name, version_id=None, data_key=None)

Retieves data blob for single object version

Parameters:

  • folder_name – str - name of the folder

  • version_id – int - version id

  • data_key – str - version key

Returns:

bytes - version data BLOB

Either version_id or data_key must be specified, but not both

get_data_bulk(folder_name, version_ids=None, keys=None)

Retrieves data BLOBs for multiple object versions

Parameters:

  • folder_name – str - name of the folder

  • version_ids – list of ints - list of version ids

  • keys – list of strings - list of version keys

Yields:

genetares sequence of dictionaries with version metadata. Each dictionary also contains “data” with the version data BLOB

version_ids and keys can not be specified at the same time

lookup_versions(folder_name, object_name=None, keys=None, key_min=None, key_max=None, ids=None, tvs=None, tr=None, tag=None, tr_since=None)

Returns multiple object versions.

Parameters:

  • folder_name – name of the folder (string)

  • object_name – name of the object (string)

  • keys – list of version keys (strings). object_name must be specified. If keys present, tvs, tr, tag are ignored

  • tvs – list of version Tv’s (floats). object_name must be specified. tr, tag may be used.

  • ids – list of version ids (ints). object_name, keys, tvs, tr, tag are ignored.

  • tr – float - record time. Only versions recorded at or before tr time will be returned

  • tr_since – float - record time. Only versions recorded after tr_since time will be returned

  • tag – string - only versions with this tag will be returned

Returns:

list of dictionaries with version metadata. If a specified version is not found, it will be absent from the output set. Order is not guaranteed

Acceptable parameter combinations:

  • object_name, keys (tvs ignored)

  • object_name, key_range

  • object_name, tvs

  • ids (object_name, keys, tvs ignored)

  • object_name - all versions for the object

objects(folder_name)

Returns list of objects found in the folder

Parameters:

folder_name – str - name of the folder

Returns:

list of strings - names as objects found in the folder

put(folder_name, object_name, data, tv=None, tags=None, key=None, override_key=False)

Stores new version for the object

Parameters:

  • folder_name – str - name of the folder

  • object_name – str - name of the object

  • data – bytes - data BLOB

  • tv – float - validity time, default = 0

  • tags – string or list ofstrings - tag or tags to associate with the new version

  • key – str - version key

  • override_key – boolean - if True and key is specified, the key will be moved to the new version

Returns:

new version metadata as dict

This method requires that the client was initialzied with username and password

version()

Returns server version information

Returns:

string - version information

Code Samples

from ucondb.webapi import UConDBClient

client = UConDBClient("https://dbdata0vm.fnal.gov/path")

print("Server version:", client.version())

print("Folders:")
for folder_name in client.folders():
    print(folder_name)

for version in client.lookup_versions("configurations","config"):
    vid = version["id"]
    tv = version["tv"]
    print(f"Version {vid}: valid from: {tv}")