Aditi users' guide 1 Introduction - TTNZ

Aditi users� guide

James HarlandDavid B� KempTim S� Leask

Kotagiri RamamohanaraoJohn A� ShepherdZoltan SomogyiPeter J� StuckeyJayen Vaghani

Abstract

Aditi is a deductive database system under development at the Collaborative InformationTechnology Research Institute by researchers from the University of Melbourne� This docu�ment is an introductory guide to the Aditi system�

� Introduction

Aditi is a deductive database system under development at the Collaborative InformationTechnology Research Institute by researchers from the University of Melbourne�

This document is an introductory guide to the Aditi system� It is one of four documentsdescribing Aditi� The other documents are�

� �An introduction to the Aditi deductive database system� �� This is an overview ofthe Aditi system� It introduces the concepts behind Aditi and describes its structureas well as its main components�

� �Aditi�Prolog language manual� �� This is a reference manual for the language in whichusers write programs for Aditi and for the interface between Aditi and NU�Prolog�

� �Experiences with a ights database� �� This describes one application of Aditi�

All four documents are distributed together with Aditi� This users� guide assumes familiaritywith the �rst of these documents and provides the background necessary for the second andthird� The manual pages of the commands mentioned in the main body of this guide areavailable online they are also included in the last appendix in this document�

In the examples in this document� input given by the user and the resulting output will be ina typewriter style font� What is input and what is output should be clear from the context�

As Aditi is still undergoing development� some of the tools described in this document areprototypes only and are not complete or robust� Some are implemented as shell scripts� andtherefore are not as fast as they could be�

�

� Getting started

�� Setting up the Aditi environment

Aditi is a multi�user system with its own security mechanisms� The �rst thing one must doto set up Aditi is to create a Unix user account and a Unix group� both named �aditi��

Files whose security should be controlled by Aditi have aditi as their owner and group and�� rw�rw�� as their mode� The relevant Aditi programs are set�group�id aditi� so theyhave full access to the �les of the user invoking them as well as to the Aditi�controlled �les ofother databases� The intention of the Aditi security system is that no ordinary user shouldhave the aditi user�id or group�id not even the database administrator�

The home directory of the aditi user should be the directory in which the Aditi distributionis installed let�s say this is ��users�aditi�� Every Aditi user should have one of the followinglines in his or her startup �les �which one depending on whether he or she uses sh or csh��

�cshrc� setenv ADITI�HOME �aditi

�profile� ADITI�HOME��users�aditi� export ADITI�HOME

This environment variable is used by some Aditi programs to construct paths to other Aditiprograms� scripts are assumed to be located in ��ADITI HOME�bin� and binary executablesin ��ADITI HOME�bin��archname�� The ��archname�� is one of �sgi� and �sun��corresponding to Silicon Graphics �D machines running Irix �� or later� and Sun � seriesmachines� SPARCstations and compatibles running SunOS �� or later� When necessary�Aditi scripts and programs �nd out automatically the type of the machine they are runningon and invoke the corresponding binary executable�

If a stable version of Aditi has its executables in ��users�aditi�bin� and an experimentalversion has its executables in �say� ��users�aditi�exp�bin�� users can choose which ver�sion�s programs they would like to use by setting ADITI HOME to either ��users�aditi� or��users�aditi�exp�� This way� one can set up an environment in which two or more versionsof Aditi programs can coexist�

�� Setting up a server

The heart of Aditi is the process called the query server� This process is responsible forallocating the necessary resources� initializing internal data structures� starting other systemprocesses and then managing their activities� The query server must be running if Aditifacilities are to be available to users�

At startup� the query server consults a con�guration �le that gives the values of a large numberof parameters� The meanings of all these parameters are described in appendix B� The mostimportant parameters are QUERYADDRESS� MUTEXKEY� SHMKEY� and MAPFILE�

QUERYADDRESS ��

�These actions require Unix superuser privilege because they involve the modi�cation of the system �les��etc�passwd� and ��etc�group��

MUTEXKEY ��

SHMKEY ��

MAPFILE �aditi�lib�aditi�map

The �rst three are identi�ers for a message queue� a semaphore and a shared memory segment�respectively these are used for synchronization and communication among the processes ofthe Aditi server�

The MAPFILE parameter gives the name of the authorization �le for the query server� This�le has a one�line entry for every authorized user� Each entry consists of a Unix user name�a string�� the corresponding Aditi user id �a number�� and a ag indicating whether the userhas �Aditi superuser� status �a number nonzero means the user has superuser status�� Aditiuses the superuser ag e�g� for deciding whether a user should be allowed to start or shutdown the query server� This is an example entry�

rao �

There may be several independent query servers active simultaneously even on a machine thathas only one version of Aditi installed on it� Each query server would represent a di�erentincarnation of Aditi�

In a production environment� one would expect to �nd one main incarnation running jobs onthe main database for users and other test incarnations running jobs on small databases forapplication programmers developing new programs� One would expect all these incarnationsto come from the same version of Aditi� In the experimental environment at the Universityof Melbourne and CITRI� each Aditi developer has his own incarnation� which may or maynot run the same version of Aditi as the others�

Each incarnation has a name� The main incarnation on each machine has the name �aditi��If most of the time a user is working on another incarnation� say one named �test�� then heor she should put one of the following commands into a startup �le�

�cshrc� setenv ADITI test

�profile� ADITI�test� export ADITI

All Aditi commands use the ADITI environment variable to select the incarnation they willconnect to� If this environment variable is not set� the default incarnation is the one named�aditi�� Some Aditi commands allow command�line arguments to override this�

Each incarnation has its own con�guration �le whose name is ��aditi�lib��ADITI�con�g�� Bycontrolling write access to the ��aditi�lib� directory� the database administrator can determinethe set of users who are allowed to set up their own incarnations� In a production environment�this directory would be writable only by the database administrator�

Each incarnation may have its own set of authorized users simply by naming di�erent autho�rization �les in the MAPFILE parameter of each con�guration �le� For example� the databaseadministrator can set things up so that an application programmer is superuser for the testincarnation but not for the aditi incarnation�

�

The con�guration �les of di�erent incarnations must always give di�erent values to the pa�rameters QUERYADDRESS� MUTEXKEY� and SHMKEY� If two query servers with thesame values for any of these parameters are ever active simultaneously� they will intercepteach other�s messages and interfere with each other in an unpredictable manner�

�� Starting up the query server

Once you have set up the ADITI HOME and ADITI environment variables and the con�gu�ration and authorization �les� issue the following command as an Aditi superuser�

� aditi start

Aditi Deductive Database System Beta�

Copyright University of Melbourne ��

The selected incarnation is aditi�

Checking for existing query servers ��

None exist�

Starting new query server ��

Query server started�

This command starts the Aditi query server for the incarnation named in the ADITI envi�ronment variable �if any�� You must do this before you can do anything else with Aditi� asother Aditi commands require this query server to be running�

When you have �nished working with Aditi for a while� you can shut down the query serverin an orderly manner by the command

� aditi stop

Aditi Deductive Database System Beta�

Copyright University of Melbourne ��

The selected incarnation is aditi�

Stopping any existing query servers ��

Query server stopped�

This command may not work if Aditi has entered a wedged state �which should be uncommonbut may happen�� In that case� use the command �aditi kill�� which will force a shutdown ofthe query server� Since it does part of its work by sending an uncatchable kill signal to thequery server� the command will work only for the owner of the query server process �the userwho started this incarnation of Aditi� and for the Unix superuser�

�

The command �aditi start� checks whether a query server is already running for the requiredincarnation� If yes� then the new query server would interfere with the existing one in anunpredictable �but probably disastrous� manner� so �aditi start� just prints an error messageand exits� If you want to guarantee the creation of a new query server� use the command�aditi �f restart�� which will stop� and if necessary kill� any existing query server�s� beforestarting a new one� A plain �aditi restart� will try to stop an existing query server but willnot kill it� or start a new one� if orderly shutdown fails�

For the remainder of this guide� we will assume that the ADITI environment variable is setand that the selected incarnation has a query server running�

�� Setting up a database

The next thing to do is to create a database� This is done via a command such as thefollowing

�� newdb �users�aditi�example

Aditi �� Create Database s�

newdb� creating database �users�aditi�example ��

created dictionary for �users�aditi�example�db

Inserting standard schemas ��

newdb� creation of database �users�aditi�example completed

