Introduction

The agtool command-line utility combines most individual command-line programs into one. Its general calling sequence is 

% agtool <utility> [options]

So for example, to load an Ntriples file my-ntrips.nt into the my-database store, the command might be 

 % agtool load --port 10035 --input ntriples my-database mydata-1.nt

There were individual programs for the various utilities in releases prior to 6.2.0. Those programs still exist (although they are now mostly scripts that call agtool). Most utilities are documented in separate documents linked to from this document.

Help

% agtool --help

displays a help string giving a brief description of each utility. 

% agtool UTILITY --help

displays a help string for the specific UTILITY.

Utilities

agtool can run the following utilities. Use agtool UTILITY --help to get more information on any utility.

There are additional agtool utilities that are not documented here. Some provide information useful for dealing with problem reports and user may be asked to run those as part of dealing with a problem report. Others are associated with other AllegroGraph features and should only be run as part of using those features. Those utilities are documented with the feature rather than here.

Most agtool utilities take the same options as the program they are replacing, but some have either new options or no longer accept previous options (usually the abbreviation is not accepted but the long form is). These changes are noted for each relevant utility.

AllegroGraph supports triple attributes (key/value pairs associated with individual triples) and static filters (statements that can restrict access to triples based on their attribute values. These features are described in the Triple Attributes document.

Attributes can only be associated with a triple when the attribute has been defined. agtool can be used to define attributes (agtool define-attribute), delete attribute definitions (agtool delete-attribute-definition), lookup attribute definitions (agtool lookup-attribute-definitions), and set and delete a static attribute filter (agtool set-static-attribute-filter and agtool delete-static-attribute-filter). To see the calling sequence for these commands, execute 

% agtool COMMAND --help

For example 

% agtool define-attribute --help

The archive utility

Command calling template: 

% agtool archive [options] command [command-args]

options are prefixed with double dashes (single dash in some cases) and may also take arguments. To get usage information, enter 

% agtool archive --help

The commands which write to or read from files (backup, backup-all, backup-settings, restore, restore-all, and restore-settings) are passed a directory and perhaps additional information like a database name. The specific files are located and named within that directory following standard rules (described here. Unless the --supersede option is specified to backup commands, the archive directory must either not exist or be empty.

agtool archive can be used to upgrade a database from the format on one AllegroGraph release to the format of a later release. This is the recommended way to upgrade since it provides a backup copy of the database in the earlier format which allows easy recovery if there are problems with the later version. The agtool upgrade utility does not (by itself) backup a database before upgrading.

See the Backup and Restore document for a complete list of commands and options.

The materializer utility

Command calling template: 

% agtool materialize [options] command [command-args]

See the Command Line Interface section in the Materializer document for details on the options.

The query utility

Command calling template: 

% agtool query [options] DBNAME [QUERY-FILE]*

See the Querying tool document for details on the arguments and options.

The export utility

Command calling template: 

% agtool export [options] DBNAME FILE

This will export the data in the store DBNAME to FILE. For example, 

% agtool export --port 10035 --output rdfxml lesmis lesmis.rdf

exports the data in the lesmis store (in the root catalog, since no catalog is specified) to the file lesmis.rdf. The format is rdfxml.

See the Data export tool document for details on the options.

The load utility

The agtool load utility (previously the program agload) can be used to load data into a store from a file or a collection of files. See the Data Loading document for details.

The utility calling template is: 

% agtool load [options] DBNAME SOURCE*

where DBNAME is the name of the store into which the data should be loaded (the catalog can be specified as one of the options). The SOURCEs are the file(s) to be loaded. The SOURCE can be standard input. Numerous options control the loading process. All are described in the Data loading tool document for details on the options.

Here are a couple of examples of typical uses: 

% agtool load --port 10035 --input ntriples my-database mydata-1

Load the Ntriples file mydata-1 into the store my-database in the root catalog. The server listening on port 10035. 

% agtool load --port 10035 --catalog mycatalog  my-store2 mydata-2.ttl mydata-3.ttl

Load the turtle format files mydata-2.ttl and mydata-3.ttl (the format determined by the file extensions) into the store my-store2 in the catalog mycatalog. The server listening on port 10035.

The recover utility

Command calling template: 

% agtool recover [options] archive database

See the Point-in-Time Recovery document for details on the options and general usage.

The repl utility

The repl utility allows you to manage a multi-master replication cluster. See Using the agtool repl command in the Multi-master Replication document for more information.

A multi-master cluster should not be confused with single-master replication described below. Single-master replication allows for one master repository, where modifications (adding and deleting triples) can be made and replicas which cannot make modifications. Multi-master replication allows each replica to make modifications.

The replicate utility

The replication utility allows you to set up single-master replication where you have several identical instances of AllegroGraph running simultaneously, so if one fails one of the others can take over. The replicate command calling template is: 

% agtool replicate [options]

See Replication Details document and also the Replication document for more information on agtool replicate and its options.

Single-master replication should not be confused with multi-master replication, described above.

The upgrade utility

agtool ugrade will do an in-place upgrade of a single database from an earlier release to the current release (the release containing the agtool being run). The upgrade is done without backing the database up. Backing up databases prior to upgrading is strongly recommended. See Backup and Restore.

Command calling template: 

% agtool upgrade [--port|-p port] [--catalog|-c catalog] dbname

See see the agtool upgrade program in the Database Upgrading document for further details. Be sure to backup any database before upgrading.

Managing users and roles

agtool user can be used to add and remove users and to set user permissions and access rights. agtool role can be used to create and manage roles. See Managing Users for information on managing users with *agtool and with AGWebView.