Guide to Performance and Customization


VoltDB Home » Documentation » Guide to Performance and Customization

Guide to Performance and Customization


The text and illustrations in this document are licensed under the terms of the GNU Affero General Public License Version 3 as published by the Free Software Foundation. See the GNU Affero General Public License ( for more details.

Many of the core VoltDB database features described herein are part of the VoltDB Community Edition, which is licensed under the GNU Affero Public License 3 as published by the Free Software Foundation. Other features are specific to the VoltDB Enterprise Edition and VoltDB Pro, which are distributed by VoltDB, Inc. under a commercial license. Your rights to access and use VoltDB features described herein are defined by the license you received when you acquired the software.

VoltDB is a trademark of VoltDB, Inc.

VoltDB software is protected by U.S. Patent Nos. 9,600,514 and 9,639,571. Other patents pending.


This book explains how to optimize application performance and customize database features using VoltDB.

Table of Contents

1. Organization of this Manual
2. Other Resources
1. Introduction
1.1. What Affects Performance?
1.2. How to Use This Book
2. Hello, World! Revisited
2.1. Optimizing your Application for VoltDB
2.2. Applying Hello World to a Practical Problem
2.3. Partitioned vs. Replicated Tables
2.3.1. Defining the Partitioning Column
2.3.2. Creating the Stored Procedures
2.4. Using Asynchronous Stored Procedure Calls
2.4.1. Understanding Asynchronous Programming
2.4.2. The Callback Procedure
2.4.3. Making an Asynchronous Procedure Call
2.5. Connecting to all Servers
2.6. Putting it All Together
2.7. Next Steps
3. Understanding VoltDB Execution Plans
3.1. How VoltDB Selects Execution Plans for Individual SQL Statements
3.2. Understanding VoltDB Execution Plans
3.3. Reading the Execution Plan and Optimizing Your SQL Statements
3.3.1. Evaluating the Use of Indexes
3.3.2. Evaluating the Table Order for Joins
4. Using Indexes Effectively
4.1. Basic Principles for Effective Indexing
4.2. Defining Indexes
4.3. The Goals for Effective Indexing
4.4. How Indexes Work
4.5. Summary
5. Creating Flexible Schemas With JSON
5.1. Using JSON Data Structures as VoltDB Content
5.2. Querying JSON Data
5.3. Updating JSON Data
5.4. Indexing JSON Fields
5.5. Summary: Using JSON in VoltDB
6. Creating Geospatial Applications
6.1. The Geospatial Datatypes
6.1.1. The GEOGRAPHY_POINT Datatype
6.1.2. The GEOGRAPHY Datatype
6.1.3. Sizing GEOGRAPHY Columns
6.1.4. How Geospatial Values are Interpreted
6.2. Entering Geospatial Data
6.3. Working With Geospatial Data
6.3.1. Working With Locations
6.3.2. Working With Regions
7. Creating Custom Importers, Exporters, and Formatters
7.1. Writing a Custom Exporter
7.1.1. The Structure and Workflow of the Export Client
7.1.2. How to Use Custom Properties to Configure the Client
7.1.3. How to Compile and Install the Client
7.1.4. How to Configure the Export Client
7.2. Writing a Custom Importer
7.2.1. Designing and Coding a Custom Importer
7.2.2. Packaging and Installing a Custom Importer
7.2.3. Configuring and Running a Custom Importer
7.3. Writing a Custom Formatter
7.3.1. The Structure of the Custom Formatter
7.3.2. Compiling and Packaging Custom Formatter Bundles
7.3.3. Installing and Invoking Custom Formatters
7.3.4. Using Custom Formatters With the kafkaloader Utility
8. Creating Custom SQL Functions
8.1. Writing a User-Defined Function
8.2. Loading a User-Defined Function into the Database
8.3. Declaring a User-Defined Function
8.4. Invoking User-Defined Functions in SQL Statements
9. Understanding VoltDB Memory Usage
9.1. How VoltDB Uses Memory
9.2. Actions that Impact Memory Usage
9.3. How VoltDB Manages Memory
9.4. How Memory is Allocated and Deallocated
9.5. Controlling How Memory is Allocated
9.6. Understanding Memory Usage for Specific Applications
10. Managing Time
10.1. The Importance of Time
10.2. Using NTP to Manage Time
10.2.1. Basic Configuration
10.2.2. Troubleshooting Issues with Time
10.2.3. Correcting Common Problems with Time
10.2.4. Example NTP Configuration
10.3. Configuring NTP in a Hosted, Virtual, or Cloud Environment
10.3.1. Considerations for Hosted Environments
10.3.2. Considerations for Virtual and Cloud Environments

List of Examples

10.1. Custom NTP Configuration File