This command will create the directory ��users�aditi�example� if it does not already exist�It will then create two subdirectories �db� and �rl� within it�

The �rl� subdirectory will initially be empty� Later� it will contain Aditi object �les givingthe de�nitions of derived predicates �see section �� The name of the directory is �rl� becausethe object code is a bytecode version of RL� the Aditi Relational Language�

The initial contents of the �db� subdirectory are housekeeping relations used by Aditi itself�

� The data dictionary pseudo�relation contains information about schemas and relationscreated by users� Its initial contents are descriptions of a standard set of schemasinserted by newdb�

� The predmode library relation contains information about what relations are callable inwhich modes �adornments�� It initially contains information about the system relations��For the de�nition of modes� see the Aditi�Prolog language manual��

� The rlregister relation contains a list of the derived relations of the database� For eachderived relation� it states where in the �rl� subdirectory the RL code de�ning it islocated� It is initially empty�

�

Later� the �db� subdirectory will also contain all the base relations in the database�

Because most of the time one works with the same database� most Aditi commands do notneed a database to be speci�ed on the command line if the ADITIBASE environment variableis set� It is therefore a good idea for Aditi users to include lines like the following in theirstartup �les�

�cshrc� setenv ADITIBASE �users�aditi�example

�profile� ADITIBASE��users�aditi�example� export ADITIBASE

Query servers and RAPs can access more than one database at a time e�g� a RAP can jointwo relations from two distinct databases� This capability was designed into Aditi because ina production environment we want to allow Aditi users to keep their own relations under theirown control while still being able to compute with them as conveniently as if they belongedto the main database� At the moment� this functionality is inaccessible to users� as the queryshell can only access one database at a time� This restriction will be lifted in the future�

In the current version of Aditi� there is nothing to stop multiple query servers from accessingthe same database at the same time� If this ever happens� the results are unpredictable �butunlikely to be what you would want��

� Managing base relations

In this section we will describe the Aditi facilities for managing base relations derived relationsare the subject of section �� We will use as a running example a toy version of a ights databasethat a travel agent might use� We assume that the ADITI HOME� ADITI and ADITIBASEenvironment variables and the relevant con�guration and authorization �les have been set upappropriately and that the query server is running� If any one of these assumptions is nottrue� all invocations of the commands shown below will fail�

Failure messages from the current version of Aditi specify only an error number� Thesenumbers are always negative� Error numbers between � and �� come from Unix systemcalls other numbers �all negative� come from Aditi itself� To convert an error number to thecorresponding string� use the command �aerr �errno�� For example�

�� aerr ��

SI NOSERVER �� No server running

The minus sign on the command line is optional�

At the moment� this is the main facility for diagnosing problems caused by improper useof Aditi commands and for tracking down problems with Aditi itself� The other debuggingfacility in Aditi� which traces the execution of Aditi�Prolog programs� is described in theAditi�Prolog language manual� To paraphrase Brian Kernighan� from this information �theexperienced Aditi user will usually know what�s wrong��

�

�� Creating a relation

The command for creating a base relation is �newrel�� For example� to create a relation tostore the location of the headquarters of each known airline� issue the command�

�� newrel hq

Creating relation hq in �users�aditi�example

using schema flex� and index type data ��

Created hq� in �users�aditi�example with

index type data and schema flex�

Creation completed�

The �rst argument gives the name of the relation being created� while the second gives�directly or indirectly� the name of the schema that determines the shape of the new relation��Aditi�s notion of a schema resembles but is not identical to the notions of schemas commonin relational database systems�� In this case� the second argument is a number �an arity�� sothe newrel command converts it into a schema name by inserting the pre�x �ex�� Thus thearity �� is a shorthand for the schema name �ex��

�� Creating a schema

A schema gives three things� an arity� a tuple type� and a list of key attributes� The arity isstraightforward� In the current version of Aditi the tuple type must be �ex� later versionswill support ��xed� and �free� as well� Flexible tuples are the most general� each attributecan be an arbitrary term� and thus an arbitrary size� In �xed tuples each attribute has aprede�ned type and �xed size they will be implemented when we add typechecking to Aditi�Prolog� Free tuples are intended for the storage of compiled RL procedures in Aditi relations currently these are stored in a separate set of Unix �les� The list of key attributes is currentlyused only when the relation has a B�tree index� the list provides the ordering function� andoptionally prevents the inclusion of duplicates�

When it creates a new database� the newdb command inserts into the new data dictionary notonly the schemas needed for Aditi�s standard internal relations but also several schemas thatare intended to be generally useful� These latter schemas have the names �ex�� ex��etc through to �ex�� Each has the tuple type and arity implied by the name� The key listconsists of just attribute � �default indexing on the �rst argument being a logic programmingtradition��

The default key list is appropriate for the hq relation as we assume that each airline has justone headquarters� But suppose we wanted to create a relation to record information aboutcity�pairs that are connected by direct ights� We would need the key of this relation toconsist of both attributes� We would need a schema that is just like ex� except that its keyattribute list is �� instead of just �� The command to create such a schema is�

�� newschema flight flex �

�

Aditi �� Create Schema

Creating schema flight in �users�aditi�example ��


You can verify that the de�nition of ight made it into the data dictionary by displaying thecontents of the data dictionary�

�� showdict

Aditi �� Show Dictionary Information

Aditi Dictionary Information for ��users�aditi�example�db��

Relations

��

hq� Schema� flex� Index type� Data

predmode�� Schema� predmode�� Index type� BTree

rlregister� Schema� flex� Index type� BTree

Schemas

��

flex�� Type� Flexible Arity� � Key Attributes�

flex� Type� Flexible Arity� Key Attributes�



��




��


flight Type� Flexible Arity� Key Attributes� �

predmode�� Type� Flexible Arity� � Key Attributes� �

Display completed�

Now you can create the relation itself�

�� newrel flight flight

Aditi �� Create Relation

�

Creating relation flight in �users�aditi�example

using schema flight and index type data ��

Created flight� in �users�aditi�example�db with

index type data and schema flight


�� Creating an indexed relation

The type of indexing to use on a new relation can be speci�ed explicitly as the fourth argumentof newrel� If this argument is missing� the default index type is �data�� so the immediatelyprevious command is equivalent to�

�� newrel flight flight data

The word �data� indicates that the relation should have no index the mnemonic is that thedata is its own index�

Note that there is no way to alter the type of indexing on a relation whatever indexing isestablished by newrel will serve for the lifetime of the relation�

Aditi currently supports three true indexing methods� unsorted data �les with a B�tree index��btree�� and two versions of multikey hashed �les with superimposed keyword �ltering�intended for �les with static ��simc�� and dynamic ��dsimc�� sizes� Future versions of Aditiwill support other indexing methods as well�

To create a relation with a B�tree index� execute a command like this one�

�� newrel flight flight btree � ��

Aditi �� Create Relation

Creating relation flight in �users�aditi�example

using schema flight and index type btree ��

Created flight� in �users�aditi�example�db with

index type btree and schema flight


The �rst three arguments are the relation�s name� its schema� and the type of its index� asbefore� The remaining arguments are the parameters of the indexing method� For B�trees�these are �in order� the minimum blocking factor� the block size� and a �duplicates� ag�Aditi�s B�trees have variable size nodes� The size of the smallest nodes is the minimumblocking factor times the block size� while the largest nodes will be one block short of twicethat size� For example� the command above would create a B�tree whose nodes range from �to � kilobytes in size�

�

The records stored in the nodes of the B�tree index contain the values of the key attributesof the relation �taken from the schema speci�ed for the relation� together with a pointeror pointers to the records that have that combination of key attribute values� The B�treeindex is ordered on the internal representations of the values of the key attributes� Sincethe internal representations of two key values do not necessarily compare the same way astheir printed representations� a listing of a B�tree indexed relation �via the seerel commandintroduced below� is not necessarily sorted the way a human would expect them to be� Thekey attributes are used mainly for clustering and making it easier to detect duplicates� Theduplicates ag says whether or not two tuples with the same key may exist in the relation any nonzero number means yes �nonzero numbers therefore mean that Aditi�s �keys� are notreally keys in the usual sense��

To create a relation with a superimposed codeword index� execute a command like this one�

� newrel hq simc � �� g��g��aaaaaaaa�

