Quickstart

You’ll install Pixeltable, write one file, create its table, start its service and POST a row. The example calls no model, so you need no API key and no account. You need Python 3.11 or later, on Linux, macOS or Windows.

Install Pixeltable

Make a folder for the project, with a virtual environment in it:

venv
uv

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

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

The package installs the pxt command. The [serve] extra adds FastAPI and uvicorn, which pxt service uses to serve your routes. If you only plan to insert from Python, pip install pixeltable is enough and you can skip the service steps below.

Make the folder a project

pxt init

This writes pixeltable.toml, which makes my-app the project root. Pixeltable records each function you write for your columns by its module path from that root, app.excerpt for the one in the next step, so it can import the function again when it computes your columns.

Write app.py

pxt service example --out app.py

That writes a working app. Without its comments, it’s this:

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)
    title: pxt.String
    body: pxt.String | None
    title_upper = pxtf.string.upper(title)
    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(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])

Docs is a table named docs. A line with a colon is a column you insert: every row needs a title, and body can be left out because its type allows None. A line with = is a computed column. Pixeltable fills in title_upper and summary on every insert, and again when an update changes title. summary calls excerpt(), an ordinary Python function that @pxt.udf lets a column call. id is a key Pixeltable generates on insert, and the update route uses it to find the row.ingest is a service with three routes over Docs. POST /docs inserts a row and returns its key and computed columns. POST /docs/update changes a row’s title. POST /titles computes title_upper for a title and stores nothing.

Create the table

pxt schema update app.py my_app

created   my_app/docs

my_app, the last argument, is a catalog directory, and pxt schema update creates it along with the docs table. It isn’t a folder on disk.The first pxt command that needs the catalog starts the Pixeltable daemon, a background process that runs the local database. It keeps running after you close the terminal, and it reads your environment once, when it starts: export API keys before your first pxt command, or run pxt daemon restart after. The data lives in Pixeltable’s home directory, outside my-app. Infrastructure has the layout.

Start the service

pxt service update app.py my_app

It asks before it starts anything. Type y:

start or restart 1 service(s)? [y/N] y
+ ingest                   applied  http://127.0.0.1:54140
    route 'POST /docs' will be added  [additive]
    route 'POST /docs/update' will be added  [additive]
    route 'POST /titles' will be added  [additive]

Plan: 1 start, 0 restart, 0 unchanged, 0 extra

The service runs in the background, on a port Pixeltable picks: 54140 here, something else for you. pxt service list prints the URL and the routes again whenever you need them. In a script or in CI, where nothing can answer the prompt, add -f.

POST a row

Use your port in place of 54140:

curl -X POST http://127.0.0.1:54140/docs \
  -H 'Content-Type: application/json' \
  -d '{"title": "Hello", "body": "world"}'

{"id":"01a161d3-f18e-74e7-94a0-75bddaea7f0a","title_upper":"HELLO","summary":"Hello"}

You sent title and body. Before it answered, Pixeltable stored the row, generated its id, and computed title_upper and summary. pxt rows my_app/docs shows the row, pxt dashboard opens a local UI over the catalog, and in Python pxt.get_table('my_app.docs').collect() returns it.

Change a column

This is the loop you’ll repeat most. In app.py, cut the excerpt at 3 characters:

class Docs(TableModel, name='docs'):
    ...
    summary = excerpt(title, n=3)

See what that changes:

pxt schema diff app.py my_app

~ my_app/docs              update
    ~ the value expression of computed column 'summary' will be updated; existing values will not be recomputed  safe

Plan: 0 create, 1 update, 0 unchanged, 0 extra  |  0 destructive

pxt schema update changes the table, and pxt service update restarts the service so it picks up the new definition. Until you restart it, the service answers inserts with HTTP 409.

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

New rows get the 3-character excerpt, like Wor... for World. The Hello row keeps its old one until you recompute it:

pxt recompute my_app/docs summary

That reruns summary on every existing row, along with anything computed from it, and leaves the other columns alone. It asks before it starts, since on a column that calls a model, a recompute costs real money.

Stop when you're done

pxt service stop my_app/ingest
pxt daemon stop

The first command stops the service, and the second stops the daemon. The table and its rows stay. pxt service update app.py my_app starts the service again, on a new port.

You now have the whole loop: edit app.py, run pxt schema update, then pxt service update. The README’s video example is the same pattern with model calls: a video column, then columns for its audio, transcript and summary. To call a real model, add a column like the ones in RAG and live APIs or Media pipelines. For complete apps, browse awesome-pixeltable-apps.

How it works

What each line of app.py means, and what diff, update and prune do with it.

Pixeltable Cloud

The same app.py on a hosted database, from pxt login to a running service.

Getting started

Tools

How to

Resources

Next

How it works

Pixeltable Cloud

​Next

How it works

Pixeltable Cloud

Next