API Reference

Public alloy.storage and alloy.sql methods, result objects, environment variables, and errors

This page is a compact reference for the Python SDK surface used with Mesh Storage.

Install

pip install alloy-sdk

The SDK needs Python 3.12 (>=3.12,<3.13).

Environment variables

Variable	Used by	Description
`ALLOY_API_KEY`	`alloy.storage`, `alloy.sql`	Alloy API key for your org
`ALLOY_DATA_URL`	`alloy.storage`, `alloy.sql`	Alloy data API URL, for example `https://data.usealloy.ai`

Explicit base_url= and api_key= values override environment defaults.

alloy.storage

Import:

from alloy import storage

Connect

storage.connect(
    *,
    base_url: str | None = None,
    api_key: str | None = None,
    headers=None,
    timeout: float = 120.0,
)

Returns a sync storage.Client.

storage.async_connect(
    *,
    base_url: str | None = None,
    api_key: str | None = None,
    headers=None,
    timeout: float = 120.0,
)

Returns an async storage.AsyncClient.

Both clients are context managers and close SDK-owned HTTP sessions.

Client methods

client.upload_file(
    local_path,
    *,
    path: str | None = None,
    ttl_seconds: int | None = None,
    overwrite: Literal[False] = False,
) -> storage.UploadResult

Uploads one .mcap, .json, .yml, or .yaml file into a Mesh Storage path. overwrite=True raises NotImplementedError.

client.upload_folder(
    local_folder,
    *,
    path: str | None = None,
    ttl_seconds: int | None = None,
    overwrite: Literal[False] = False,
) -> storage.UploadResult

Uploads every file below a folder, preserving relative paths. Sidecars upload before MCAPs. Every file must be .mcap, .json, .yml, or .yaml. One unsupported file stops the whole upload with AlloyStorageTransferError before any file uploads.

client.list_files(
    prefix: str | None = None,
    *,
    path: str | None = None,
    recursive: bool = False,
    max_keys: int = 100,
    continuation_token: str | None = None,
    ttl_seconds: int | None = None,
) -> storage.StorageListResult

Lists objects below either an SDK upload path or a raw Mesh prefix.

client.download_file(
    key: str,
    destination,
    *,
    ttl_seconds: int | None = None,
) -> None

Downloads one Mesh object by exact key.

storage.AsyncClient exposes the same methods with await.

One-shot helpers

storage.upload_file(...)
storage.upload_folder(...)
storage.list_files(...)
storage.download_file(...)
await storage.async_upload_file(...)
await storage.async_upload_folder(...)
await storage.async_list_files(...)
await storage.async_download_file(...)

One-shot helpers open a client, run one operation, and close the client.

Storage result objects

Object	Fields
`StorageFile`	`key`, `size`, `last_modified`, `etag`
`StorageListResult`	`files`, `directories`, `next_token`, `prefix`
`PlannedUpload`	`local_path`, `relative_path`, `key`, `size`
`UploadResult`	`files`, `total_bytes`, `path`, `prefix`

alloy.sql

Import:

from alloy import sql

Connect

sql.connect(
    *,
    base_url: str | None = None,
    api_key: str | None = None,
    headers=None,
    timeout: float = 120.0,
)

sql.async_connect(
    *,
    base_url: str | None = None,
    api_key: str | None = None,
    headers=None,
    timeout: float = 120.0,
)

Query methods

Method	Returns	Use for
`fetch(sql, *, params=None, timeout=None, max_rows=None)`	`list[dict[str, Any]]`	small row results
`fetchrow(sql, *, params=None, timeout=None)`	`dict[str, Any] \| None`	one row
`fetchval(sql, *, params=None, timeout=None)`	first value	scalar queries
`fetch_rows(sql, *, params=None, timeout=None, max_rows=None)`	`RowSet`	rows plus schema/cap metadata
`query(sql, *, params=None, timeout=None)`	`QueryResult`	Arrow-backed result object
`query_arrow(sql, *, params=None, timeout=None)`	`pyarrow.Table`	Arrow handoff
`query_pandas(sql, *, params=None, timeout=None)`	pandas DataFrame	notebook analysis
`query_polars(sql, *, params=None, timeout=None)`	Polars DataFrame	Polars analysis
`query_df(sql, *, params=None, timeout=None)`	pandas DataFrame	alias for pandas
`stream(sql, *, params=None, timeout=None)`	`QueryStream`	Arrow batch streaming
`query_batches(sql, *, params=None, timeout=None)`	`QueryStream`	alias for stream

params, timeout, and max_rows are keyword-only. timeout is in seconds and defaults to the client timeout.

Async clients expose the same method names. Await eager methods; use async with for streams.

SQL result objects

Object	Useful members
`RowSet`	`columns`, `rows`, `row_count`, `truncated`, `named_rows()`, `to_csv()`
`AsyncRowSet`	`columns`, `rows`, `row_count`, `truncated`, `await named_rows()`, `await to_csv()`
`QueryResult`	`column_names`, `column_types`, `row_count`, `to_arrow()`, `to_pandas()`, `to_polars()`, `to_duckdb()`
`AsyncQueryResult`	async equivalents for expensive conversions
`QueryStream`	context-managed Arrow batch stream
`AsyncQueryStream`	async context-managed Arrow batch stream

Errors

Storage errors:

Error	Meaning
`AlloyStorageError`	Base storage SDK error
`AlloyStorageHttpError`	The storage API returned a non-2xx response, for example 402 `storage_limit_reached`. Has `status_code` and `body`
`AlloyStorageResponseError`	The storage API returned an unexpected response shape
`AlloyStorageTransferError`	Local planning failed (missing source, unsupported file type, key over 1024 bytes) or the pre-upload conflict check failed
`AlloyStorageConflictError`	`overwrite=False` found an existing target key
`AlloyStorageDependencyError`	Required transfer dependency is unavailable

Network errors and errors during the file transfer itself (upload, list, or download) come straight from the underlying HTTP and storage client libraries. The SDK does not wrap them in AlloyStorageError.

SQL errors:

Error	Meaning
`AlloySqlError`	Base hosted SQL SDK error
`AlloySqlHttpError`	Hosted SQL returned a non-2xx response. Has `status_code` and `body`
`AlloySqlResponseError`	Hosted SQL response had an unexpected shape
`AlloySqlTransportError`	The HTTP request failed, or the Arrow stream ended early. Subclass of `AlloySqlResponseError`
`AlloySqlDecodeError`	Arrow IPC decoding failed
`AlloySqlDependencyError`	Polars or DuckDB is not installed. A missing pandas raises a plain `ImportError`

Version notes

Storage helpers, async transfers, and hosted SQL are available in the current alloy-sdk package. Upgrade before using this reference:

pip install --upgrade alloy-sdk

API Reference

On this page