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.

The VoltDB client libraries, for accessing VoltDB databases programmatically, are licensed separately under the MIT 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, 9,639,571, 10,067,999, 10,176,240, and 10,268,707. 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 Scalar Function
8.2. Writing a User-Defined Aggregate Function
8.3. Loading User-Defined Functions into the Database
8.4. Declaring a User-Defined Function
8.5. Invoking User-Defined Functions in SQL Statements
9. Creating Custom Tasks
9.1. Overview of How Custom Tasks Work
9.2. Modifying the Procedure Call and Arguments
9.2.1. Designing a Java Class That Implements ActionGenerator
9.2.2. Compiling and Loading the Class into VoltDB
9.2.3. Declaring the Task
9.3. Modifying the Interval Between Invocations
9.3.1. Designing a Java Class That Implements IntervalGenerator
9.3.2. Compiling and Loading the Class into VoltDB
9.3.3. Declaring the Task
9.4. Modifying Both the Procedure and Interval
9.4.1. Designing a Java Class That Implements ActionScheduler
9.4.2. Compiling and Loading the Class into VoltDB
9.4.3. Declaring the Task
10. Understanding VoltDB Memory Usage
10.1. How VoltDB Uses Memory
10.2. Actions that Impact Memory Usage
10.3. How VoltDB Manages Memory
10.4. How Memory is Allocated and Deallocated
10.5. Controlling How Memory is Allocated
10.6. Understanding Memory Usage for Specific Applications
11. Managing Time
11.1. The Importance of Time
11.2. Using NTP to Manage Time
11.2.1. Basic Configuration
11.2.2. Troubleshooting Issues with Time
11.2.3. Correcting Common Problems with Time
11.2.4. Example NTP Configuration
11.3. Configuring NTP in a Hosted, Virtual, or Cloud Environment
11.3.1. Considerations for Hosted Environments
11.3.2. Considerations for Virtual and Cloud Environments