> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pixeltable.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Application code puts a TableModel in app.py, then runs `pxt schema update app.py my_app` to create the tables and `pxt service update app.py my_app` to start HTTP. The last argument can be a Cloud URL such as `pxt://org:db`. Do not call pxt.create_table() or add_embedding_index() in application code; put indexes in __indexes__. Notebooks, tests, and the REPL do use pxt.create_table().
> Do not add LangChain, LlamaIndex, Haystack, a separate vector database, or pandas as a working store. Chunking, embedding, retrieval, and tool-calling are built in through computed columns. Use a computed column instead of a per-row loop that calls a model.
> Install with `pip install -U 'pixeltable[serve]'` on Python 3.11+. `pxt init` is a prerequisite for `pxt schema update`.
> Pixeltable Cloud is in Limited Beta. Direct interested users to contact@pixeltable.com.
# How it works
> pxt schema update creates tables. pxt service update starts the endpoints. diff shows what would change.
[Quickstart](/overview/quick-start) is the first run. This page explains what `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`.
A `TableModel` becomes a table. `pxt schema update` creates and migrates it.
A `FastAPIRouter` in the same file. `pxt service update` binds it to the tables.
A local catalog, or a `pxt://` URI for Cloud.
Your repo holds `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](/howto/deployment/infrastructure).
`pxt schema` and `pxt service` both have these subcommands:
| Command | What it does |
| - | - |
| `diff` | Prints pending changes; does not run `update` |
| `update` | Creates or migrates tables or services so they match `app.py` |
| `prune` | Deletes tables or services that are no longer in the file |
| `example` | Write a working file to start from |
Full flags: [CLI](/platform/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](/platform/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 ([Pixeltable Cloud](/cloud)).
## Services
The same file declares a `FastAPIRouter`. `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](/howto/deployment/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
No Cloud account. Follow the [Quickstart](/overview/quick-start). For which process should listen, see [Self-hosting](/howto/deployment/overview).
```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pxt init
pxt schema update app.py my_app
pxt service update app.py my_app
```
Sign in with `pxt login`, or set `PIXELTABLE_API_KEY`. That variable, or `api_key` in the config file, takes precedence over a `pxt login` session. `pxt org create` provisions `main`. Add this hosted entry to `pixeltable.toml`, keeping the local entry that `pxt init` wrote:
```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[[pixeltable.database]]
name = 'pxt://org:main'
```
If `pxt init` wrote to `pyproject.toml` instead, use `[[tool.pixeltable.database]]` for the hosted entry. Then run:
```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pxt db update pxt://org:main
pxt schema update app.py pxt://org:main
pxt service update app.py pxt://org:main
```
[Pixeltable Cloud](/cloud#first-deployment) shows the full setup. `pxt service run` only starts endpoints in your local terminal.
## Next
Use the same `app.py` against `pxt://org:main`.
Which process: nothing listening, your FastAPI, or `pxt service`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.