The arguments after �simc� are the parameters of the simc indexing scheme� They give theexpected average size of tuples �including Aditi�s overhead�� the expected number of tuplesin the relation� the size of each block ��segment� in simc terminology�� and a fact templatewith further indexing parameters� �The quotes are needed to protect the template frominterpretation by the shell��

A relation with a simc index will have its data in one Unix �le and the index in another �le�The data �le is divided into segments� To cluster related tuples together� Aditi computesthe number of the segment to put a tuple into by multikey hashing� The index �le has asuperimposed codeword descriptor for each segment in the data �le� The descriptors arestored in a bit�slice fashion� �rst bit � from all descriptors� then bit � from all descriptors�and so on� This optimizes the speed of retrieval of the desired descriptor bits� but imposesa maximum size on the descriptor �le� The simc indexing method thus imposes a maximumsize on the relation as well this size is the product of two simc parameters� the expectedaverage size of each tuple and the expected number of tuples in the relation�

The dsimc indexing scheme has the same set of parameters� Beside a main data �le and anindex �le� a dsimc relation may also have one or more overow �les dsimc uses recursivelinear hashing as its overow policy �simc uses rehashed open addressing� so overow tuplesare stored in the data �le itself�� The main di�erence between simc and dsimc is that in adsimc index �le� all the bits of a descriptor are stored together� The index �le thus imposesno limit on the size of the relation� and the relation can therefore grow as necessary�

Both simc and dsimc use the template parameter to tell them how to construct superimposedcodewords and exactly how to perform multi�key hashing� The template is a list of termswith the function symbols replaced by a three�tuple giving weight and clustering information�The �rst element of the tuple is a �g� or �v� indicating whether facts will ever have variablesin that position� In the current version of Aditi� facts must always be ground� so this elementshould always be �g�� The second element indicates the relative likelyhood that the givenpart of the term will be speci�ed in queries on the relation this governs how many bits inthe superimposed codeword will be derived from the function symbol �if any� in this part ofthe term� The third element is a hexadecimal representation of a ��bit number it gives thebits of the choice vector �see below� to be allocated to a function symbol in this position�

��

Applying the �or� operation to all the third elements together should give a ��bit binarynumber consisting of all ones applying the �and� operation to any two third elements shouldgive all zeroes�

Each term in the template stands for the corresponding argument of the relation being created�These terms may have functions symbols of arity greater than zero� For example� you maywish to use this template for indexing the hq relation�

g��g�� g��g��

This states that the second argument of a tuple inserted into the relation will be expectedto be a function symbol of arity two� and it assigns weights to the arguments of the functionsymbol as well as to the function symbol itself� thus providing indexing on the �rst�levelelements of the term �the city and the country in the example below� as well as the surfaceelement� Inserted tuples may have deeper structure than the template� and may also havefunction symbols of arity greater than the template provides for the excess elements in thetuple are not used for indexing� Similarly� the relation may have an arity greater than thetemplate provides for the unrepresented arguments are not used for indexing� If a tuplebeing inserted is smaller than the template� the tuple is indexed as if the missing elementshad default values�

Simc and dsimc do not pay attention to key attributes� nor do they detect or eliminateduplicate tuples� This will be �xed in a future version of Aditi�

If you need more information about superimposed codeword indexing methods in general� forexample an explanation of what choice vectors are� read ��

�� Inserting data into a relation

The newrel command of course creates empty relations� The command to insert tuples intorelations is �newtups��

� newtups flight

Aditi �� Add Tuples

sydney� honolulu

honolulu� toronto

sydney� melbourne

melbourne� honolulu

� D

� tuple s� inserted

Addition completed�

To the newtups command� and to all other Aditi commands except newrel� relations areidenti�ed by name and arity�

��

The next example shows that you can insert complex terms into Aditi relations and thatthere are no restrictions on the structure of these terms� e�g� you can use both of the functionsymbols city�� and city��

�� newtups hq

Aditi �� Add Tuples

qantas� city sydney� australia�

delta� city atlanta� usa�

cathay pacific� city hongkong�

lufthansa� airport frankfurt�

� D

� tuple s� inserted

Addition completed�

A later version of Aditi will probably implement type checking�

The input data to newtups should have no blank lines� and no white space at the end of aline� The data itself must have the following properties�

� Aditi does not currently allow variables to be stored in base relations� so the input tonewtups must consist of ground terms� Each line of the input gives a comma�separatedlist of the attributes of the ground fact to be inserted�

� Attribute values that are complex terms �i�e� have functions symbols of arity � �� mustbe in pre�x form� Unfortunately� this includes lists� a list such as �a� b� c� must bewritten as � a� � b� � c� � ��

� Following the Prolog convention� function and constant symbols must start with alower case letter� However� any string of characters between single quotes� e�g� �JohnSmith� can be used as a function or constant symbol�

� Aditi strings consist of arbitrary characters enclosed within double quotes� Aditi storesstrings the same way as constant symbols� but they are a di�erent kind of object� thestring �John Smith� does not unify with the function symbol �John Smith� � In a futureversion of Aditi� strings will unify with lists of characters� Since they currently don�t�Aditi�Prolog strings are di�erent from NU�Prolog strings� and so there is no way toissue a query that speci�es an Aditi string as the value of an attribute �see section ��

If a tuple is being inserted into a relation that has a btree index and a zero duplicates ag�and the tuple agrees in its key attributes with a tuple already in the relation� newtups willprint a message and ignore the tuple� This checking is not �yet� performed when insertinginto other types of relations�

�

�� Looking at the contents of a relation

To check that the tuples you wanted were inserted correctly into the hq relation� use thecommand

�� seerel hq

Aditi �� See relation

Relation name� hq

Arity� Cardinality� �

Nkeys� Ntkeys� � TupSorted� �

� cathay pacific� city hongkong�

� qantas� city sydney� australia�

�� lufthansa� airport frankfurt�

�� delta� city atlanta� usa�

Display completed�

The Arity and Cardinality �elds should be self�explanatory� The Nkeys �eld gives the numberof keys of the relation according to its schema it does not say which attributes those keysare� When sorting a relation� the RAP modi�es each tuple by copying the sort keys to thefront of the tuple this way� two tuples can be compared very e�ciently �using an inlinedvariant of strncmp that works on words� not bytes�� The Ntkeys �eld gives the number ofthese temporarily prepended keys� The TupSorted �eld is non�zero if the relation has beensorted and duplicates removed�

Permanent relations are usually not the result of RAP operations� thus Ntkeys and TupSortedwill usually be zero�

�� Deleting data from a relation

The simplest way to delete tuples from a relation is via the �deltups� command�

�� deltups hq

Aditi �� Delete Tuples

delta� city atlanta� usa�

� D

tuple s� deleted

Deletion completed�

The input to deltups is in the same format as used by newtups� a list of tuples� one per line�In the current version� the tuples must be ground� i�e� one cannot specify patterns such as�Airline� city�hongkong��

Deltups does not quite act as an inverse to newtups� If the relation has two or more copies of agiven tuple� deltups will delete all copies� This is consistent with the idea that Aditi actuallyimplements set semantics� but represents sets as multisets for implementation reasons�

��

Deleting say ten tuples from a non�indexed ��data�� relation would require ten scans ofthe whole relation� At the moment� deltups therefore works only for relations with a true�non��data�� index� However� this is not too important a limitation� as this functionality isavailable through the query shell �see section ��

To delete all the tuples in a relation� using deltups is ine�cient� Use the �clearrel� commandinstead�

�� clearrel hq

Aditi �� Clear relation

Clearing hq� in �users�aditi�example ��

Clearing completed�

clearrel works even for relations with index type data�

Aditi does not allow tuples to be modi�ed directly� If you wish to do so� you must delete thetuple and insert the new version�

�� Deleting a relation

To actually delete a relation� use the command �delrel��

�� delrel hq

Aditi �� Delete Relation

Deleting hq� from �users�aditi�example ��


The command marks the relation hq� for deletion the actual deletion of the data in therelation will occur when the last Aditi process that currently has the relation open closes its�le descriptor� The relation�s entry in the data dictionary will be deleted immediately� sothat the relation hq� will not exist from the point of view of Aditi jobs that start after delrelhas �nished its task�

Aditi will not let you delete the system relations predmode and rlregister�

�� Deleting a schema

To delete a schema� use the command �delschema��

�� delschema flex��

Aditi �� Delete Schema

��

Deleting schema flex�� from �users�aditi�example ��


The schema ex�� will cease to exist� There is no delay involved�

