pxt schema update and pxt service update do, and what the last argument names.
One Python file declares tables and, if you want endpoints, routes. pxt schema update creates the tables. pxt service update starts the endpoints on an assigned port. The last argument is a catalog such as my_app, or a pxt://org:db URI for Cloud. It does not create a folder beside app.py.
Schema
A
TableModel becomes a table. pxt schema update creates and migrates it.Services
A
FastAPIRouter in the same file. pxt service update binds it to the tables.Database
A local catalog, or a
pxt:// URI for Cloud.app.py and usually pixeltable.toml. After pxt schema update, Python loads the table as pxt.get_table('my_app.docs'). Inspect with pxt ls my_app. Layout: Infrastructure.
pxt schema and pxt service both have these subcommands:
Full flags: CLI.
Schema
An annotation (title: pxt.String) is a stored column: you insert that value. A bare type is required; use pxt.String | None when the value may be missing. Cast a JSON path such as transcript.text with .astype(pxt.String | None) when the value can be missing. .astype(pxt.String) aborts the insert if the value is None. An assignment (title_upper = ...) is a computed column. It runs on insert and on update. Use pxt.Column(...) when you need a primary key, stored=False, or a media option an annotation cannot express.
Set base=Docs to make a view of Docs. The view can use columns from that base. Add an iterator when each input row should become many output rows, such as frames or chunks. A view (base=) cannot use group_by, aggregates, order_by, limit, or join. .group_by() on that view is allowed at query time (Views). Indexes belong on the model (__indexes__ with EmbeddingIndex or BtreeIndex). B-tree indexes are not created automatically. Do not call add_embedding_index() after pxt schema update.
pxt schema example writes a long sample. --brief writes only a small set of classes. Create tables with pxt schema update app.py my_app. Extra tables in that namespace stay until you run pxt schema prune, which deletes them.
pxt schema update imports app.py as a module, so a @pxt.udf there is recorded by file path. A UDF defined in a script you run with python app.py is refused. Renaming app.py leaves columns that call it unable to compute. On Cloud, pxt db update puts the project in the image so workers can resolve that path (Deploy to Pixeltable Cloud).
Services
The same file declares aFastAPIRouter. pxt service update starts it against tables that already exist. Run pxt schema update first. pxt service list prints the URL; the port is assigned. Do not hard-code :8000 for pxt service update.
An insert route writes a row and returns the columns listed in outputs. A compute route runs those columns and writes no row. Update and delete match a row (primary key by default). File uploads, background jobs, query routes, and mounting on your own FastAPI app: HTTP serving.
A schema change with a service already running needs pxt service update after pxt schema update. If you only change routes, run pxt service update again; it restarts the services whose routes changed. Inspect with pxt dashboard, pxt ls, and pxt errors.
Database
- Local
- Cloud
No Cloud account. Follow the Quickstart. For which process should listen, see Self-hosting.
Next
Cloud
Use the same
app.py with a hosted URL such as pxt://your-org:your-db.Self-hosting
Which process: nothing listening, your FastAPI, or
pxt service.