Skip to content
ParticleDB
Release candidateParticleDB 1.1.19-rc.17 is not yet GA or ready for production data.Release status →

Particles

A Particle is application code registered as a SQL function. Use it for scoring, normalization and transformations that belong beside the records they operate on.

Python Particles are included in the free edition: the standard 1.1.19-rc.17 download from the installer runs them. The server links no Python library. It starts python3 worker processes on the server host, so that host needs:

  • Python 3.11 or newer as python3 on the server’s PATH.
  • The particledb package installed for that interpreter. It provides the @scalar, @aggregate and @window annotations and the module loader the server runs at startup. It is the same package as the Python SDK.

To use a specific interpreter, such as one in a virtual environment, set PDB_PARTICLES_PYTHON to its path when you start the server. Version 3.11 is the minimum because the particledb package requires it; the macOS system Python 3.9 cannot install it.

Save this as tools.py:

from particledb import scalar
@scalar
def priority(impact: float, confidence: float) -> float:
return impact * confidence

Install the package into a virtual environment and point the server at its interpreter:

Terminal window
python3 -m venv .venv
.venv/bin/pip install particledb
export PDB_PARTICLES_PYTHON="$PWD/.venv/bin/python"

Start the server with --python-functions, added to the quickstart start command:

Terminal window
particledb start \
--data-dir ./pdb-particles \
--http-addr 127.0.0.1:7173 \
--pg-addr 127.0.0.1:5432 \
--redis-addr 127.0.0.1:6379 \
--mysql-addr 127.0.0.1:3307 \
--metrics-addr 127.0.0.1:7175 \
--no-unix-sockets \
--no-auth \
--python-functions ./tools.py

The server reads the module at startup and registers each annotated function. If the module cannot be loaded, the server does not start and prints the reason. See loading and deployment for restarts and durable deployment.

SELECT priority(0.9, 0.8) AS score;

The score is 0.72, subject to normal floating-point representation.

From a client, call it like any other function:

Uses db from the connect example.

print(db.query("SELECT priority($1, $2) AS score", [0.5, 0.75]))
Output
[{'score': 0.375}]

Python functions · Testing · Runtime and trust

Documentation home · Troubleshooting