Insert & Query

Add records to collections and query them with filters, ordering, and pagination.

Insert a record

Pass any JSON-serialisable map. The returned record includes the auto-generated id, created_at, and created_by.

lib/database.dart

Dart

final record = await Koolbase.db.collection('posts').insert({
  'title': 'My first post',
  'body': 'Hello from Koolbase',
  'published': true,
  'tags': ['flutter', 'mobile'],
});

print(record.id);         // UUID
print(record.createdAt);  // DateTime
print(record.data);       // the JSON you inserted

Insert or update in one call

Need to insert a record only when it doesn't already exist, and update it otherwise? Use upsert, covered in Update & Delete.

You may supply your own id inside data: a valid UUID is kept as the record's $id, so the id you chose is the id you get back — this is how the SDKs give offline-created records an identity that survives sync. Anything that is not a UUID is silently ignored and the server generates one, so if the id you sent matters, send a UUID.

Get all records

Fetch all records in a collection. Returns up to 20 records by default.

lib/database.dart

Dart

final result = await Koolbase.db.collection('posts').get();

for (final record in result.records) {
  print(record.data['title']);
}
print(result.total); // total count in collection

Query with filters

Use .where() to filter records by field values. Multiple filters are combined with AND.

lib/database.dart

Dart

// Filter by a single field
final published = await Koolbase.db
  .collection('posts')
  .where({'published': true})
  .get();

// Filter by multiple fields
final filtered = await Koolbase.db
  .collection('posts')
  .where({
    'published': true,
    'category': 'flutter',
  })
  .get();

Limit and offset

lib/database.dart

Dart

// Get first 10 records
final page1 = await Koolbase.db
  .collection('posts')
  .limit(10)
  .get();

// Get next 10 records
final page2 = await Koolbase.db
  .collection('posts')
  .limit(10)
  .offset(10)
  .get();

Order results

lib/database.dart

Dart

// Order by created_at descending (newest first)
final recent = await Koolbase.db
  .collection('posts')
  .orderBy('created_at', descending: true)
  .limit(20)
  .get();

Get a single record

lib/database.dart

Dart

final record = await Koolbase.db
  .doc('record-uuid-here')
  .get();

print(record.data['title']);

Access rules apply

All query and fetch operations are subject to the collection's read rule. If the rule is authenticated, the user must be logged in. If owner, only records created by the current user are returned.