Cell Values

KalamCellValue is the typed wrapper around each individual cell value returned in a Dart SDK query result or subscription event.

Instead of accessing raw dynamic values from positional rows, you use typed accessor methods to extract values safely.

Quick Example

1import 'package:kalam_link/kalam_link.dart';2 3final response = await client.query('SELECT id, name, score, avatar FROM users');4 5// Typed row maps: Map<String, KalamCellValue>6for (final row in response.rows) {7  final id     = row['id']?.asString();      // String?8  final name   = row['name']?.asString();    // String?9  final score  = row['score']?.asDouble();   // double?10  final born   = row['born_at']?.asDate();   // DateTime?11  final url    = row['avatar']?.asFileUrl(12    'http://localhost:18080', 'default', 'users',13  );                                          // String?14  print('$id $name $score $url');15}

Creating a KalamCellValue

KalamCellValue.from(raw)

Wrap any raw dynamic value. Pass null for SQL NULL.

1final cell = KalamCellValue.from(someRawValue);

Accessing Typed Rows

QueryResult.rows

Returns List<Map<String, KalamCellValue>> — each row as a map with typed cell values.

1for (final row in result.rows) {2  print(row['email']?.asString());3}

Convenience on QueryResponse

1final response = await client.query('SELECT * FROM orders');2final rows = response.rows; // List<Map<String, KalamCellValue>>

Type Guards

Typed Accessors

.asString(): String?

Returns the value as a String, or null for SQL NULL.
Handles {"Utf8": "..."} Rust-side string envelopes automatically.

1final name = row['name']?.asString(); // "Alice"

.asInt(): int?

Returns the value as an int, or null.
Truncates doubles. Parses string-encoded integers.

1final count = row['item_count']?.asInt(); // 7

.asDouble(): double?

Returns the value as a double, or null.
Parses string-encoded floats.

1final price = row['price']?.asDouble(); // 19.99

.asBool(): bool?

Returns the value as a bool, or null.
Handles string-encoded booleans: "true", "false", "1", "0".

1final active = row['is_active']?.asBool(); // true

.asDate(): DateTime?

Returns the value as a DateTime, or null for SQL NULL / unparseable values.

Handles:

• Unix milliseconds (int)
• ISO 8601 strings ("2024-01-01T00:00:00Z")
• Numeric timestamp strings ("1704067200000")

1final created = row['created_at']?.asDate();2print(created?.toLocal());

.asObject(): Map<String, dynamic>?

Returns the value as a Map<String, dynamic>, or null.

.asArray(): List<dynamic>?

Returns the value as a List<dynamic>, or null.

FILE Column Support

.asFile(): KalamFileRef?

Parse a FILE column value and return a KalamFileRef, or null.

1final ref = row['attachment']?.asFile();2if (ref != null) {3  print('${ref.name} (${ref.formatSize()})');4  print(ref.isImage()); // true for image/* MIME types5}

See the FILE Columns section for the full KalamFileRef API.

.asFileUrl(baseUrl, namespace, table): String?

Convenience method — parse a FILE column and return the download URL.

1final url = row['avatar']?.asFileUrl(2  'http://localhost:18080',3  'default',4  'users',5);6// e.g. "http://localhost:18080/v1/files/default/users/f0001/12345-photo.png"

The generated URL uses KalamDB’s stored filename path and should be fetched with the caller’s bearer token.

Serialisation

.asJson(): dynamic

Returns the underlying raw JSON value. This is the preferred JSON accessor.

.toJson(): dynamic

Compatibility alias of .asJson().

Returns the underlying raw dynamic value. Use this when you need to pass the value to code that expects plain JSON data.

.toString(): String

Human-readable display:

• SQL NULL → "NULL"
• String → value as-is
• everything else → _raw.toString()

Using with Live Events

Live event streams (InsertEvent, UpdateEvent, DeleteEvent, InitialDataBatch) expose rows as typed maps:

1client.liveEvents('SELECT * FROM orders').listen((event) {2  switch (event) {3    case InsertEvent():4      final name = event.row['customer']?.asString();5      final total = event.row['total']?.asDouble();6      print('New order: $name \$$total');7 8    case UpdateEvent():9      final newName = event.row['customer']?.asString();10      final oldName = event.oldRow?['customer']?.asString();11      print('Order updated: $oldName → $newName');12 13    case DeleteEvent():14      print('Deleted: ${event.row['id']?.asInt()}');15 16    case InitialDataBatch():17      for (final row in event.rows) {18        print(row['customer']?.asString());19      }20 21    default:22      break;23  }24});

Available typed accessors on ChangeEvent subclasses

Full API Reference