Using OmniSci Services

OmniSci features two system services: mapd_server and mapd_web_server. You can start these services individually using systemd.

Starting and Stopping OmniSci Core Using systemd

For permanent installations of OmniSci Core, OmniSci recommends that you use systemd to manage the OmniSci Core services. systemd automatically handles tasks such as log management, starting the services on restart, and restarting the services if there is a problem.

In addition, systemd manages the open-file limit in Linux. Some cloud providers and distributions set this limit too low, which can result in errors as your OmniSci environment and usage grow. For more information about adjusting the limits on open files, see Why am I seeing the error "Too many open files...erno24"? in Frequently Asked Questions.

Initial Setup

You use the install_mapd_systemd.sh script to prepare systemd to run OmniSci services. The script asks questions about your environment, then installs the systemd service files in the correct location. You must run the script as the root user so that the script can perform tasks such as creating directories and changing ownership.

cd $MAPD_PATH/systemd
sudo ./install_mapd_systemd.sh

The install_mapd_systemd.sh script asks for the information described in the following table.

Variable Use Default Notes
MAPD_PATH Path to the OmniSci Core installation directory Current install directory OmniSci recommends /opt/mapd as the install directory.
MAPD_STORAGE Path to the storage directory for OmniSci Core data and configuration files /var/lib/mapd Must be dedicated to OmniSci. The installation script creates the directory $MAPD_STORAGE/data, generates an appropriate configuration file, and saves the file as $MAPD_STORAGE/mapd.conf.
MAPD_USER User OmniSci Core is run as Current user User must exist before you run the script.
MAPD_GROUP Group OmniSci Core is run as Current user's primary group Group must exist before you run the script.

Starting OmniSci Core Using systemd

To manually start OmniSci Core using systemd, run:

sudo systemctl start mapd_server
sudo systemctl start mapd_web_server

Restarting OmniSci Core Using systemd

You can use systemd to restart OmniSci Core—for example, after making configuration changes:

sudo systemctl restart mapd_server
sudo systemctl restart mapd_web_server

Stopping OmniSci Core Using systemd

To manually stop OmniSci Core using systemd, run:

sudo systemctl stop mapd_server
sudo systemctl stop mapd_web_server

Enabling OmniSci Core on Startup

To enable the OmniSci Core services to start on restart, run:

sudo systemctl enable mapd_server
sudo systemctl enable mapd_web_server

Using Configuration Flags on the Command Line

To use options provided in a configuration file, set the --config flag to the path of the configuration file for mapd_server and mapd_web_server. For example:

$MAPD_PATH/bin/mapd_server --config $MAPD_STORAGE/mapd.conf

You can also specify configuration settings at the command line. OmniSci recommends that you use the systemctl command to start and stop the servers, but you can use the mapd_server and mapd_web_server commands with configuration flags for testing and debugging.

Command Line Configuration Flags for OmniSci Server