Aditi will let you delete the schemas of existing relations� even the schemas of system relations�Nothing untoward will happen� The reason is that an Aditi relation requires its schema toexist only at the time that the relation is created� At that time� the relevant information iscopied into the data dictionary record of the relation�

�� Security

Aditi implements a simple security system� Base relations newly created by newrel are acces�sible only to the user who created them� who is called the owner of the relation only this usercan read the relation� write to the relation and delete the relation� The owner of the relationcan however grant these rights to other users via the command aditiperms� This commandgrants all users read access to the relation ight��

�� aditiperms �read flight�

Aditi �� Change�Show Relation Permissions

Changing permissions for flight� in �users�aditi�example ��

Permissions are now�

Owner Id� �

Relation Type� User

public read� yes

public write� no

public delete� no

superuser delete� no

Change Permissions completed�

The �rst two arguments of aditiperms specify the relation� The rest of the command can be��read�� read�� write� or ��write� to grant to or revoke from all users the right to readfrom or write to the relation� The two rights are not independent� the right to write to arelation implies the right to read from it� There is currently no provision for granting reador write access to selected users or groups� either only the owner has e�g� read access� or allusers do�

With respect to the right to delete a relation� users are classi�ed into not two but three classes�the owner of the relation� Aditi superusers� and others� The owner always has the right todelete his or her own relation� and he or she can grant the right separately to the two otherclasses of users� via commands such as�

�� aditiperms �delete superuser flight�

��




Owner Id� �


public read� yes

public write� no

public delete� no

superuser delete� yes


� aditiperms �delete public flight�




Owner Id� �


public read� yes

public write� no

public delete� no

superuser delete� yes


Only the owner of a relation can change the permissions on that relation� but every user canhave a look at what those permissions are�

� aditiperms show flight�


Showing permissions for flight� in �users�aditi�example ��

Owner Id� �


public read� yes

public write� no

public delete� yes

superuser delete� no

Show Permissions completed�

For implementation reasons� Aditi stores the identity of the owner of a relation in terms oftheir Aditi user id� as shown by the output of the commands above� Since di�erent Aditi

��

incarnations can have di�erent authorization �les� the security system requires the databasemanager to ensure that all authorization �les agree on the Aditi user id of each Unix user�

The current version of Aditi does not provide security for schemas� since the the copying ofschemas at relation creation time means that none is needed� The current version of Aditialso does not provide security for derived relations�

� Managing derived relations

So far we have talked only about base relations� However� the power of deductive databaseslies in derived relations� relations that can infer information at run�time� In Aditi� users de�nederived relations by writing programs in Aditi�Prolog� a pure �declarative� variant of Prologaugmented with mode declarations and with ags to control the Aditi�Prolog compiler� The�le �stops�al� is an example�

�� mode stops f�f�f��

�� flag stops� �� diff��

stops Origin� Destination� ��

flight Origin� Destination��

stops Origin� Destination� �Stop�Stoplist��

flight Origin� Stop��

stops Stop� Destination� Stoplist��

not in�list Stop� Stoplist��

�� mode in�list f�b��

�� flag in�list� � magic��

�� flag in�list� � diff��

in�list Head� �Head��Tail��

in�list Item� �Head�Tail��

in�list Item� Tail��

This code fragment declares two predicates �derived relations�� The �rst gives all possibleroutes between all city�pairs� routes are represented as lists of intermediate stops� Thisrelation can be queried with all variables being free� The second relation checks whether its�rst argument is a member of the list that is its second argument the query must completelyspecify �i�e� ground� the second argument� Aditi will use di�erential �semi�naive� evaluationwhen answering queries on both relations� For in list� it will use the magic set optimizationas well� �Actually� the di� ags can be omitted� as di�erential evaluation is the default��

For further details of the language� see the Aditi�Prolog language manual�

�� Compiling AditiProlog programs

The Aditi�Prolog compiler is called �apc�� Its interface is intentionally similar to the interfaceof other compilers on Unix systems� e�g� cc� As arguments� one just names the �les to be

��

compiled�

�� apc stops�al

Aditi�Prolog Compiler ��

Compiling stops�al ��

�� Compiler Statistics ��

Read�� Mode�� HdsHds�� Strata��

Compile�� LdsLds�� LdsRL��

Compilation finished

By a convention enforced by the compiler� source �les containing Aditi�Prolog programsmust have the su�x ��al� �derived from ��pl� and ��nl� for Prolog and Nu�Prolog programs the initial letter of course stands for Aditi�� Apc leaves the corresponding object programin �stops�ro�� the su�x standing for �relational object� �le� This object program is in abytecode version of RL� the Aditi relational language� It also creates the �le �stops�rm��which contains information about the modes and ags of the predicates that can be evaluatedusing �stops�ro�� If �stops�al� contains directives that declare some predicates de�ned in it tobe accessible from NU�Prolog programs� apc will also create the �le �stops�nl� and will �ll itwith the necessary interface routines� �For further details on the Aditi�NU�Prolog interfacesee the Aditi�Prolog language manual��

The compiler statistics report user and system time in milliseconds for each part of thecompiler �the times accurate at most to the resolution of the system clock��

�� Compiling RL programs

Although we do not recommend it for the faint�hearted� one can also write programs directlyin RL� We do it to try out new evaluation methods and query optimizations�

One can write RL programs starting from scratch� but we recommend against this approach�To be really useful� a hand�written RL procedure must be able to call other RL proceduresand must be callable by them this means that it must have an entry in a ��rm� �le and thatit must obey the naming and argument�passing conventions established by the compiler�

The simplest way to ensure this conformance is to make the compiler do this part of the work�One writes an Aditi�Prolog program� and compiles it with the command�

�� apc �S stops�al

The �S ag tells apc that the output RL program should not be the bytecode �stops�ro��le but the human readable �stops�rs� �le �the option and the name su�x are both derivedfrom the Unix convention for dealing with assembler� since RL plays the same role in Aditias assembler does in conventional language systems�� One can then modify �stops�rs�� andgenerate �stops�ro� from it via the command�

��

�� apc stops�rs

Assembling stops�rs ��

Compilation finished

If you are interested in looking at the RL code but don�t wish to modify it� use �apc �l�� itgenerates a ��rs� �le as well as ��ro� and ��rm� �les�

�� Registering derived relations

Before a newly created ��ro� �le can be used by all users of a database to help answer queries�it must �rst be registered in �i�e� made known to� the database� The command for doing thisis�

�� newderived stops�ro

Registering file stops�ro in �users�aditi�example

Registration completed�

This copies �stops�ro� from the current directory to the �rl� subdirectory of ��ADITI HOME��and puts the mode information from �stops�rm� into the predmode system relation� The latteraction allows other Aditi�Prolog predicates to refer to the predicates de�ned in �stops�ro��

One normally wouldn�t register �stops�ro� until after the code in it has been tested and foundto be OK� One can test unregistered derived relations using the �load� command in the queryshell �see section �� However� someone working with a personal test database may want toautomatically register untested ��ro� �les in it� so the compiler can be told via the �r optionto register every ��ro� �le it generates�

�� apc �r stops�al

Aditi�Prolog Compiler ��

Compiling stops�al ��

�� Compiler Statistics ��

Read�� Mode�� HdsHds�� Strata��

Compile�� LdsLds�� LdsRL��

Registering file stops�ro in �users�aditi�example

Registration completed�

At the moment there is no concurrency control on derived relations� so the reregistration of aderived relation is safe only if nobody is using �stops�ro� at the moment� The same provisionapplies when one wants to deregister a ��ro� �le�

�� delderived stops�ro

Deregistering file stops�ro from �users�aditi�example

Deregistration completed�

��

� Querying the database

In a production environment� we would expect that most users� interaction with Aditi wouldconsist mainly of asking queries� They would therefore spend most of their time with thequery shell�

The query shell has two slightly di�erent user interfaces� One is part of xaditi� the graphicalfront�end to Aditi �see section �� The other� which is described in this section� is for usefrom dumb terminals and from workstation windows running terminal emulation programs�e�g� xterm and xwsh�� This version is started via the command

�� qsh

Aditi �� Copyright �� The University of Melbourne�

Aditi DAP Version � RL Version �

Login successful

Login name� zs Database Id� � User Id� ��

Current Database set to� �users�aditi�example

Aditi Query Shell � type ��help�� for help�

��

Before it can do anything else� the query shell must log the user into Aditi� i�e� presenthis�her credentials to the query server for checking� If this checking is successful� qsh printsas con�rmation the login name of the invoker and his�her numeric ids for Aditi and for Unix��The login process is actually performed by the Database Access Process or DAP created bythe query shell��

The user interface of the query shell is very similar to the user interface of NU�Prolog� thereason being that the query shell is a NU�Prolog program� The most important consequenceof this is that the history features of NU�Prolog are available in the query shell�

h� Displays the history list� i�e� the queries asked so far�

�� Asks query � again�

e �� Runs an editor on the text of query �� and takes the new contents of the edited �leto be your next query�

s �le� Saves the history list in the named �le�

r �le� Adds the queries in the named �le to the history of the current session� This isparticularly useful during demos� as it allows prepared queries to be invoked simplyby giving their number�

�

Queries can be made in a similar way to how they are made using NU�Prolog� and theirsyntax is mostly the same �e�g� spaces are not signi�cant except around potential operators�all queries must end with a dot� etc�� However� the query shell�s query language is currentlyrestricted to conjunctions and disjunctions of literals� queries cannot �yet� contain implicationor quanti�ers�

�� Asking queries

The simplest kind of query is an open query on a single atom� This one asks for the head�quarters of all known airlines�

�� hq Airline� Headquarters��

Answer Set for Airline� Headquarters�

� cathay pacific� city hongkong�

� qantas� city sydney� australia�

�� lufthansa� airport frankfurt�

Specifying some constants causes Aditi to perform a selection� This query asks for the head�quarters of Qantas�

�� hq qantas� Headquarters��

Answer Set for Headquarters�

� city sydney� australia�

Note that the answer relation is now of arity �� not � Each column in an answer relationrepresents a variable in the query� the heading states which variable corresponds to whichcolumn�

If the query contains no variables� then the result is a zero arity relation� If the answer tosuch a query is �true�� then the answer relation will have cardinality one� it will contain thespecial tuple ��true�� Otherwise the answer relation will have a cardinality of zero� In ourexample database� there is a direct ight from Honolulu to Toronto but not from Sydney toToronto�

� �� flight honolulu� toronto��

Answer Set�

�true

� �� flight sydney� toronto��

Answer Set�

�

No Answers

Queries that contain conjunctions implicitly ask for joins� This one asks for all possibleone�stop trips�

� �� flight Orig� Stop�� flight Stop� Dest��

Answer Set for Orig� Stop� Dest�

� sydney� honolulu� toronto

� sydney� melbourne� honolulu

�� melbourne� honolulu� toronto

Queries that contain negation implicitly ask for a set di�erence operation� This one asks forall city�pairs that have one�stop ights but no direct ights between them�

� �� flight Orig� Stop�� flight Stop� Dest�� not flight Orig� Dest��

Answer Set for Orig� Stop� Dest�

� melbourne� honolulu� toronto

� sydney� honolulu� toronto

If you are interested only in the origin and destination cities� and not in the location ofthe intermediate stop� you can tell Aditi to project the result relation onto the variablesrepresenting those cities�

� �� Orig� Dest� flight Orig� Stop�� flight Stop� Dest��

not flight Orig� Dest��

Answer Set for Orig� Dest�

� melbourne� toronto

� sydney� toronto

Anonymous variables �whose name is a single underscore� are automatically projected out ofall queries�

Queries can include arithmetic calculations as well as comparisons� If we have a relation thatrecords the distance between city�pairs� we can ask queries such as�

� �� Orig� Dest� D� flightdist Orig� Stop� D�� flightdist Stop� Dest� D��

D �� D is D � D�

Answer Set for Orig� Dest� D�

� sydney� toronto� ��

� melbourne� toronto� ��

This asks for the total length of all one�stop trips where the �rst leg is longer than ��kilometers�

Queries can even include disjunctions �represented by semicolons� and grouping to overrideprecedence �negation highest� then conjunction� then disjunction��

� �� Orig� Dest� flight Orig� Dest� � flight Orig� Stop�� flight Stop� Dest��

not flight Dest� melbourne��

Answer Set for Orig� Dest�

� sydney� honolulu

� sydney� melbourne

�� sydney� toronto

�� honolulu� toronto

�� melbourne� honolulu

�� melbourne� toronto

This asks for all city pairs with non�stop or one�stop ights where there is no direct ightfrom the destination to Melbourne� The explicit projection is essential� without it� the queryshell would try to include the variable Stop in the answer relation� and would fail becauseStop exists in only one arm of the disjunction� In the terminology of modes� Stop has noproducer in the other arm�

In Aditi derived relations may be queried the same way as base relations the �rst reference toa derived relation causes its RL object code to be loaded into the DAP� The next two queriesboth ask for all cities that are reachable from sydney but to which there are no direct ights�

� �� stops sydney� Dest� �� not flight sydney� Dest��

Procedure file ��users�aditi�example�rl�stops�ro has entries�

Loading stops �

Loading in list

Answer Set for Dest�

� toronto

�� stops sydney� Dest� �� not stops sydney� Dest� ��


� toronto

�

The second of those queries demonstrates that like base relations� derived relations can alsoappear inside negation� For the users� point of view� the only di�erence between base andderived relations is that derived relations do not have to support all modes� As their modedeclarations in section � indicate� the derived relation stops does support all modes� but thederived relation in list does not�

�� stops Orig� Dest� Stops��

Answer Set for Orig� Dest� Stops�

� sydney� toronto� �melbourne� honolulu�

� sydney� toronto� �honolulu�

�� sydney� honolulu� �melbourne�

�� sydney� honolulu� ��

�� sydney� melbourne� ��

�� melbourne� toronto� �honolulu�

�� honolulu� toronto� ��

�� melbourne� honolulu� ��

� �� in list Member� List��

QSH ERROR �� Query is impossible no mode �f� f� for in list�

QSH ERROR �� Invalid query in list FPVKB� FPVKW�

Queries may also involve aggregate operations�

� �� aggregate Set � solutions Dest�� Orig�� stops Orig� Dest� Stops��

Answer Set for Orig� Set�

� honolulu� �toronto�

� melbourne� �honolulu� toronto�

�� sydney� �melbourne� honolulu� toronto� honolulu� toronto�

Note that the set of destinations for Sydney contains two copies of Honolulu and Torontobecause there are two distinct routes to both of those cities�

Besides solutions� the min� max� sum and count aggregate operations are also available� Formore details on aggregates� see the Aditi�Prolog language manual�

�� Assignments and updates

The query shell allows the result of a query to be assigned to a temporary relation that lastsfor the remainder of the current query shell session� This query asks for all destinationsreachable from Australia using a relation that associates cities with their countries�

� �� Dest� country Orig� australia�� stops Orig� Dest� Stops��

�


� honolulu

� melbourne

�� toronto

This one asks for the same data� but also tells the query shell to put the data into a newtemporary relation called aust dest� from which it can later be retrieved�

� �� aust dests Dest� �� country Orig� australia�� stops Orig� Dest� Stops��


� honolulu

� melbourne

�� toronto

� �� aust dests Dest��


� honolulu

� melbourne

�� toronto

The new relation� like all temporary relations in the current version of Aditi� is a at �le� i�e�it has no true index� Its schema is ex�n where n is its arity� The attributes are given bythe arguments following its name� Variables occurring in the query on the right hand sideof the �� that do not occur among those attributes are automatically projected out� Theattributes may include constant and function symbols�

� �� dests aust� from Orig�� Dest� ��

country Orig� australia�� stops Orig� Dest� Stops��

Answer Set for aust� from Orig�� Dest�

� aust� from sydney�� honolulu

� aust� from sydney�� melbourne

�� aust� from sydney�� toronto

�� aust� from melbourne�� honolulu

�� aust� from melbourne�� toronto

For queries that create new relations� the answer set is the new relation� so the query shellsdisplays even the columns corresponding to constants in the relation template� e�g� �aust��

�

aust dests and dests are new base relations� Once computed� they no longer depend on thecountry or stops relations� The contents of aust dests will not change even if someone addsnew tuples to ight and thus indirectly to stops� To de�ne a relational view that instantlyreects changes� you need to de�ne� compile and register a derived relation� The stops relationis such a view on the ight base relation�

Once a temporary base relation is de�ned� its contents are frozen� in the current version ofAditi� temporary relations cannot be updated� Permanent base relations of course can be�either via the commands newtups and deltups or via the query shell� The next two queriesredirect a ight from Toronto to Montreal� Each reports the tuple being deleted or inserted�

