Supported Features and Limits

This page describes the v1 Alloy SDK contract for Mesh Storage. The intent is to keep the public surface small, predictable, and hard to misuse.

Supported in v1

Uploads

• Upload .mcap files.
• Upload .json, .yml, and .yaml metadata sidecars.
• Upload one file with upload_file.
• Upload a folder recursively with upload_folder.
• Preserve relative paths inside folder uploads.
• Upload metadata sidecars before MCAP files.
• Choose a Mesh upload path under uploads/sdk-uploads/.
• Let Alloy generate a dated upload path when path is omitted.
• Use sync or async clients.
• Use one-shot helper functions for simple scripts.

Reads

• List files by Mesh prefix.
• List SDK uploads by path.
• List recursively or one folder level at a time.
• Page through list results with continuation_token.
• Download one file by exact Mesh key.

Query

• Query Ready Mesh data through hosted SQL.
• Use typed SQL parameters.
• Return small Python rows.
• Return RowSet metadata and CSV output.
• Return Arrow tables.
• Convert results to pandas, Polars, or DuckDB.
• Stream Arrow batches.
• Use sync or async SQL clients.

Not supported in v1

The SDK does not expose:

• delete
• move
• rename
• overwrite
• raw arbitrary R2 key writes
• direct object-store credentials
• write SQL
• table creation
• direct mission creation
• upload finalize calls
• upload status polling
• cross-org access
• file-id mapping for reads

Path and key limits

Upload path values are folder-like paths below:

uploads/sdk-uploads/

The SDK validates the final object key length before upload. Mesh object keys must fit the storage provider's key size limits.

Processing limits

Uploading a file is not the same as processing it. After upload:

• Replay and Inspect work once the MCAP lands.
• SQL requires the file to reach Ready.
• Failed files need investigation from the Mesh Storage file row.

The SDK does not currently poll processing status. Use Mesh Storage, SQL Workbench, or MCP tools to inspect readiness.

Dependency notes

The base SDK includes the transfer clients required by Mesh Storage. Optional extras are still used for some local result conversions:

If a dependency is missing in a broken environment, the SDK raises a dependency error rather than silently falling back.