Command Line Configuration Flags for OmniSci Server
Flag Description Implied Value Default Value Why Change It?
--calcite-port arg Calcite port number9093Change to avoid collisions with ports already in use.
--cluster argPath to data leaves list JSON file. Indicates that the OmniSci server instance is an aggregator node, and where to find the rest of its cluster. Enterprise only.$MAPD_STORAGEChange for testing and debugging.
--config argPath to mapd.conf$MAPD_STORAGEChange for testing and debugging.
--cpuRun on CPU onlyFALSEOne use case for disabling GPUs would be during database conversion. That requires moving a large amount of data with minimal processing.
--cpu-buffer-mem-bytes arg Size of memory reserved for CPU buffers [bytes]0
--data argDirectory path to OmniSci catalogs$MAPD_STORAGEChange for testing and debugging.
--enable-watchdog [arg]Enable watchdogTRUE[1]TRUE[1]
--flush-log [arg]Immediately flush logs to disk.TRUE[1]TRUE[1]Set to FALSE if this is a performance bottleneck.
--from-table-reordering [=arg(=1)] (=1)Enable automatic table reordering in FROM clauseTRUE[1]TRUE[1]
--gpuRun on GPUs (Default)TRUEOne use case for disabling GPUs would be during database conversion. That requires moving a large amount of data with minimal processing.
--gpu-buffer-mem-bytes argSize of memory reserved for GPU buffers [bytes] (per GPU)0 Restricts the amount of memory a single process uses, so that when running multitenancy in the cloud several processes can all use the same GPUs.
--ha-shared-data argDirectory path to shared OmniSci.directory. Enterprise only.
--help-advancedPrint advanced and experimental options. These options should not normally be used in production.
--http-port argHTTP port number9090Change to avoid collisions with ports already in use.
--ldap-dn argldap DN Distinguished Name. Enterprise only.(=uid=%s, cn=users, cn=accounts, dc=mapd, dc=com)
--ldap-role-query-regex argRegEx to use to extract role from role query result. Enterprise only.
--ldap-role-query-url argldap query role URL. Enterprise only.
--ldap-superuser-role argThe role name to identify a superuser. Enterprise only.
--ldap-uri arg ldap server uri. Enterprise only.
--left-deep-join-optimization [=arg]Enable left-deep join optimizationTRUE[1]TRUE[1]
--license argPath to file containing license key
--null-div-by-zero [=arg]Allows processing to complete when when the dataset would cause a div/0 error.0
--num-gpus argNumber of gpus to use-1In a shared environment, you can assign the number of GPUs to a particular application. The default, -1, means use all available GPUs.
--read-only [=arg]Enable read-only modeTRUE[1]FALSE[0]Prevents inadvertent (or purposeful) changes to the dataset.
--render-mem-bytes argSize of memory reserved for rendering [bytes]500000000
--render-poly-cache-bytes argSize of memory reserved for polygon rendering [bytes]300000000
--rendering [=arg]Enable/disable backend renderingTRUE[1]TRUE[1]
--start-gpu argFirst gpu to useFALSE[0]
--string-servers argPath to string servers list JSON file. Enterprise only.
-h [ --help ] Print help messages
-p [ --port ] argPort number9091Change for testing and debugging.
-v [ --version ]Print the OmniSci version in use.

Command Line Configuration Flags for OmniSci Web Server

Command Line Configuration Flags for OmniSci Web Server
Flag Description Default Why Change It?
-b | backend-url string URL to http-port on mapd_server http://localhost:9090 Change to avoid collisions with other services.
--cert string Certificate file for HTTPS cert.pem Change for testing and debugging.
-c | --config string Path to OmniSci configuration file   Change for testing and debugging.
-d | --data string Path to OmniSci data directory data Change for testing and debugging.
--docs string Path to documentation directory docs  
--enable-https Enable HTTPS support   Change to enable secure HTTP.
-f | --frontend string Path to frontend directory frontend  
--key string Key file for HTTPS key.pem Change for testing and debugging.
-p | --port int Frontend server port 9092 Change to avoid collisions with other services.
-r | --read-only Enable read-only mode   Prevent inadvertent (or nefarious) changes to the data.
--servers-json string Path to servers.json   Change for testing and debugging.
--timeout duration Maximum request duration in #h#m#s format. For example 0h30m0s represents a duration of 30 minutes. 1h0m0s The --timeout option controls the maximum duration of individual HTTP requests. This is used to manage resource exhaustion caused by improperly closed connections. One side effect is that it limits the execution time of queries made over the Thrift HTTP transport. This timeout duration must be increased if queries are expected to take longer than the default duration of one hour; for example, if you perform a COPY FROM on a large file when using mapdql with the HTTP transport.
--tmpdir string Path for temporary file storage /tmp The temporary directory is used as a staging location for file uploads. You might want to place this directory on the same file system as the OmniSci data directory. If not specified on the command line, mapd_web_server also respects the standard TMPDIR environment variable as well as a specific MAPD_TMPDIR environment variable, the latter of which takes precedence. If you use neither the command-line argument nor one of the environment variables, the default, /tmp/ is used.
-v | --verbose Print all log messages to stdout   Change for testing and debugging.
--version Return version    
--db-query-list <path-to-query-list-file> Pre-load data to memory based on SQL queries stored in a list file. n/a Automatically run queries that load the most frequently used data to enhance performance. See Pre-loading Data.