� �� flight honolulu� toronto� �� true�

Deleting answers from flight�

Answer Set for honolulu� toronto�

� honolulu� toronto

� �� flight honolulu� montreal� �� true�

Inserting answers into flight�

Answer Set for honolulu� montreal�

� honolulu� montreal

These queries illustrate the simplest way to insert or delete single tuples� In general� the righthand side of an update operator can be an arbitrary query� Aditi will answer this query�and use the solutions to provide bindings for the variables appearing in the left hand side� Ifthese variables have more than one binding in the solutions� then Aditi will insert or deletemore than one tuple� For example� this query states that every city that has a direct ightto Montreal now also has a direct ight to Toronto�

�� flight Origin� toronto� �� flight Origin� montreal��

Inserting answers into flight�

Answer Set for Origin� toronto�

� honolulu� toronto

As our example database has only one ight to Montreal �the one we just inserted�� this justundoes our earlier removal of the ight from Honolulu to Toronto�

The assignment operator doesn�t work for permanent relations� The reason is not that Aditican�t support this functionality �it can�� but rather that it is too easy to make mistakes� Thisquery would remove all ights except ights to Toronto from cities that �used to� have ightsto Montreal�

�

�� flight Origin� toronto� �� flight Origin� montreal��

QSH ERROR �� Cant assign to old relation flight�

QSH ERROR �� Invalid query flight FPVLI� toronto� �� flight FPVLI� montreal�

The rule is� temporary base relations can only be assigned� permanent base relations can onlybe updated�

�� Testing derived relations

Derived relations �e�g� the stops relation above� should be tested before being registeredand thus made available to all users of a database� Suppose that the initial draft of thede�nition of the stops relation �and the in list relation that it needs� is in the �le �stops�al�in the current directory� which is ��users�aditi�examples�� Testing this de�nition requirescompiling �stops�al� with apc �this generates �stops�ro� and �stops�rm�� invoking the queryshell� and loading �stops�ro� and �stops�rm� into the query shell�

�� load ��users�aditi�examples�stops��

loading file ��stops�ro��

Procedure file �stops�ro has entries�

Loading stops �

Loading in list

Since the current directory is ��users�aditi�examples�� we could have given just �stops� asthe argument of the load� and since stops is an acceptable Prolog term� we could then haveomitted the quotes as well�

The load command echoes the names of the RL procedures in �stops�ro� as they are loadedinto the query shell� or more precisely� into the DAP that supports the query shell� Thenaming convention followed by the compiler is to create the name of an RL procedure bytaking the name of the predicate and adding �rst its arity and then the number of the modethat this RL procedure implements� � Underscores separate the name components to preventproblems such as the name of the RL procedure implementing p�� clashing with the nameof the RL procedure implementing p��

The load command also looks at the �le �stops�rm�� and loads the declarations in it into thequery shell proper� This can be veri�ed by the command�

�� decs�

These mode declarations are in force�

�predmode ��in list�� diff� magic�� m � m� i� �f� b��

predmode ��stops�� diff�� m � m� i� �f� f� f��

For each predicate in �stops�al�� stops�rm� and hence decs gives its name� arity� the ags itwas compiled with and information about its modes� The query shell really needs only the

�The reason why we do not append the b�s and f�s instead of the mode number is that we intend later toimplement a strong mode system that allows partially instantiated terms�

�

mode information� A modelist entry such as �m�� m� i� �f� f� f�� says that mode number � hasbeen made �i�e� RL code has been generated for it�� and that this mode is internal to Aditi �i�e�it is inaccessible from NU�Prolog applications�� and that it corresponds to the instantiationpattern �f� Armed with this information� the query shell can convert an instantiation patterninto a mode number� which is part of the process of converting a predicate name in an Aditi�Prolog call into the name of the RL procedure implementing that call� One can verify thisby asking a query on a loaded procedure�

� �� stops Orig� Dest� Stops��

Answer Set for Orig� Dest� Stops�

� sydney� toronto� �melbourne� honolulu�

� sydney� toronto� �honolulu�

�� sydney� honolulu� �melbourne�

�� sydney� montreal� �melbourne� honolulu�

�� sydney� montreal� �honolulu�

�� sydney� honolulu� ��

�� sydney� melbourne� ��

�� melbourne� toronto� �honolulu�

�� melbourne� montreal� �honolulu�

�� honolulu� montreal� ��

� honolulu� toronto� ��

� melbourne� honolulu� ��

Even though stops is not declared to have a mode b�� the existence of this mode is impliedby the mode �f� One can thus ask for the destinations reachable from Melbourne togetherwith the intermediate stops required�

� �� stops melbourne� Dest� Stops��

Answer Set for Dest� Stops�

� toronto� �honolulu�

� montreal� �honolulu�

�� honolulu� ��

The query shell implements this by computing the whole stops relation using the �f modeand then selecting just the trips starting from Melbourne� This is the best that can be doneif stops is compiled only in mode �f� For better e�ciency� one must compile stops in modeb� with some magic�like optimization �e�g� the magic set interpreter��

There should really be no need to write RL programs from scratch� but if you want to do it�you should know the mode and ag commands� These commands give to the query shell theinformation that the ��rm� �le would contain if it existed�

� �� mode timezone b� f��

� �� flag timezone� � magic��

�

As these commands only enter information into the query shell� you can issue them evenbefore loading the ��ro� �le that contains the RL code implementing timezone�

Once you have told the query shell all it needs to know about the derived relations to betested� you can start the testing itself� Asking queries on the relations under test is thesimplest testing and debugging method but it can be very e�ective� especially if the testerknows and uses the logic programming technique of declarative debugging�

Aditi has one facility specially intended to support the debugging of Aditi�Prolog programs�When an Aditi�Prolog program includes a trace declaration such as

�� flag in�list� � trace��

the compiler generates RL code that prints diagnostics whenever any of the RL proceduresimplementing the named predicate is either entered or exited� �In the case of in list� thisincludes the RL procedure for magic in list �� as well as the one for in list�� Whenentering a traced RL procedure� the query shell prints the relation that is the input argumentof the procedure when exiting it� the query shell prints the output relation� The outputrelation will have all the attributes of the input relation� and maybe more �one more attributeper �f� in the mode�� Each output tuple will have a tuple from the input relation in its inputpositions� but some input tuples �those that lead to no solution� will not be found in this way�

When the query shell calls either directly or indirectly a predicate that was compiled withtracing� it prints a message on every entry to and exit from a traced RL procedure� togetherwith the appropriate relation� You can get a reasonably good feel for what Aditi is doing bylooking at this output together with the RL assembly code being executed �which you can getby invoking apc with the �l ag� as explained in section �� You can put the two togethermore easily if you set the stats variable in the DAP� this will cause the query shell to reportthe completion of every relation algebra operation �see below for how to set DAP variables��

If you suspect that a bug is caused by the query shell telling the DAP to do the wrong thing�you may wish to look at the �les

!ADITI�HOME�tmp�in�!username�dap

!ADITI�HOME�tmp�out�!username�dap

which contain the data sent from the query shell to the DAP and from the DAP to the queryshell respectively� This data is ASCII� and so is human readable� but to interpret it and makeuse of it you do need knowledge of some system internals� See the manual page for dbsh��A�for details�

When you �nd the bug in your code� you should �x it in the source and recompile the a�ected�les� It would be nice if you could do this while the query shell that you used to �nd thebug remained suspended in the background� and then foreground the query shell� reload thea�ected �les and continue where you left o�� Unfortunately� at present there is no way toreload or unload a loaded ��ro� �le� so you must exit the query shell and start another to testthe new version of the code under test�

To make life easier in such an environment� the query shell at startup looks for a �le named��qshrc� �rst in the current directory and then in the home directory� If it �nds one� it

�

executes its contents� For example� if ��qshrc� in the current directory contains �load stops��then the startup message will be�

�� qsh

Aditi �� Copyright �� The University of Melbourne�

Aditi DAP Version � RL Version �

Login successful

Login name� zs Database Id� � User Id� ��

Reading commands from ��qshrc��

�qshrc �� load stops

loading file ��stops�ro��

Procedure file �stops�ro has entries�

Loading stops �

Loading in list


Aditi Query Shell � type ��help�� for help�

��

�� Accessing other databases

