The entire Hypertable configuration is defined in the hypertable.cfg file. The preferable location for the configuration file is %ProgramData%\Hypertable\hypertable.cfg or <install dir>\conf\hypertable.cfg. For any other location of the configuration file hypertable.cfg use the following command to install the Hypertable service:

Hypertable.Service --install-service --config <abs dir>\hypertable.cfg


For a complete list of all command line options use:

Hypertable.Service --help

For a complete list of all configuration parameters use:

Hypertable.Service --help-config


Note that any changes to the configuration require the Hypertable service (or the affected database servers) to be restarted before they take effect.

Configure verbosity

To change the default logging level use either the command line argument

Hypertable.Service --logging-level <info|warn|notice|error|crit|alert|fatal>

or the configuration parameter.



Configure data directories

The default Hypertable for Windows data directory is located at %ProgramData%\Hypertable. The location can be changed by using the following configuration parameter:

Hypertable.DataDirectory=<hypertable data dir>


Relative to the path defined in the Hypertable.DataDirectory, the default location for the cell store files (using the DFS local broker) is fs/local. The cell store files can either be placed in relation to the Hypertable.DataDirectory by configuring a relative directory name or into a location independent of the Hypertable.DataDirectory by configuring an absolute directory name using the following parameter:

FsBroker.Local.Root=<cell stores root dir>


Related to the path defined in the Hypertable.DataDirectory, the default logging directory is log. The logging directory can be changed by using the following configuration parameter:

Hypertable.Service.Logging.Directory=<logging dir>


Note that all files and directories created by the Hypertable database servers get the default permission (ACL) defined for the user account out of which the servers have been started. Usually the Hypertable service runs in the local system account. Therefore, the created files and directories will not be accessible to other users or to Hypertable itself if started from a different user account. In order to run Hypertable in different user accounts the file permissions, usually just for the Hypertable.DataDirectory, must be adjusted manually.


Configure the Windows service

Changing the service name is required if running more than one service on a single machine. Setting the service name can be achieved by using the following configuration parameters:

Hypertable.Service.Name=<unique service name>
Hypertable.Service.DisplayName=<service display name>


Usually the Hypertable service launches all database servers including the ThriftBroker. Depending on the setup it can be necessary to start and control only a subset of the database servers. The behavior can be changed with the following configuration parameters :


If yes (which is the default value) the service will launch and control the desired database servers. The Hypertable service automatically re-launches the controlled database servers on failovers.

In order to pass additional arguments to the Hypertable service use the following command:

Hypertable.Service --install-service [additional arguments]

The additional arguments will be passed to the service itself at startup and to all database servers launched by the service.


Using the embedded filesystem

The default configuration starts and utilize the local file system broker. If Hypertable runs on a single node then the DFS broker overhead can be eliminated using the embedded file system, which results in better performance. The embedded filesystem can be enabled by using the following configuration parameters:



The DFS broker can be completely disabled by using the following configuration parameter:



Configure range server memory limits

The default configuration is meant to run a Hypertable instance on a dedicated server machine. Therefore, the range server is configured to use up to 50% of the available physical memory for caches. There can be certain reasons for re-configuring the different memory limits to achieve optimum performance under different memory conditions. Especially if Hypertable is used as a mid-range desktop database the memory limits need manual adjustment by using the following configuration parameters:


Hypertable.RangeServer.MemoryLimit=<value in bytes>

Defines the absolute memory limit for the range server caches in bytes. Memory fragmentation and memory used apart from the caches is not taken into account.


Hypertable.RangeServer.MemoryLimit.Percentage=<value in %>

Defines the memory limit as a percentage of the physical RAM for the range server caches.


Hypertable.RangeServer.LowMemoryLimit.Percentage=<value in %>

Defines the amount of memory to be kept free in low memory conditions as a percentage of the range server memory limit. For example, 10% is a reasonable value for the range server memory limit if using Hypertable as a mid-range desktop database.


Hypertable.RangeServer.BlockCache.MinMemory=<value in bytes>

Defines the minimum size of the block cache in bytes.


Hypertable.RangeServer.BlockCache.MaxMemory=<value in bytes>

Defines the maximum (target) size of the block cache in bytes.


Hypertable.RangeServer.QueryCache.MaxMemory=<value in bytes>

Defines the fixed size of the query cache in bytes. The query cache is not dynamic so far.

Below an example is given for a minimum memory configuration:



Configure Range Server proxy name

Running multiple Hypertable instances within a network requires unique location ids for all the range servers accross the Hypertable instances, which must be configured using


this creates an unique location id based on host name and port, or

Hypertable.RangeServer.ProxyName=<unique rs proxy name>


Using environment variables

The following properties expand the environment variable strings and replace them with the values defined for the current user: