6. Databases

database types

Everything that Nala does is stored in freeform JSON databases. This makes it much easier to create complex databases and relationships. There are three main databases: registration.json, settings.json, and actions.json. Each of these will be briefly discussed in the sections that follow.

registration.json

This is the database that is used to store all the registration information. It contains the following fields:

Variable	Example	Description
name	'jim'	name of the user.
email	'js@neurolex.co'	email of user.
userID	0	the unique user ID of the user (this is only relevant if multiple users are using Nala and is a future feature)
hostdir	'/Users/jim/Desktop/nala/data/baseline'	the path to the directory of the baseline folder to access later.
location	{'ip': '71.156.202.219', 'city': 'Cambridge', 'region': 'Massachusetts', 'country': 'US', 'loc': '42.3700,-71.0812', 'postal': '02141', 'org': 'AS395354 Starry, Inc.'}	the location information of the registered user, so that actions can reference this information later.
rest time	0.1	the rest time after each query is completed before the wakeword engine is activated again.
facenums	24	a number determined based on facial recognition during the registration process.
registration date	'2018-07-09 09:58:53.639529'	the date of registration as determined by the datetime.datetime.now() function.

settings.json

This is where all the default settings are stored as described in the SETTINGS section of this wiki. Here are the values.

Variable	Options	Description
alarm	True, False	whether the alarm is turned on or off at the designated time
alarm time	8	the time the alarm would go off at (in 24 hour time, 8 = 8AM, 13 = 1 PM) if the alarm action is turned on.
greeting	True, False	if True, then Nala will greet you every time you login and get the weather (default). If False, she will not do this.
end	1531914937.172238	the last time that you updated the database (this is useful for understanding sessions)
transcription_type	‘sphinx’, ‘google’	The type of transcription. Default is ‘sphinx’ (and if google and the path to the environment variable cannot be found, it will revert back to sphinx).
wake_type	'sphinx', 'snowboy', 'porcupine'	Wakeword detector used to detect user queries. Default is ‘porcupine’ as it is the most accurate wakeword detector.
query_time	2	Time in seconds of each query when Nala is activated. The default query time is 2 seconds (from trial-and-error).
multi_query	True, False	Multi-query capability allows you to separate queries with AND in the transcript, so it doesn’t stop after one query. Default is True.
query_save	True, False	Ability to save queries once they have been propagated. Otherwise, they are deleted. This is useful if you want to cache query data or build a dataset. Default is True.
register_face	True, False	Store face when user registers to authenticate later with facial recognition. Default is True.
sleep_time	30	The time (in minutes) that Nala will sleep if you trigger the “Go to sleep” action query. Default is 30 minutes.
budget	30	The budget ($USD) that a user is comfortable spending going out with friends on a given night (for actions)
genre	'rock'	The user's preferred music genre (useful for actions).

actions.json

The actions.json directory is where the main database is stored. It is arranged as follows:

Variable	Description
logins	the date/times when a user logs in.
logouts	the date/times when a user logs out.
active session	what information is stored in the current session, not yet stored in the sessions variable.
sessions	sessions store all sorts of data - logins, logouts, queries, action logs, etc. - and represent the sum-total activity of a user over one login and logout.
query count	running count of queries that have been prompted to the end user.
queries	a reference to all queries that were recognized in the ./data/queries folder along with their associated metadata.
noise	a reference to queries that were not recognized in the ./data/queries folder.
action count	the total number of actions that have been executed.
action log	a running list of all the actions that have been executed - as used by all action scripts
loopnum	the number of times the Nala event loop has been repeated.
available actions	a list of currently available actions to execute.

database redundancy

Note that Nala uses a redundant database in case a database is corrupted. Specifically, Nala backs up the actions.json and settings.json databases upon each loop and iteration in the ./data/baseline directory. Nala also updates the databases in the directory where nala.py is located. In this way, databases can be restored later. Check out the following function that updates the database in the Nala code to see what I'm talking about:

def update_database(hostdir,logins,logouts,session,sessions,query_count,queries,noise,action_count,loopnum, alarm, end):

    curdir=os.getcwd()
    os.chdir(hostdir)

    # update only the fields that matter
    data=json.load(open('actions.json'))

    data['logins']=logins
    data['logouts']=logouts
    data['active session']=session
    data['sessions']=sessions
    data['query count']=query_count
    data['queries']=queries
    data['noise']=noise
    data['action count']=action_count
    data['loopnum']=loopnum

    jsonfile=open('actions.json','w')
    json.dump(data,jsonfile)
    jsonfile.close()

    data=json.load(open('settings.json'))

    data['alarm']=alarm
    data['end']=end

    jsonfile=open('settings.json','w')
    json.dump(data,jsonfile)
    jsonfile.close()

    # store backup copy just in case of either database being corrupted 
    os.chdir(hostdir+'/data/baseline')
    os.remove('actions.json')
    os.remove('settings.json')
    shutil.copy(hostdir+'/actions.json',os.getcwd()+'/actions.json')
    shutil.copy(hostdir+'/settings.json',os.getcwd()+'/settings.json')

    os.chdir(curdir)