The query shell has a notion of the current database� which is the database in which it looksfor all the relations mentioned in queries� At startup� the current database is initialized tothe database named by the ADITIBASE environment variable�

Suppose that during an Aditi session you wish to compare the answers you obtain from aquery using the data in your database� with the answers computed from the data in anotherdatabase� e�g� ��users�aditi�example�� To do this� you can change the current database viathe �db� command�

�� showdb�


�� flight sydney� Dest��


� honolulu

� melbourne

� �� db ��users�aditi�example��

� �� showdb�


��

� �� flight sydney� Dest��


No Answers

This shows the ight relation in ��users�aditi�example� does not have any ights out ofSydney�

In the current Aditi implementation� RL procedures that were loaded into the DAP servingthis query shell will stay there even when the user uses the db command to switch to anotherdatabase� Any reference after the switch to the predicates these RL procedures implement willthus still use the old database�s de�nitions of these derived relations� though these de�nitionsmay now refer to base relations from the new database� Later versions of Aditi will implementa cleaner semantics�

�� Accessing the DAP

The query shell gives limited access to the DAP supporting the query shell� The most usefulDAP facility available in this way is the ability to manipulate some toggle switches thatcontrol the production of diagnostics by the DAP� The commands involved are �set� and�unset�� invoked like this�

� �� set verbose�

The toggle switches that can be manipulated include�

disasm When set� the query shell will print a line at the start of every major DAPoperation� giving the type of the operation and its arguments� This can be usefulwhen trying to follow the progress of an RL program�

nodups When set� the query shell will eliminate duplicates in answer relations� �Nodupsis actually a query shell switch� not a DAP switch�� Nodups is set by default�

stats When set� the query shell will print a one�line summary at the completion ofevery RAP job invoked by the DAP� This summary includes the job type �e�g�project� select� join etc�� its status �� means successful�� and the time taken bythe job �reported as elapsed time� user time and system time� all in seconds��

tmpincore When set� the lower layers of Aditi will attempt to keep temporary �les� or aslarge chunks of them as possible� in main memory� This can increase the speedof the system substantially at the cost of dramatically increasing its memoryrequirements� Tmpincore is set by default�

verbose When set� the query shell will print at the end of each query details about thetime taken to execute it� Each report gives the total elapsed time for the query�excluding compilation from Aditi�Prolog to RL�� the user time� system time and

��

elapsed time for the work that the DAP has done for this query� and the sum ofthe user� system and elapsed times for the RAP jobs that the DAP invoked toanswer this query�

In fact� you can issue any DAP command from the query shell by putting it into quotes andpre�xing it by the word �dap� �for the set of useful DAP commands� see dbsh��A�� Forexample� the command �set verbose� is just shorthand for the command

� �� dap �set verbose�

Similarly� the command

� �� shutdown

