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. A Modern Java Client Programming Interface (API) for VoltDB
5.1. Configuring the Client
5.2. Connecting to the Database
5.3. Calling Procedures
5.3.1. Handling Backpressure
5.3.2. Handling Request Timeouts
5.3.3. Defining Options on a Per-Call Basis
6. Prioritizing Transactions
6.1. How Prioritizing Transactions Works
6.2. Enabling Prioritized Transactions
6.3. Prioritizing Transactions at Runtime
6.4. Prioritizing Other Types of Transactions
7. Creating Flexible Schemas With JSON
7.1. Using JSON Data Structures as VoltDB Content
7.2. Querying JSON Data
7.3. Updating JSON Data
7.4. Indexing JSON Fields
7.5. Summary: Using JSON in VoltDB
8. Creating Geospatial Applications
8.1. The Geospatial Datatypes
8.1.1. The GEOGRAPHY_POINT Datatype
8.1.2. The GEOGRAPHY Datatype
8.1.3. Sizing GEOGRAPHY Columns
8.1.4. How Geospatial Values are Interpreted
8.2. Entering Geospatial Data
8.3. Working With Geospatial Data
8.3.1. Working With Locations
8.3.2. Working With Regions
9. Creating Custom Importers, Exporters, and Formatters
9.1. Writing a Custom Exporter
9.1.1. The Structure and Workflow of the Export Client
9.1.2. How to Use Custom Properties to Configure the Client
9.1.3. How to Compile and Install the Client
9.1.4. How to Configure the Export Client
9.2. Writing a Custom Importer
9.2.1. Designing and Coding a Custom Importer
9.2.2. Packaging and Installing a Custom Importer
9.2.3. Configuring and Running a Custom Importer
9.3. Writing a Custom Formatter
9.3.1. The Structure of the Custom Formatter
9.3.2. Compiling and Packaging Custom Formatter Bundles
9.3.3. Installing and Invoking Custom Formatters
9.3.4. Using Custom Formatters With the kafkaloader Utility
10. Creating Custom SQL Functions
10.1. Writing a User-Defined Scalar Function
10.2. Writing a User-Defined Aggregate Function
10.3. Loading User-Defined Functions into the Database
10.4. Declaring a User-Defined Function
10.5. Invoking User-Defined Functions in SQL Statements
11. Creating Custom Tasks
11.1. Overview of How Custom Tasks Work
11.2. Modifying the Procedure Call and Arguments
11.2.1. Designing a Java Class That Implements ActionGenerator
11.2.2. Compiling and Loading the Class into VoltDB
11.2.3. Declaring the Task
11.3. Modifying the Interval Between Invocations
11.3.1. Designing a Java Class That Implements IntervalGenerator
11.3.2. Compiling and Loading the Class into VoltDB
11.3.3. Declaring the Task
11.4. Modifying Both the Procedure and Interval
11.4.1. Designing a Java Class That Implements ActionScheduler
11.4.2. Compiling and Loading the Class into VoltDB
11.4.3. Declaring the Task
12. Understanding VoltDB Memory Usage
12.1. How VoltDB Uses Memory
12.2. Actions that Impact Memory Usage
12.3. How VoltDB Manages Memory
12.4. How Memory is Allocated and Deallocated
12.5. Controlling How Memory is Allocated
12.6. Understanding Memory Usage for Specific Applications
13. Managing Time
13.1. The Importance of Time
13.2. Using NTP to Manage Time
13.2.1. Basic Configuration
13.2.2. Troubleshooting Issues with Time
13.2.3. Correcting Common Problems with Time
13.2.4. Example NTP Configuration
13.3. Configuring NTP in a Hosted, Virtual, or Cloud Environment
13.3.1. Considerations for Hosted Environments
13.3.2. Considerations for Virtual and Cloud Environments