1.1. quasardb shell

1.1.1. Introduction

The quasardb shell is a command line tool that enables you to interact with a quasardb node or cluster. The shell can be used interactively and non-interactively. In interactive mode, the user enters commands to be executed on the node. Feedback is provided to indicate failure. In non-interactive mode, a single command - supplied as a parameter - is executed and the program exits.

By default qdbsh will attempt to connect in interactive mode to a qdbd daemon running on 127.0.0.1:2836. If this is not the case - for example if your qdbd daemon runs on 192.168.1.1 and listens on the default port 2836 - you will need to pass the address and port as a qdb:// URI string, shown below:

$ qdbsh qdb://192.168.1.1:2836

If you wish to connect to a secure cluster, you can use the following command:

$ qdbsh --cluster qdb://192.168.1.1:2836 \
        --cluster-public-key-file /usr/share/qdb/cluster_public.key \
        --user-security-file /path/to/my/security.key

You will need to replace the locations of the cluster public key file /usr/share/qdb/cluster_public.key and your user security file /path/to/my/security.key with those provided by your system administration. Please refer to our security documentation for more information.

1.1.2. Command line options

Option	Usage	Default
-h, --help	display help
-v, --version	display quasardb version
-c	run a qdb command
-l, --list-commands	list available commands
--cluster	cluster URI	qdb://127.0.0.1:2836
--color-output	color output mode	automatic
--user-security-file	path to the file containing the user’s security token used for connection
--cluster-public-key-file	path to the file containing the public key of the cluster to connect to

1.1.3. Interactive mode

Use qdbsh interactive mode to enter as many commands as needed. The shell provides you with feedback upon success and failure or displays the content of retrieved entries.

Unless otherwise specified, qdbsh assumes the daemon is running on localhost and on the port 2836.

Once qdbsh has connected to a cluster, the following prompt is displayed:

qdbsh >

This means the shell is ready to accept commands. Only one command at a time may be specified.

A command is executed as soon as Enter is pressed and cannot be canceled or rolled back.

To exit the shell, enter the command exit. To list the available commands, type help. For the list of supported commands, see Command reference.

If you are looking for an example usage, please refer to the QuasarDB primer which uses an interactive qdbsh session to guide you through the first steps.

1.1.4. Non-interactive mode

Use qdbsh non-interactive mode to run one command without waiting for any input. Non-interactive mode supports standard input and output and can be integrated in a tool chain à la Unix. Performance-wise, non-interactive mode implies establishing and closing a connection to the quasardb cluster every time the qdbsh executable is run.

The command to be executed is supplied as an argument to the -c parameter. For the list of supported commands, see Command reference.

When successful, the result of the command will be printed on the standard output stream and the shell will exit with the code 0. Most commands produce no output when successful (silent success).

In case of error, the shell will output an error message on the standard error output stream and will exit with the code 1.

1.1.4.1. Examples

Unless otherwise specified, qdbsh assumes the daemon is running on localhost and on the port 2836.

Save the content of a Blob named “biography” in a text file named “biography.txt”:

qdbsh -c blob_get biography > biography.txt

Compress a file named “myfile”, then add its content to an entry named “myfile” on the quasardb node at 192.168.1.1:

bzip2 -c myfile | qdbsh qdb://192.168.1.1:2836 -c blob_put myfile

1.1.5. Command reference

If you want to use qdbsh in conjunction with our SQL query language, you can just use them directly from the QuasarDB shell.

In addition to these timeseries-oriented commands, qdbsh also supports the key/value API and more administrative commands which are described below.

1.1.5.1. General

Command	Arguments	Description
help		Display help page
exit		Exit the shell
version		display version information of qdbsh and the quasardb daemon

1.1.5.2. Administrative

Command	Arguments	Description
cluster_purge_all		remove ALL entries on the WHOLE cluster (dangerous!)
cluster_purge_cache		remove ALL cached data on the WHOLE cluster
cluster_trim		remove unused versions of entries from the cluster
cluster_wait_for_stabilization	timeout_in_millliseconds	wait for the stabilization of the cluster
cluster_status timeout_in_seconds	cluster_uri	print status information about a cluster
node_config	host	return the node configuration as a JSON string
node_status	host	return the node status as a JSON string
node_stop	host reason	shut down the quasardb daemon on a host
node_topology	host reason	return the node topology as a JSON string

1.1.5.3. Tags

Command	Arguments	Description
attach_tag	alias tag	add a tag to an entry
attach_tags	alias tag1 [ tag2 ... ]	add tags to an entry
detach_tag	alias tag	remove a tag from an entry
detach_tags	alias tag1 [ tag2 ... ]	remove tags from an entry
get_tagged	tag	get entries with the given tag
get_tagged_count	tag	get an approximate count of entries with the given tag
get_tags	tag	get tags for the given entry
has_tag	alias tag	return true if the entry has the tag

1.1.5.4. Key/Value

Command	Arguments	Description
find		find key/value entries that match certain parameters
prefix_get	prefix max_count	return aliases of all entries with aliases starting with the given prefix
suffix_get	suffix max_count	return aliases of all entries with aliases ending with the given suffix
remove	alias	remove the entry from the cluster
get_metadata	alias	return the metainformation about the entry
get_type	alias	return the type of the entry
blob_compare_and_swap	alias content comparand	atomically compare and swap the Blob with the comparand
blob_get	alias	return the content of the Blob
blob_get_and_update	alias content	atomically get and update the Blob
blob_put	alias content	create a new Blob; fails if Blob already exists
blob_remove_if	alias comparand	remove the Blob if the value matches the comparand
blob_scan	pattern max_count	scan ALL blobs on the WHOLE cluster for the given pattern
blob_scan_regex	pattern max_count	scan ALL blobs on the WHOLE cluster for the given regular expression pattern
blob_update	alias content	update an existing Blob or creates a new Blob
int_add	alias value	atomically increment the Integer by the value
int_get	alias	return the value of the Integer
int_put	alias value	create a new Integer; fails if Integer already exists
int_update	alias value	update an existing Integer or create a new Integer
deque_back	alias	return the value at the back of the Deque
deque_front	alias	return the value at the front of the Deque
deque_pop_back	alias	remove and return the value from the back of the Deque
deque_pop_front	alias	remove and return the value from the front of the Deque
deque_push_back	alias content	add a value to the back of the Deque
deque_push_front	alias content	add a value to the front of the Deque
deque_size	alias	return the size of the Deque
expires_at	alias expiry	set the absolute expiry time of the entry
expires_from_now	alias delta	set the expiry time of the entry to seconds relative to now
get_expiry	alias	return the absolute expiry time of the entry

arrow_backPrevious

1. Tools

Next arrow_forward

1.2. quasardb import tool