A Practical Guide to Using Isar Database in Your Flutter App

Struggling with local data in Flutter? This guide explores Isar, a fast NoSQL database. Learn to implement CRUD operations, complex queries, full-text search, and multi-entry indexes with practical code examples for high-performance, reactive apps.

Getting stuck managing local data in your Flutter app? You’re not alone. Many Flutter developers look for a fast, reactive, developer-friendly database that supports complex queries, full text search, and JSON without boilerplate.

This article focuses on Isar, the coolest Flutter database built for high performance and compile-time safety. We'll explore features like multi-entry indexes, Isar collections, basic CRUD operations, and query modifiers, and then execute queries using them.

What is Isar Database?

Isar is a fast, NoSQL database for Flutter with native Dart APIs . It runs directly inside your app with no external dependencies. The database is optimized for mobile devices and supports both Android and iOS.

• Stores objects with a schema defined using Dart classes.

• Supports reactive data queries with minimal boilerplate.

• Works offline, with a free forever license.

Mermaid Diagram: Isar Architecture

Explanation:

Your Flutter app opens a database instance and interacts with Isar collections. Queries are handled via a builder pattern, and query modifiers return reactive results.

Setting Up Isar in Your Flutter Project

Before working with the Isar app, you must install and initialize it properly. You define schemas, enable query generation, and use build\_runner to generate code.

Run the following command to generate schemas:

Copy
1
flutter pub run build_runner build

This will scan your models and output the final .g.dart files used in the database instance.

“Isar brings speed and simplicity to data management. Now, it's time to put that power into your creation.”

Build Flutter App Now

Defining Collections and Schemas

Collections in Isar are defined using Dart classes . You annotate each class with @Collection() and mark the ID and indexed fields.

Code snippet:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
@Collection()
class User {
  Id id = Isar.autoIncrement;

  String name;

  @Index(caseSensitive: false)
  String email;

  int age;

  User({required this.name, required this.email, required this.age});
}

Explanation:

This defines a User class, creating an ISAR collection. The email field is indexed and case-insensitive, and the ID is automatically generated.

Creating and Opening Isar Instances

To access the ISAR database, open an instance pointing to your final dir path.

Copy
1
2
3
4
5
final dir = await getApplicationDocumentsDirectory();
final isar = await Isar.open(
  [UserSchema],
  directory: dir.path,
);

Explanation:

You must await the Isar because the operation is asynchronous. UserSchema is generated during codegen. The directory points to where your database file is stored.

Basic CRUD Operations

Performing basic CRUD operations is simple and type-safe.

Copy
1
2
3
await isar.writeTxn(() async {
  await isar.users.put(User(name: 'John', email: 'john@email.com', age: 30));
});

Explanation:

Wrap your changes inside writeTxn. The put function saves or updates the object. It’s fast, reactive, and works offline.

To delete, use:

Copy
1
2
3
await isar.writeTxn(() async {
  await isar.users.delete(1);
});

Performing Complex Queries

Isar supports a powerful query language with query modifiers. You can filter by values, chain conditions, or sort results.

Copy
1
2
3
4
5
6
final results = await isar.users
  .filter()
  .ageGreaterThan(25)
  .and()
  .emailContains('example', caseSensitive: false)
  .findAll();

Explanation:

This query fetches users over 25 with emails that contain “example.” The filters are compile-time checked and eliminate typos.

JSON Support and Editing Properties

Isar has JSON support, allowing you to import/export objects.

Copy
1
2
final userJson = user.toJson();
final userFromJson = User.fromJson(userJson);

To edit properties, load the object, change values, and update inside a transaction.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
await isar.writeTxn(() async {
  final user = await isar.users.get(1);
  if (user != null) {
    user.name = "Updated Name";
    await isar.users.put(user);
  }
});
```​

## Full Text Search in Isar

Use `@Index(type: IndexType.value)` to support full text search.

```dart
@Index(type: IndexType.value, caseSensitive: false)
late String bio;

Search by:

Copy
1
2
3
4
final matches = await isar.users
  .filter()
  .bioWordsElementEqualTo('flutter')
  .findAll();

Explanation:

Indexes split text into words. You can perform token-based full-text queries efficiently.

Multi-Entry Indexes

Isar lets you index multiple values in a list field.

Copy
1
2
@Index(type: IndexType.hashElements)
late List<String> tags;

Now you can query entries containing specific tags:

Copy
1
2
3
4
final tagged = await isar.users
  .filter()
  .tagsElementEqualTo('developer')
  .findAll();

Explanation:

With hash elements, you create multi-entry indexes. You can find objects based on individual list elements.

Debug Mode and Inspector

Enable inspector by running your app in debug mode with this flag:

Copy
1
flutter run --dart-define=ISAR_INSPECTOR=true

Visit the inspector link shown in your debug console. It lets you explore collections, data, indexes, and even perform complex queries visually.

Table: Key Features of Isar

Explore the standout features of Isar, a high-performance NoSQL database for Flutter.

Final Thoughts

If you're building a Flutter app and need a fast, reactive database that integrates with Dart deeply, Isar is a smart choice. With features like compile-time safety, multi-entry indexes, and JSON support, managing your data becomes smooth and predictable. From basic CRUD operations to complex queries, Isar does it with clean syntax and zero boilerplate.