2. The Shell

Introduction to the Databridge Shell

The Shell is a command line interface which you use to list, create, run, monitor and abort your Databridge data imports. To start the Shell go to the Databridge installation folder and type:

#!bash
$ bin/databridge

When the Shell starts up you will be presented with a simple welcome screen:

#!bash
********************************************************************************
Welcome to the Databridge Command Shell.
User: gandalf
Type 'help' for a list of available commands.
********************************************************************************
databridge$ 

To list the available Shell commands, type help. You can get more detailed help on what each command does, and how to use it, by typing help <command>

Shell commands

• init - create a new import project

• drop - delete an existing import project

• list - list available import tasks

• import - run an import project

• test - dry-run an import but do not create the database

• status - report the status of a running import project

• abort - abort a running import project

• use - switch Neo4j to use the database created by the specified import project

• quit - leave the Databridge shell

list

Lists all the import tasks in the imports folder. Type help list

#!bash
list: lists the import tasks that can be run

usage: 'list'

Import tasks that have been created using the 'init' command are registered in the imports folder 
and are enumerated by the 'list' command

Import tasks that are not in the imports folder are not shown. They can be run by specifying
the full path to the import project folder

init

The init command creates a new import project folder in the imports folder of the Databridge installation. Type help init

#!bash
init: Creates a new import project

usage: 'init <import-project>'

A new folder '<import-project>' will be created in the imports folder of the installation,
containing the following sub-folders:

  - resources
  - schema

The 'resources' sub-folder should contain the Resource Definitions for the import and
the 'schema' sub-folder should contain the Schema Definitions.

Please refer to the online documentation for additional details about configuring the 
Resource and Schema definitions.

drop

Permanently removes an import project, e.g. drop satellites. Type help drop

#!bash
drop: deletes an import project

usage: 'drop <import-project>'

Permanantly removes the specified import project

If a simple name is specified for the import project, e.g. 'drop satellites', the import project will be 
removed from the imports folder, if it exists.

To drop an import project in a different location, specify an absolute or relative path to the import project folder, e.g.:

    drop /demos/test

WARNING: this operation cannot be undone!

import

Runs the specified import project, e.g. import satellites. Type help import

#!bash
import: Runs the specified import project

usage: import [-d] [-s] [-q] [-o target] [-l limit] <import-project>

  d: create a new database for the import. Existing data will be lost.
  s: stream data into a running instance of Neo4j
  q: run the import project in the background, logging output to import.log instead of the console

  o target : use the specified target database for this import. The database should not be in use

  l limit  : the max number of rows to process from each resource during the import

If a simple name is specified for the import project, e.g. 'import satellites', the import project will be 
looked up from the imports folder.

To run an import project in a different location, specify an absolute or relative path to the import project folder, e.g.:

    import demos/satellites

If the import is successful, a new database 'graph.db' will be created in the import project folder, unless 
 you specified an alternative location using the -o flag.

Please refer to the 'use' command for a simple way to switch Neo4j to use the new database.

Some of the import options are explained in more detail below

-s

Use the streaming endpoint. The streaming endpoint allows you to insert and update data into a running Neo4j instance. This is many times slower than using the default endpoint which requires the database to be shut down. However, it can be useful for scenarios where an initial bulk-load of data is done, and then incremental updates can be run using the streaming endpoint.

-q

You can run the import in the background by specifying this option. This frees up your console allowing you to perform other tasks while the import is in progress. You can check the running status of an import project in the background using the status command, or abort it with the abort command.

When an import is running in the background, the console output is redirected to a log file. You can check its progress using tail import.log

-o

Imports data into the folder specified by the argument supplied to the -o flag. For example:

import -o /opt/data subway

Will import the subway data into an existing database folder /opt/data/graph.db. If a graph database directory does not exist at the specified location, it will be created. Any data in the existing database is preserved.

test

#!bash
test: Performs a dry-run of the specified import project, bit does not create a database

usage: test [-l limit] <import-project>

  l limit  : the max number of rows to process from each resource during the import

If a simple name is specified for the import project, e.g. 'test satellites', the import project will be 
looked up from the imports folder.

To test an import project in a different location, specify an absolute or relative path to the import project folder, e.g.:

    test demos/satellites

status

Checks the running status of an import project executing in the background. Type help status

#!bash
status: checks the running status of an import project executing in the background

usage: 'status'

Note that only one import can be running at a time

abort

Terminates the import project currently running in the background, if any. Type help abort

#!bash
abort: kills any import project currently running in the background

usage: 'abort'

Note that only one import can be running at a time

use

Switches a local installation of Neo4j to use the database created by the specified import project. Type help use

#!bash
use: switches a local installation of Neo4j to use the database created by the specified import project

usage: 'use <import-project>'

Neo4j must be installed on the same machine as the Databridge import tool. This command changes
the local Neo4j server configuration to use the database created by the specified import project.

The command will attempt to stop the Neo4j server first if it is currently running

Note that your user account will require elevated privileges to execute this command