# Particles

Write application functions in Python and call them from SQL beside your data.

Source: https://particledb.ai/particles/overview/

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.

## Availability and requirements

Python Particles are included in the free edition: the standard `1.1.19-rc.17` download from the [installer](/installation/binary/) 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`](https://pypi.org/project/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](/sdks/python/).

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.

## Write a function

Save this as `tools.py`:

```python
from particledb import scalar

@scalar
def priority(impact: float, confidence: float) -> float:
    return impact * confidence
```

## Load the module

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

```bash
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](/getting-started/quickstart/) start command:

```bash
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](/particles/loading/) for restarts and durable deployment.

## Call the function

```sql
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:

#### Python

```python
print(db.query("SELECT priority($1, $2) AS score", [0.5, 0.75]))
```

Output:

```
[{'score': 0.375}]
```

#### TypeScript

```typescript
console.log(await db.queryOne('SELECT priority($1, $2) AS score', [0.5, 0.75]));
```

Output:

```
{ score: 0.375 }
```

#### Java

Inside main, with import com.particledb.ParticleDB.

```java
System.out.println(db.queryOne("SELECT priority(?, ?) AS score", 0.5, 0.75));
```

Output:

```
Row{score=0.375}
```

#### Go

Inside func main. Errors are ignored here for brevity; check them in real code.

```go
var score float64
db.QueryRow(ctx, "SELECT priority($1, $2)", 0.5, 0.75).Scan(&score)
fmt.Println(score)
```

Output:

```
0.375
```

#### Rust

Inside fn main() -> particledb_sdk::Result, with use particledb_sdk::{Config, ParticleDB, Value}.

```rust
let args = [Value::Float64(0.5), Value::Float64(0.75)];
let row = db.query_one("SELECT priority($1, $2)", &args)?.unwrap();
println!("{}", row.get::<f64>(0)?);
```

Output:

```
0.375
```

#### SQL

```sql
SELECT priority(0.5, 0.75) AS score;
```

Output:

```
0.375
```

## Continue

[Python functions](/particles/python/) · [Testing](/particles/testing/) · [Runtime and trust](/particles/limits/)

## Related

[Documentation home](/docs/) · [Troubleshooting](/guides/troubleshooting/)
