Mesh Storage
Quickstart
Install alloy-sdk, upload a folder, query ingested data, and download a file
This quickstart uploads one local run into Mesh Storage, lists the uploaded files, and runs a hosted SQL query once the files show Ingested.
Install
The SDK needs Python 3.12. It does not install on Python 3.11 or 3.13.
pip install alloy-sdkThe SDK includes the transfer clients it needs for Mesh uploads and downloads.
Configure credentials
Create an API key in Mesh Storage: open Data, click API keys, then create a key. Copy the key and the Catalog endpoint shown with it. The key value is shown only once.
Set the key and the endpoint:
export ALLOY_API_KEY="ak_..."
export ALLOY_DATA_URL="https://data.usealloy.ai"You can also pass base_url= and api_key= directly to storage.connect() and sql.connect().
Treat your Alloy API key like a password. Do not commit it to source control or print it in notebook output.
Upload and query
from alloy import storage, sql
with storage.connect() as store:
upload = store.upload_folder(
"local/run-001",
path="flights/run-001",
overwrite=False,
)
print(upload.prefix)
# uploads/sdk-uploads/flights/run-001/
with sql.connect() as db:
rows = db.fetch(
"""
SELECT key, count(*) AS entries
FROM alloy.mesh.file_meta
GROUP BY key
ORDER BY entries DESC
LIMIT 20
"""
)
for row in rows:
print(row)The exact table names depend on the MCAP contents and your Mesh catalog. Use SQL Workbench, list_mesh_tables over MCP, or hosted SQL discovery queries to inspect available tables.
List and download files
from alloy import storage
with storage.connect() as store:
listing = store.list_files(path="flights/run-001", recursive=True)
for file in listing:
print(file.key, file.size)
store.download_file(
"uploads/sdk-uploads/flights/run-001/run.mcap",
"downloaded-run.mcap",
)Upload helpers use friendly path values such as flights/run-001. List helpers accept the same SDK path for SDK uploads. Downloads use the Mesh key returned by upload or list results.
Async version
from alloy import storage, sql
async with storage.async_connect() as store:
upload = await store.upload_folder(
"local/run-001",
path="flights/run-001",
overwrite=False,
)
async with sql.async_connect() as db:
count = await db.fetchval("SELECT count(*) FROM alloy.mesh.file_meta")Async storage transfers use the same method names; async SQL uses native async HTTP and decodes Arrow off the event loop.