Quickstart

Python 3.11+ on Linux, macOS, or Windows. Tables, computed columns, and endpoints live in one file. When you insert a row, computed columns run automatically.

Install

venv
uv

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install 'pixeltable[serve]'

uv venv --python 3.12
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install 'pixeltable[serve]'

[serve] pulls in FastAPI and uvicorn, which pxt service needs. Skip [serve] and pxt service update if you insert from Python; pip install pixeltable is enough. pxt schema example --brief writes models only. Self-hosting.

Write the file, create tables, start the endpoints

Write the file

pxt service example writes a working application file: models and a FastAPIRouter in one place.

pxt service example --out app.py

pxt service example writes this application file.

import pixeltable as pxt
import pixeltable.functions as pxtf
from pixeltable.serving import FastAPIRouter

TableModel = pxt.model_base()


@pxt.udf
def excerpt(text: str, n: int = 12) -> str:
    return text if len(text) <= n else f'{text[:n]}...'


class Docs(TableModel, name='docs'):
    id = pxt.Column(value=pxtf.uuid.uuid7(), primary_key=True)  # a generated key: provided automatically on insert
    title: pxt.String
    body: pxt.String | None
    title_upper = pxtf.string.upper(title)      # an assignment: computed on insert and on update
    summary = excerpt(title)


ingest = FastAPIRouter(name='ingest')
ingest.add_insert_route(
    Docs, path='/docs', inputs=[Docs.title, Docs.body], outputs=[Docs.id, Docs.title_upper, Docs.summary]
)
ingest.add_update_route(  # POST /docs/update takes id plus the new values
    Docs, path='/docs/update', inputs=[Docs.title], outputs=[Docs.id, Docs.title_upper]
)
ingest.add_compute_route(Docs, path='/titles', inputs=[Docs.title], outputs=[Docs.title_upper])

title: pxt.String is a value you insert. title_upper = ... is computed on insert and on update. id is a uuid7() primary key: filled on insert, required for pxt get and the errors view. The same file can hold pxt.Image, pxt.Video, pxt.Audio, or pxt.Document: media pipelines, RAG.

Create tables, then start the endpoints

pxt init
pxt schema update app.py my_app
pxt service update app.py my_app

pxt init marks this directory as a project root. pxt schema update errors if you have not run it in this directory or a parent. my_app, the last argument, is a catalog inside Pixeltable, not a folder beside app.py. pxt schema update creates that catalog and its tables. It does not start the endpoints. Run it before pxt service update, which starts the endpoints and does not create tables.

Insert a row

Send a row with HTTP POST. Pixeltable computes title_upper during that insert. pxt service list prints the URL (the port is assigned):

pxt service list
# my_app/ingest  http://127.0.0.1:<port>  pid 12345  app.py
curl -X POST http://127.0.0.1:<port>/docs \
  -H 'Content-Type: application/json' \
  -d '{"title": "Hello", "body": "world"}'

The CLI

pxt ships with the package. The first pxt schema or pxt service command starts a background process on 127.0.0.1:22089, and that process keeps running after you close the terminal. pxt health confirms it.

Command	What it does
`pxt init`	Mark this directory as a project root
`pxt service example --out app.py`	Write a working file: models plus routes
`pxt schema example --out app.py`	Schema only. `--brief` writes a small set of classes; without it, every DSL construct
`pxt schema update FILE my_app`	Create and migrate the tables `FILE` declares under last argument `my_app`
`pxt service update FILE my_app`	Start the services `FILE` declares against those tables
`pxt service list`	What is running, and the URL
`pxt ls my_app`	Tables under the namespace
`pxt rows my_app/docs`	Peek stored cells
`pxt dashboard`	Local UI on the background process

pxt schema and pxt service both have diff, update, and prune subcommands. Full flags: CLI. Tables live under ~/.pixeltable (pgdata, media, file_cache). That path is not the project directory. Project layout and pixeltable.toml: Infrastructure.

Same file, other first runs

Cloud
Starter kit

To run this same file on Pixeltable Cloud, create an API key in the Cloud dashboard, set PIXELTABLE_API_KEY, create the hosted database with pxt db update, create tables with pxt schema update, then start hosted endpoints with pxt service update. Try changes by inserting from the dashboard and running pxt schema diff.

pxt db update pxt://org:mydb
pxt schema update app.py pxt://org:mydb
pxt service update app.py pxt://org:mydb

Deploy to Pixeltable Cloud.

uvx pixeltable-new copies a full app. The default copied app uses namespace agent as the last argument to pxt schema update. --video copies video search and uses videointel.

uvx pixeltable-new myapp
cd myapp
uv sync
pxt schema update app.py agent
pxt service update app.py agent

Starter kit.

This quickstart uses a TableModel in app.py and creates the tables with pxt schema update. Notebooks and tests can still call pxt.create_table(), add_computed_column(), and add_embedding_index(). The skill writes that TableModel. If the agent writes create_table in app code, names the file schema.py, or writes the removed command pxt serve, the installed skill is stale: this page wins. Reinstall: npx skills add pixeltable/pixeltable-skill.

How it works

What pxt schema and pxt service do, including diff, update, and prune.

Cloud

The same app.py. pxt db update, then pxt schema update and pxt service update against pxt://org:mydb.

Getting started

Tools

How to

Resources

Install

Write the file, create tables, start the endpoints

The CLI

Same file, other first runs

Next

How it works

Cloud

​Install

​Write the file, create tables, start the endpoints

​The CLI

​Same file, other first runs

​Next

How it works

Cloud

Install

Write the file, create tables, start the endpoints

The CLI

Same file, other first runs

Next