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

Particle names and errors

A scalar Particle cannot use the name of a built-in scalar function. For example, this module is rejected when loaded because upper is already a built-in:

from particledb import scalar
@scalar
def upper(value: str) -> str:
return value

Use a name that describes your application operation, such as customer_priority or normalize_account_name. Rename the Python function and update its SQL callers together.

A rejected startup module prevents the server from starting. The startup error names the module and the reason, for example particle upper rejected: cannot create particle "upper": a built-in function with that name already exists. Check it before sending queries. Keep the previous module available so you can restore a working configuration.

Test module changes on a disposable server before applying them to an application server. See loading.

The strict scalar function from your first Particle returns NULL when an argument is NULL:

SELECT priority(NULL, 0.8) AS missing_score;

The result is SQL NULL. Test this behavior again if you change the function’s null-handling options.

An exception raised by a function fails the statement with SQLSTATE 38000; an exceeded time budget fails it with 57014 (see limits). Handle a failed function call as a failed database statement. Within a transaction, roll back a failed transaction before reusing the connection. Fix invalid inputs or function code before retrying; retrying the same deterministic failure will not resolve it.

Test Particles · Handle database errors · Best practices