Cell Values

KalamCellValue is the typed wrapper around each cell in query and subscription results.

Instead of parsing raw serde_json::Value at every call site, use the accessor methods on KalamCellValue.

Quick example

RUST

1use kalam_client::KalamCellValue;2 3let response = client4    .execute_query("SELECT id, name, score FROM users", None, None, None)5    .await?;6 7for row in response.rows_as_maps() {8    let id = row.get("id").and_then(|v| v.as_text());9    let name = row.get("name").and_then(|v| v.as_text());10    let score = row.get("score").and_then(|v| v.as_double());11    println!("{id:?} {name:?} {score:?}");12}

Row shapes

Context	Type
`QueryResponse::rows_as_maps()`	`Vec<HashMap<String, KalamCellValue>>`
`QueryResponse::rows()`	`Vec<Vec<KalamCellValue>>` (positional)
`LiveRowsEvent::Rows`	`Vec<HashMap<String, KalamCellValue>>`
Low-level `ChangeEvent` rows	Named or positional depending on event variant

Prefer named maps (rows_as_maps, live row maps) for application code.

Creating values

RUST

1let cell = KalamCellValue::text("hello");2let cell = KalamCellValue::int(42);3let cell = KalamCellValue::boolean(true);4let cell = KalamCellValue::null();5let cell = KalamCellValue::from(serde_json::json!({"key": "value"}));

Type guards

KalamCellValue derefs to serde_json::Value, so you can use standard JSON checks:

RUST

1cell.inner().is_null();2cell.inner().is_string();3cell.inner().is_number();

Prefer the typed accessors below for SQL column semantics.

Typed accessors

Method	SQL types
`as_text()`	`Text`
`as_small_int()`	`SmallInt`
`as_int()`	`Int`
`as_big_int()`	`BigInt` (handles string-encoded JSON for precision)
`as_float()` / `as_double()`	`Float` / `Double`
`as_decimal()`	`Decimal`
`as_boolean()`	`Boolean`
`as_timestamp()`	`Timestamp` (epoch value)

BigInt and large integers are often serialized as JSON strings — accessors handle both numeric and string forms.

Raw access

RUST

1let raw: &serde_json::Value = cell.inner();2let owned: serde_json::Value = cell.clone().into_inner();

Live subscription rows

RUST

1if let LiveRowsEvent::Rows { rows, .. } = event? {2    for row in rows {3        let body = row.get("body").and_then(KalamCellValue::as_text);4        println!("{body:?}");5    }6}

FILE columns

FILE values deserialize to structured JSON. Use file-specific helpers instead of parsing raw JSON by hand.

`.as_file() -> Option<FileRef>`

Parse a FILE column into table-agnostic metadata:

RUST

1if let Some(file_ref) = cell.as_file() {2    println!("{} ({})", file_ref.name, file_ref.format_size());3    assert!(file_ref.is_image());4}

FileRef alone does not include namespace/table — you need those to build download URLs.

`.as_bound_file(&TableId) -> Option<BoundFileRef>`

Parse and attach table context in one step. Reuse one TableId when parsing many rows from the same table:

RUST

1use kalam_client::TableId;2 3let table_id = TableId::from_strings("docs", "files");4let bound = cell.as_bound_file(&table_id).expect("FILE column");5 6println!("{}", bound.relative_url());7let download = client.download_bound_file(&bound, None).await?;

See FILE Columns & Uploads for uploads, BoundFileRef, and download APIs.

Accessor summary

Method	Returns	Use for
`as_text()`	`Option<&str>`	Text columns
`as_int()` / `as_big_int()`	numeric options	Integer columns
`as_file()`	`Option<FileRef>`	FILE metadata without table context
`as_bound_file(&TableId)`	`Option<BoundFileRef>`	FILE metadata + download context

Cell Values

Quick example

Row shapes

Creating values

Type guards

Typed accessors

Raw access

Live subscription rows

FILE columns

.as_file() -> Option<FileRef>

.as_bound_file(&TableId) -> Option<BoundFileRef>

Accessor summary

Next

`.as_file() -> Option<FileRef>`

`.as_bound_file(&TableId) -> Option<BoundFileRef>`