Query Mesh Data

Use alloy.sql to query Mesh data after files reach Ready. The hosted SQL endpoint returns Arrow IPC; the SDK adapts it into rows, RowSets, Arrow tables, DataFrames, DuckDB relations, or streams.

from alloy import sql

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
        """
    )

Connect

export ALLOY_API_KEY="ak_..."
export ALLOY_DATA_URL="https://data.usealloy.ai"

from alloy import sql

with sql.connect() as db:
    count = db.fetchval("SELECT count(*) FROM alloy.mesh.file_meta")

Explicit values are supported:

from alloy import sql

with sql.connect(
    base_url="https://data.usealloy.ai",
    api_key="ak_...",
) as db:
    rows = db.fetch("SELECT * FROM alloy.mesh.file_meta LIMIT 10")

Small row results

Use fetch, fetchrow, and fetchval for bounded results that fit naturally in Python.

from alloy import sql

with sql.connect() as db:
    topics = db.fetch(
        """
        SELECT topic, count(*) AS messages
        FROM alloy.fleet.diagnostics
        GROUP BY topic
        ORDER BY messages DESC
        LIMIT 100
        """
    )

    latest = db.fetchrow(
        """
        SELECT file_id, updated_at
        FROM alloy.mesh.file_meta
        ORDER BY updated_at DESC
        LIMIT 1
        """
    )

    file_count = db.fetchval("SELECT count(DISTINCT file_id) FROM alloy.mesh.file_meta")

RowSet results

Use fetch_rows when you need columns, row counts, CSV output, or a local materialization cap.

from alloy import sql

with sql.connect() as db:
    rowset = db.fetch_rows(
        """
        SELECT file_id, key, value, value_num
        FROM alloy.mesh.file_meta
        ORDER BY updated_at DESC
        LIMIT 1000
        """,
        max_rows=1000,
    )

print(rowset.columns)
print(rowset.row_count)
print(rowset.to_csv())

max_rows is a local SDK cap. It prevents unbounded Python row materialization, but it does not rewrite your SQL or reduce hosted SQL work. Use SQL LIMIT for query performance.

Typed params

Use typed params instead of formatting values into SQL strings.

from alloy import sql

p = sql.param

with sql.connect() as db:
    rows = db.fetch(
        """
        SELECT file_id, key, value
        FROM alloy.mesh.file_meta
        WHERE key = $key
          AND value = $mission_id
        LIMIT 100
        """,
        params={
            "key": p.utf8("alloy.mission_id"),
            "mission_id": p.utf8("2U8NUGFHGifdCt7tdcnwTd"),
        },
    )

Parameter names do not include $ in the params mapping. Params are values only; they cannot stand in for table names, column names, SQL clauses, or fragments.

Supported param constructors:

Constructor	Use for
`sql.param.utf8(value)`	strings
`sql.param.bool(value)`	booleans
`sql.param.int64(value)`	signed 64-bit integers
`sql.param.float64(value)`	floating point values
`sql.param.date32(value)`	dates
`sql.param.timestamp_us(value)`	timestamps
`sql.param.binary(value)`	bytes

Arrow and DataFrames

Use query when you want an Arrow-backed result object with multiple conversion options.

from alloy import sql

with sql.connect() as db:
    result = db.query("SELECT * FROM alloy.mesh.file_meta LIMIT 1000")

print(result.column_names)
print(result.column_types)
print(result.row_count)

arrow_table = result.to_arrow()
pandas_df = result.to_pandas()
polars_df = result.to_polars()
duckdb_conn = result.to_duckdb(table_name="mesh_file_meta")

Direct helpers are shortcuts:

with sql.connect() as db:
    arrow_table = db.query_arrow("SELECT * FROM alloy.mesh.file_meta LIMIT 100")
    pandas_df = db.query_pandas("SELECT * FROM alloy.mesh.file_meta LIMIT 100")
    polars_df = db.query_polars("SELECT * FROM alloy.mesh.file_meta LIMIT 100")
    df = db.query_df("SELECT * FROM alloy.mesh.file_meta LIMIT 100")

Pandas, Polars, and DuckDB helpers require their corresponding SDK extras, such as alloy-sdk[pandas], alloy-sdk[polars], or alloy-sdk[duckdb].

Streaming batches

Use streams for large query results that should be processed batch by batch.

from alloy import sql

with sql.connect() as db:
    with db.stream("SELECT * FROM alloy.mesh.file_meta") as stream:
        with stream.reader() as reader:
            for batch in reader:
                print(batch.num_rows)

Async usage

from alloy import sql

with sql.connect() as db:
    row = db.fetchrow("SELECT count(*) AS n FROM alloy.mesh.file_meta")

from alloy import sql

async with sql.async_connect() as db:
    row = await db.fetchrow("SELECT count(*) AS n FROM alloy.mesh.file_meta")

Async clients mirror the sync method names. Expensive result materialization is async so service code does not accidentally block the event loop.

Hosted SQL is read-only in v1. Use it to query Mesh data, not to insert, update, delete, or create tables.