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

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,
    overwrite: Literal[False] = False,
) -> storage.UploadResult

Uploads one .mcap, .json, .yml, or .yaml file into a Mesh Storage path.

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

Uploads supported files below a folder, preserving relative paths. Sidecars upload before MCAPs.

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

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

client.download_file(
    key: str,
    destination,
) -> 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)`	`list[dict[str, Any]]`	small row results
`fetchrow(sql, params=None)`	`dict[str, Any] \| None`	one row
`fetchval(sql, params=None)`	first value	scalar queries
`fetch_rows(sql, params=None, max_rows=None)`	`RowSet`	rows plus schema/cap metadata
`query(sql, params=None)`	`QueryResult`	Arrow-backed result object
`query_arrow(sql, params=None)`	`pyarrow.Table`	Arrow handoff
`query_pandas(sql, params=None)`	pandas DataFrame	notebook analysis
`query_polars(sql, params=None)`	Polars DataFrame	Polars analysis
`query_df(sql, params=None)`	pandas DataFrame	alias for pandas
`stream(sql, params=None)`	`QueryStream`	Arrow batch streaming
`query_batches(sql, params=None)`	`QueryStream`	alias for stream

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`, `named_rows()`, `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`	Storage Gateway returned a non-2xx response
`AlloyStorageResponseError`	Gateway or storage response had an unexpected shape
`AlloyStorageTransferError`	Local planning or transfer failed
`AlloyStorageConflictError`	`overwrite=False` found an existing target key
`AlloyStorageDependencyError`	Required transfer dependency is unavailable

SQL errors:

Error	Meaning
`AlloySqlError`	Base hosted SQL SDK error
`AlloySqlHttpError`	Hosted SQL returned a non-2xx response
`AlloySqlResponseError`	Hosted SQL response had an unexpected shape
`AlloySqlDecodeError`	Arrow IPC decoding failed
`AlloySqlDependencyError`	Optional DataFrame/DuckDB dependency is unavailable

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