"" Shutting down query server� """

is shorthand for �dap �shutdown� �� Its e�ect is equivalent to an �aditi stop� from a Unixshell� Since the query shell cannot exist without a query server� shutting down the queryserver causes the query shell to exit�

The other� more usual way of exiting the query shell is to press the end�of��le character�usually control�D� at the beginning of a line�

� The X interface to Aditi

Xaditi is a graphical user interface �GUI� that provides access to almost all the facilities ofAditi� the main exceptions being the starting and stopping of query servers and the manipu�lation of the permissions associated with relations� It works on machines using the X windowsystem� Although xaditi is built with the Motif libraries� it does not require the windowmanager to be mwm or its relatives� we usually use it with twm or tvtwm�

The main xaditi window has four main parts� From top to bottom� they are the menu bar�the name of the current database� a window onto the query shell and an output window� Thequery shell window and the output window are independently scrollable using the standardMotif mouse operations� The dividing line between these two windows can be moved bydragging the small pane control box near the right side astride the dividing line�

Whenever the cursor is in the main xaditi window� keyboard input is directed to the queryshell window� This window functions in almost exactly the same way as an xterm windowrunning qsh the main di�erence is that results are displayed not in this window but in theseparate output window� This way� one can scroll through a large result relation while stillbeing able to see the query that generated it�

The menu bar provides easy access to the functionality that is provided by Aditi commandsother than qsh� Many of the menu entries do their work through dialog boxes� Clicking thecancel button in any dialog cancels the operation that created the dialog box� Clicking thehelp button unfortunately does not do anything in this version of Aditi�

�

Xaditi executes many of the commands invoked from the menu bar by passing them onto thequery shell which passes them on further to the underlying DAP� When this happens� xaditiechoes the command in the query shell window�

The leftmost menu allows you to clear the output window and to quit xaditi� The other threemenus manipulate databases� relations and schemas respectively� The commands availablethrough the Db menu are�

Create Db Asks for a Unix pathname and creates an Aditi database in the nameddirectory� This emulates the behaviour of the newdb command�

Change Db Like the query shell� xaditi has a notion of the current database �initiallyit is the database named by the ADITIBASE environment variable�� Thiscommand asks for a Unix pathname and changes the current database to thenamed directory for both xaditi and its query shell� Changing the currentdatabase from the query shell window is not recommended as it updatesonly the query shell�s notion of the current directory and leaves xaditi�sunchanged this will lead to inconsistencies�

Db Info Asks for a Unix pathname and displays the data dictionary of the namedAditi database in the output window� This emulates the behaviour of theshowdict command�

The commands available through the Relation menu are�

Create Rel Puts up a dialog box asking you to type in a relation name and to select aschema and an index type from two displayed lists� If you select an indextype other than data� then some other slots pop up asking you for theparameters of the selected intex type� This emulates the functionality ofthe newrel command�

Modify Rel Puts up a dialog box asking you to select a relation� to select whether youwant to add or delete tuples� and to type the tuples that you want to addor delete into the lower window of the dialog box� However� you can get thetuples themselves from a �le by clicking on the �load tuple data� button�which will put a �le selection dialog box and replace the contents of the lowerwindow with the contents of the selected �le� This emulates the behaviourof the newtups and deltups commands�

Show Rel Asks you to select the name of an Aditi relation and displays the contentsof that relation in the output window� This emulates the behaviour of theseerel command�

Delete Rel Asks you to select the name of an Aditi relation and deletes that relation�This emulates the behaviour of the delrel command�

The commands available through the Schema menu are�

��

Create Schema Puts up a dialog box asking you to type in the name� arity and keylist ofthe new schema and to select its tuple type from a list �currently the onlyvalid selection is �ex��

Show Schema Creates a window listing all the schemas in the current database includingall their details �arity� tuple type� key attributes�� This emulates part of thebehaviour of the showdict command�

Delete Schema Asks you to select the name of an Aditi schema and deletes that schema�This emulates the behaviour of the delschema command�

� Acknowledgements

Many people have contributed signi�cantly to Aditi both by performing research and bydeveloping software� We would like to acknowledge the support of Warwick Harvey� DavidKeegel� Kim Marriott� and Je�rey Schultz in this respect�

This research was supported by grants from the Australian Research Council through theMachine Intelligence Project� from the Victorian Department of Manufacturing and IndustryDevelopment� through the Collaborative Information Technology Research Institute� from theAustralian Department of Industry� Technology and Commerce through the Key Centre forKnowledge�based Systems� and from the Australian Cooperative Research Center programmethrough the Center for Intelligent Decision Systems�

References

�� J� Harland� D� B� Kemp� T� S� Leask� K� Ramamohanarao� J� Shepherd� Z� Somogyi�P� J� Stuckey� and J� Vaghani� Aditi�prolog language manual� Technical Report ��Department of Computer Science� University of Melbourne� November ��

�� J� Harland and K� Ramamohanarao� Experiences with a ights database� Technical Report�� Department of Computer Science� University of Melbourne� November ��

�� J� Vaghani� K� Ramamohanarao� D� B� Kemp� Z� Somogyi� and P� J� Stuckey� Designoverview of the aditi deductive database system� Proceedings of the Seventh International

Conference on Data Engineering� pages �� April ��

��

A Aditi environment variables

Aditi uses the values of the following environment variables�

ADITI HOME This environment variable should be set to the full pathname of �aditi� thedirectory where Aditi is installed� It is used by various Aditi programsto construct paths to other parts of the Aditi system� mainly other Aditiprograms� It must be set if Aditi is to function properly�

ADITI This environment variable should be set to the name of the Aditi in�carnation that you use most of the time� If thing environment vari�able is not set� Aditi program assume the default value� which is�aditi�� At initialization time� the query server consults the con�gura�tion �le whose pathname is ��ADITI HOME�lib��ADITI�con�g�� The �le��ADITI HOME�lib�aditi�con�g� must exist�

ADITIBASE Several Aditi commands take the pathname of a database as a parameter�The value of this environment variable� if set� supplies the default value tosuch parameters� allowing command lines to be shorter� In the current ver�sion of Aditi� databases are identi�ed by the pathname of the Unix directoryin which they are stored�

B Aditi con�guration �les

Every Aditi process consults the con�guration �le ��ADITI HOME�lib��ADITI�con�g� atstartup� This con�guration �le will look something like this�

# Configuration file for the Aditi deductive database system

# Server name� test

QUERYADDRESS ��

MUTEXKEY ��

SHMKEY ��

MAPFILE �aditi�lib�aditi�map

RAPNAME �aditi�bin�sgi�rap

MUDDTMPDIR �aditi�tmp

NPROCESSORS

RAPINIT �

RAPMAX �

MAXLOGINS ��

MAXUSERLOGIN �

UPDATECYCLE ��

DOLOGGING

��

LOGFILE �aditi�log�test�log

MAXSYSFILES �

MAXCOREFILES ��

MAXCOREPERCENT �

PAGESIZE ��

NUMPAGES ��

NUMFREE

BUFFERENTRIES ��

SYSSHMSIZE ��

MAXPROCESSES �

MAXLOCKS ��

DEBUGMALLOC �

USEINCORE

NESTEDLOOPSIZE ��

JOINMETHOD SORT

Lines beginning with � � are comments� Each of the remaining nonblank lines sets oneparameter� The parameters may be speci�ed in any order� and any omitted parameter willhave its value set to a default�

The meanings of the various parameters are as follows�

QUERYADDRESS Two integers separated by a dot� The �rst integer is intended to be anetwork address in a future version of Aditi currently it must be setto zero� The second integer is a System V message queue identi�er�see msgget�� it must be unique across all Aditi con�g �les� andit must not conict with message queue identi�ers used by any otherprogram on the system� By convention� the second integer is the sameas MUTEXKEY and SHMKEY�

MUTEXKEY An integer used as a System V semaphore identi�er �see semget�� it must be unique across all Aditi con�g �les� and it must not conictwith semaphore identi�ers used by any other program on the system�By convention� MUTEXKEY is the same as SHMKEY and the secondhalf of QUERYADDRESS�

SHMKEY An integer used as a System V shared memory segment identi�er �seeshmget�� it must be unique across all Aditi con�g �les� and it mustnot conict with shared memory segment identi�ers used by any otherprogram on the system� By convention� SHMKEY is the same as MU�TEXKEY and the second half of QUERYADDRESS�

MAPFILE The full pathname of the authorization �le for this server� For theformat of this �le� see appendix C�

RAPNAME The pathname of the RAP executable� This option is used by Aditi�sdevelopers to allow a server to be set up with a new and possibly buggy

��

RAP� There are no QSNAME and DAPNAME parameters as users canchoose the QS and DAP programs to use by appropriate settings of theirADITI HOME environment variable�

MUDDTMPDIR The pathname of the directory in which Aditi will put its temporary�les� This directory can �ll up with temporary relations that were beingworked on at times of machine �or Aditi� crashes� as well as temporaryrelations that were explicitly saved �by setting nodelete in a DAP� pos�sibly from a query shell�� so you might want to clean it out periodically�

NPROCESSORS The number of processors on the machine where the query server willrun� In the future� the query server will use this to judge how manyconcurrently executing RAPs are �too many� �if you want to reservesome CPUs for other purposes� you may wish to understate the actualnumber�� At the moment� the query server simply uses the parameterRAPMAX�

RAPINIT At initialization� the query server will start this many Relational Alge�bra Processes�

RAPMAX The query server will allow this many RAPs to exist at any one time�This is a limit on the total number of RAPs on the machine if and onlyif this is the only query server running on the machine� as each queryserver has its own set of RAPs�

MAXLOGINS The query server will allow this many DAPs to be connected to itselfat any time time� Any further login requests from DAPs will be refuseduntil some already logged�in DAP exits�

MAXUSERLOGIN The query server will allow this many DAPs operating on behalf of anAditi user to be connected to itself at any time time� Any further loginrequests from DAPs on behalf of that user will be refused until one ofthat user�s already logged�in DAPs exits�

UPDATECYCLE The query server periodically calculates how much work it has done onbehalf of every system user this parameter gives the interval in secondsbetween such calculations� In the future� the query server will use thisinformation to implement fair scheduling of RAP among several users�

DOLOGGING A positive non zero number means log entries are written to the log �lenamed by the LOGFILE parameter� The data written to this �le is ofinterest only to Aditi�s developers� Note� Aditi never truncates this �le�so if you do logging� you must� otherwise your disk will �ll up�

LOGFILE The pathname of the �le in which various Aditi programs will put logmessages�

MAXSYSFILES The number of Aditi system �le handles� This parameter should be setto about the number of relations �permanent and temporary� that youexpect to be used at any one time multiplied by two �for the data and

��

index �les�� This parameter can be larger than the maximum numberof open �le descriptors allowed by the underlying Unix implementation Aditi does its own �le descriptor caching�

MAXUSERFILES The number of Aditi system �le handles that can be open simultaneouslyin an Aditi process� This parameter must be less than or equal toMAXSYSFILES and less than or equal to the maximum number ofopen �le descriptors allowed by the underlying Unix implementation�

MAXCOREFILES The maximum number of temporary �les that can be cached in core atthe same time�

MAXCOREPERCENT The percentage of the Aditi bu�er cache that Aditi can attempt to useto cache entire temporary relations in core�

PAGESIZE The size in bytes of the pages in the Aditi bu�er cache� The minimumpage size is two kilobytes�

NUMPAGES The number of pages in the Aditi bu�er cache� This bu�er cache isshared by all Aditi processes connected to this query server�

NUMFREE The number of pages in the Aditi bu�er cache that form a reserve andcannot be locked down� Attempts to lock down pages beyond this limitwill cause data to be copied out of the bu�er cache to the address spaceof the requesting process�

BUFFERENTRIES The size in pages set aside in each Aditi process for local caching oftemporary �les� If the tmpincore DAP parameter is set �which is thedefault�� this area will hold overows from the shared bu�er cache�

SYSSHMSIZE The size in kilobytes of a piece of shared memory set aside to hold long�term data of potential interest to all Aditi processes connected to thisquery server� e�g� headers giving parameters of permanent relations�

MAXPROCESSES The maximum number of Aditi processes that can connect to the queryserver at any one time� This includes RAPs� DAPs� and Aditi commandsinvoked from a shell�

MAXLOCKS The maximum number of locks available� Since locks can be taken onboth relations and pages� the value of this parameter should be approx�imately MAXSYSFILES � NUMPAGES�

DEBUGMALLOC This parameter is intended to be used only by Aditi�s developers�

USEINCORE A positive non�zero value indicates that RAPs may create their inter�nal temporary �les in core� This decision is completely independent ofwhether temporary relations may be kept in core that is controlled bythe DAP variable tmpincore�

NESTEDLOOPSIZE Aditi uses the nested loop algorithm to perform joins only if the smallerrelation can be scanned less than �ve times while still �tting into a partof the Aditi bu�er cache whose size is given by this parameter in bytes�

��

JOINMETHOD The join method to use on two unindexed relations� �Joins on indexedrelations use the index�� In the current version of Aditi� this parametercurrently should be set to SORT� In later versions� Aditi will supportother join methods as well�

C Aditi authorization �les

The con�guration �le of every Aditi server must set the parameter MAPFILE to the pathnameof a �le listing the authorized users of that server�

With the exception of blank lines and comment lines �those beginning with a � � sign� everyline in this �le describes an Aditi user� These lines should have three �elds� a Unix username �a string�� an Aditi login id �a number�� and a ag indicating whether the user has�Aditi superuser� status �a number nonzero means superuser�� The Aditi login ids must allbe distinct� The following is an example�

# Aditi User Id File

#

# Username Login�id Superuser�Flag

dba

clerk �

clerk � �

tester �

D Aditi commands

The following pages contain the manual pages for the Aditi commands visible to users�

��

Documents

Aditi users' guide 1 Introduction - TTNZ