Skip to content

How the session catalog works

A session whose storage section has a catalog key runs a tiled server on this machine, from build to shutdown, to hold its catalog. Keep a catalog of runs shows how to use it.

What the session sets up

redsun starts the server, keeps its database in <base_dir>/<session>/catalog, and gives its address to any component that asks for a CatalogAddress. It registers nothing in the catalog itself. Acquisition bytes belong to the service and its device (ADR 0013), and the session's components decide whether runs are recorded. Step through to see who does what:

A session with a catalog

A session whose storage section has a catalog key runs a catalog. Its components decide what goes in.

sessionA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build. startsCatalogAddresssubscribesthe run'sdocumentsreadsA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build.
sessionA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build. startsCatalogAddresssubscribesthe run'sdocumentsreadsA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build.

The session starts a tiled server on this machine in its first build step, with its database in a catalog folder inside the session's folder. It stops the server at shutdown, after every component and service.

sessionA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build.tiled serveron this machineThe session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it.catalog databaseThe database lives in a folder named catalog, inside the session's folder under the base directory. startsCatalogAddresssubscribesthe run'sdocumentsreadsA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build. The session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it. The database lives in a folder named catalog, inside the session's folder under the base directory.
sessionA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build.tiled serveron this machineThe session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it.catalog databaseThe database lives in a folder named catalog, inside the session's folder under the base directory. startsCatalogAddresssubscribesthe run'sdocumentsreadsA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build. The session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it. The database lives in a folder named catalog, inside the session's folder under the base directory.

Any component can ask for a CatalogAddress, and opens its own client with tiled's from_uri.

sessionA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build.tiled serveron this machineThe session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it.catalog databaseThe database lives in a folder named catalog, inside the session's folder under the base directory.componentAny component can ask for a CatalogAddress, and opens its own client with tiled's from_uri, which gives it the whole client API. startsCatalogAddresssubscribesthe run'sdocumentsreadsA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build. The session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it. The database lives in a folder named catalog, inside the session's folder under the base directory. Any component can ask for a CatalogAddress, and opens its own client with tiled's from_uri, which gives it the whole client API.
sessionA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build.tiled serveron this machineThe session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it.catalog databaseThe database lives in a folder named catalog, inside the session's folder under the base directory.componentAny component can ask for a CatalogAddress, and opens its own client with tiled's from_uri, which gives it the whole client API. startsCatalogAddresssubscribesthe run'sdocumentsreadsA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build. The session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it. The database lives in a folder named catalog, inside the session's folder under the base directory. Any component can ask for a CatalogAddress, and opens its own client with tiled's from_uri, which gives it the whole client API.

A component that wants runs recorded subscribes a TiledWriter, from bluesky-tiled-plugins, which sends each run's documents to the server.

sessionA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build.tiled serveron this machineThe session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it.catalog databaseThe database lives in a folder named catalog, inside the session's folder under the base directory.componentAny component can ask for a CatalogAddress, and opens its own client with tiled's from_uri, which gives it the whole client API.TiledWritera document callbackTiledWriter, from bluesky-tiled-plugins, writes a run's documents into the catalog. The component decides whether to subscribe one. startsCatalogAddresssubscribesthe run'sdocumentsreadsA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build. The session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it. The database lives in a folder named catalog, inside the session's folder under the base directory. Any component can ask for a CatalogAddress, and opens its own client with tiled's from_uri, which gives it the whole client API. TiledWriter, from bluesky-tiled-plugins, writes a run's documents into the catalog. The component decides whether to subscribe one.
sessionA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build.tiled serveron this machineThe session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it.catalog databaseThe database lives in a folder named catalog, inside the session's folder under the base directory.componentAny component can ask for a CatalogAddress, and opens its own client with tiled's from_uri, which gives it the whole client API.TiledWritera document callbackTiledWriter, from bluesky-tiled-plugins, writes a run's documents into the catalog. The component decides whether to subscribe one. startsCatalogAddresssubscribesthe run'sdocumentsreadsA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build. The session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it. The database lives in a folder named catalog, inside the session's folder under the base directory. Any component can ask for a CatalogAddress, and opens its own client with tiled's from_uri, which gives it the whole client API. TiledWriter, from bluesky-tiled-plugins, writes a run's documents into the catalog. The component decides whether to subscribe one.

The server reads the frames from the camera's store, but only from the session's directory and the directories storage.catalog lists under readable.

sessionA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build.tiled serveron this machineThe session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it.catalog databaseThe database lives in a folder named catalog, inside the session's folder under the base directory.componentAny component can ask for a CatalogAddress, and opens its own client with tiled's from_uri, which gives it the whole client API.TiledWritera document callbackTiledWriter, from bluesky-tiled-plugins, writes a run's documents into the catalog. The component decides whether to subscribe one.the camera's storeOME-ZarrThe server reads files only from the session's directory and the directories storage.catalog lists under readable. It serves an OME-Zarr image as one array whose dims are its axis names. startsCatalogAddresssubscribesthe run'sdocumentsreadsA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build. The session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it. The database lives in a folder named catalog, inside the session's folder under the base directory. Any component can ask for a CatalogAddress, and opens its own client with tiled's from_uri, which gives it the whole client API. TiledWriter, from bluesky-tiled-plugins, writes a run's documents into the catalog. The component decides whether to subscribe one. The server reads files only from the session's directory and the directories storage.catalog lists under readable. It serves an OME-Zarr image as one array whose dims are its axis names.
sessionA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build.tiled serveron this machineThe session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it.catalog databaseThe database lives in a folder named catalog, inside the session's folder under the base directory.componentAny component can ask for a CatalogAddress, and opens its own client with tiled's from_uri, which gives it the whole client API.TiledWritera document callbackTiledWriter, from bluesky-tiled-plugins, writes a run's documents into the catalog. The component decides whether to subscribe one.the camera's storeOME-ZarrThe server reads files only from the session's directory and the directories storage.catalog lists under readable. It serves an OME-Zarr image as one array whose dims are its axis names. startsCatalogAddresssubscribesthe run'sdocumentsreadsA session whose storage section has a catalog key. Without the tiled extra installed, it refuses to build. The session starts the server in its first build step and stops it at shutdown, after every component and service. A server that fails to start is logged, and the session carries on without it. The database lives in a folder named catalog, inside the session's folder under the base directory. Any component can ask for a CatalogAddress, and opens its own client with tiled's from_uri, which gives it the whole client API. TiledWriter, from bluesky-tiled-plugins, writes a run's documents into the catalog. The component decides whether to subscribe one. The server reads files only from the session's directory and the directories storage.catalog lists under readable. It serves an OME-Zarr image as one array whose dims are its axis names.

The server reads application/x-ome-zarr files with ome-tiled, whose consolidator the session registers for TiledWriter. A consolidator turns a StreamResource and its StreamDatum documents into one catalog entry; this one reads the image's shape, chunks and axis names from its store rather than from the documents.

One catalog per session

A catalog indexes only the runs of its own session, so to ask a question across sessions you open each catalog. In exchange, everything a session produced lives under one directory, which you can archive or delete as a unit.

Overwriting a registered file

Registering a file doesn't protect it: tiled's write, write_block and patch reach a registered file like any other, and management=external forbids nothing. write_block is the hardest to notice, since it replaces one chunk and the file still reads correctly.

A client can overwrite a registered file

redsun calls none of these routes, but a component holding a client can. If your component writes into the catalog, have it create its own nodes, as client[run_uid].write_array(...) does, and leave registered ones alone.