Projections and Aggregates for Efficient Data Access

Most queries return full typed objects, and that is the right choice whenever your app needs to display, edit, or write those objects back. Projections are different: instead of hydrating complete records, they read only the fields you ask for. Aggregates go one step further and calculate a single summary value — a count, minimum, maximum, sum, or average — without reading any individual records into application code at all. Use projections to keep lightweight lists and autocomplete fast; use aggregates for dashboard summaries and numeric totals.

Single-Property Projections

Generated property helpers project one persisted field from a query result. Call the helper after your query conditions and execute with findAll() or findFirst().

// Returns List<String>
final titles = await db.todos
    .all()
    .titleProperty()
    .findAll();

for (final title in titles) {
  print(title);
}

Use findFirst() when only the first projected value is needed:

final firstTitle = await db.todos
    .all()
    .titleProperty()
    .findFirst();

Combine with normal query conditions, sorting, and pagination just as you would with a full-object query:

final openTitles = await db.todos
    .filter()
    .completedEqualTo(false)
    .sortByCreatedAt(order: CindelSortOrder.descending)
    .titleProperty()
    .findAll();

Dynamic Property Projection

When the field name is only known at runtime, use the lower-level property<T> API:

final titles = await db.todos
    .all()
    .property<String>('title')
    .findAll();

Prefer generated property helpers whenever the field is known at compile time. Use property<T>('fieldName') only for dynamic code that already works with persisted field names.

Multi-Property Projections

Use properties([...]) to project several persisted fields at once. The result is a List<CindelDocument>, where each entry is a Map<String, Object?> keyed by the persisted field names you requested.

// Returns List<CindelDocument>  (typedef CindelDocument = Map<String, Object?>)
final rows = await db.todos
    .all()
    .properties(['dbId', 'title'])
    .findAll();

for (final row in rows) {
  final id    = row['dbId']  as int;
  final title = row['title'] as String;

  print('$id: $title');
}

Multi-property projections are a good fit for table views, autocomplete lists, export previews, and summary screens that only need a handful of fields per record.

Pass persisted field names to properties([...]). If a model field is annotated with @Name, its persisted name may differ from the Dart field name. Generated single-property helpers handle this automatically when the field is known at compile time.

Aggregates

Aggregate helpers are available on any property query. Chain them in place of findAll() or findFirst() to receive a single computed value.

Method	Returns	Use for
`count()`	`int`	Number of non-null projected values
`min()`	`T?`	Smallest comparable value (e.g. earliest date)
`max()`	`T?`	Largest comparable value (e.g. latest date)
`sum()`	`num`	Numeric total
`average()`	`double?`	Numeric mean

`count()`

final datedCount = await db.todos
    .all()
    .createdAtProperty()
    .count();

count() counts non-null projected values. Use query-level count() (without a property) when you want to count the matching objects themselves:

final openCount = await db.todos
    .filter()
    .completedEqualTo(false)
    .count();

`min()` and `max()`

min() and max() require comparable values (dates, numbers, strings):

final oldest = await db.todos
    .all()
    .createdAtProperty()
    .min();

final newest = await db.todos
    .all()
    .createdAtProperty()
    .max();

`sum()` and `average()`

sum() and average() require numeric values:

final revenue = await db.orders
    .all()
    .totalCentsProperty()
    .sum();

final averageRevenue = await db.orders
    .all()
    .totalCentsProperty()
    .average();

Combining Aggregates with Filters

All aggregates compose naturally with filters. Apply conditions before the property projection:

final openEstimate = await db.todos
    .filter()
    .completedEqualTo(false)
    .estimateMinutesProperty()
    .sum();

final completedRevenue = await db.orders
    .filter()
    .paidEqualTo(true)
    .totalCentsProperty()
    .sum();

Combine projections and aggregates with where() filters for best performance. Starting from an indexed lookup narrows the candidate set before the projection or aggregate runs.

Common Use Cases

final rows = await db.todos
    .all()
    .sortByTitle()
    .properties(['dbId', 'title'])
    .findAll();

for (final row in rows) {
  final id    = row['dbId']  as int;
  final title = row['title'] as String;
  print('$id: $title');
}

final titles = await db.todos
    .filter()
    .titleContains(search)
    .titleProperty()
    .findAll();

final openTodos = await db.todos
    .filter()
    .completedEqualTo(false)
    .count();

final totalCents = await db.orders
    .filter()
    .paidEqualTo(true)
    .totalCentsProperty()
    .sum();

final oldest = await db.todos
    .all()
    .createdAtProperty()
    .min();

final newest = await db.todos
    .all()
    .createdAtProperty()
    .max();

Choosing the Right Query Shape

Use this decision guide to pick the right approach for each screen or operation:

Need	Approach
Display, edit, or write objects back	Full object query — `findAll()` / `findFirst()`
List or table needing only a few fields	Multi-property projection — `properties([...])`
Autocomplete or label list needing one field	Single-property projection — `titleProperty().findAll()`
Count, total, min, max, or average	Aggregate — `count()`, `sum()`, `min()`, `max()`, `average()`

// Full objects — display and edit
final todos = await db.todos.all().findAll();

// Single-property projection — labels only
final titles = await db.todos.all().titleProperty().findAll();

// Aggregate — summary value only
final count = await db.todos.filter().completedEqualTo(false).count();

CindelDocument (Map<String, Object?>) is the map-shaped type returned by multi-property projections. Most application code should prefer typed objects and generated helpers unless you are intentionally working with a partial projection.

Get Started

Data Modeling

Querying Data

Core Features

Platforms

Reference

Projections and Aggregates for Efficient Data Access

Single-Property Projections

Dynamic Property Projection

Multi-Property Projections

Aggregates

`count()`

`min()` and `max()`

`sum()` and `average()`

Combining Aggregates with Filters

Common Use Cases

Choosing the Right Query Shape

​Single-Property Projections

​Dynamic Property Projection

​Multi-Property Projections

​Aggregates

​count()

​min() and max()

​sum() and average()

​Combining Aggregates with Filters

​Common Use Cases

​Choosing the Right Query Shape

Single-Property Projections

Dynamic Property Projection

Multi-Property Projections

Aggregates

`count()`

`min()` and `max()`

`sum()` and `average()`

Combining Aggregates with Filters

Common Use Cases

Choosing the Right Query Shape