Skip to content

Build a retail app with the Aerospike Python SDK and Voyager

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Objectives

By the end of this tutorial, you will be able to:

  • Connect a Python application to Aerospike Database using the Aerospike Python SDK.
  • Implement dict-based insert, point-read, and secondary-index query methods.
  • Build flexible multi-condition queries with the Aerospike Expression Language (AEL).
  • Implement a check-and-set update for a nested map document representing a shopping cart.
  • Use Aerospike Voyager to inspect, filter, and edit records in a live cluster.

This tutorial walks you through writing the database layer of a simple retail application using the Aerospike Python SDK and inspecting the resulting data with Aerospike Voyager. You start with a FastAPI application whose data-access methods are stubbed out, then implement each method step by step. As you go, you use Voyager to verify your work, build filter expressions visually, and edit data directly in the cluster.

The sample application, UI, and product data are in the same workshop repository used by the Java SDK version of this tutorial. Only the backend language and SDK differ.

If you are new to Aerospike, read the Data model guide first. It explains namespaces, sets, records, bins, and keys in the terms you will see in Voyager and in this tutorial.

The Aerospike Python SDK

The Aerospike Python SDK uses a fluent style: each method call adds one piece of an operation to a builder, the chain reads top to bottom, and you end with await ...execute() to send the request to the cluster. In Store and load products, you walk through how connect() wires up ClusterDefinition, Behavior, and Session.

The workshop uses the SDK’s async API because FastAPI is async-native. The SDK also offers a sync API if you prefer blocking calls. This tutorial uses async throughout because the sample app is FastAPI-based. Reads and writes return result streams that you iterate with async for. Business objects (Product, Cart) are converted to and from Aerospike bins with helper methods such as Product.to_bins() and Product.from_bins(). Queries use the Aerospike Expression Language (AEL) to filter records, and the SDK chooses the best matching secondary index for you automatically.

Aerospike Voyager

Aerospike Voyager is a desktop tool available for macOS, Windows, and Linux that lets you connect to one or more Aerospike clusters, browse data, build filter expressions visually, and edit records in place.

Voyager main window with three columns: left-hand toolbar, middle cluster list, and right-hand cluster details panel

In this tutorial, you use Voyager to:

  • Connect to the local Aerospike cluster started by Docker Compose.
  • Confirm that your store_product implementation writes all 200 sample records.
  • Build an AEL filter visually by selecting a bin and value, then copy the generated expression directly into your Python code.
  • Inspect the nested map structure of a shopping-cart record and edit it as JSON.