Isar Database

https://isar.dev
Admin
Isar is a super-fast, cross-platform NoSQL database for Flutter that supports hundreds of thousands...
Tokens:14,493
Snippets:204
Trust Score:7.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Implement Migration Logic

Source: https://isar.dev/recipes/data_migration.html

Example of checking the current database version and executing migration functions using shared preferences.

```dart
import 'package:isar/isar.dart';
import 'package:shared_preferences/shared_preferences.dart';

void main() async {
  final dir = await getApplicationDocumentsDirectory();

  final isar = await Isar.openAsync(
    schemas: [UserSchema],
    directory: dir.path,
  );

  await performMigrationIfNeeded(isar);

  runApp(MyApp(isar: isar));
}

Future<void> performMigrationIfNeeded(Isar isar) async {
  final prefs = await SharedPreferences.getInstance();
  final currentVersion = prefs.getInt('version') ?? 2;
  switch(currentVersion) {
    case 1:
      await migrateV1ToV2(isar);
      break;
    case 2:
      // If the version is not set (new installation) or already 2, we do not need to migrate
      return;
    default:
      throw Exception('Unknown version: $currentVersion');
  }

  // Update version
  await prefs.setInt('version', 2);
}

Future<void> migrateV1ToV2(Isar isar) async {
  final userCount = await isar.users.count();

  // We paginate through the users to avoid loading all users into memory at once
  for (var i = 0; i < userCount; i += 50) {
    final users = await isar.users.where().offset(i).limit(50).findAll();
    await isar.writeTxn((isar) async {
      // We don't need to update anything since the birthYear getter is used
      await isar.users.putAll(users);
    });
  }
}
```

--------------------------------

### Apply Filter Conditions

Source: https://isar.dev/queries

Examples of using various filter conditions to query shoe sizes.

```dart
isar.shoes.filter()
  .sizeLessThan(40)
  .findAll() // -> [39, null]

isar.shoes.filter()
  .sizeLessThan(40, include: true)
  .findAll() // -> [39, null, 40]

isar.shoes.filter()
  .sizeBetween(39, 46, includeLower: false)
  .findAll() // -> [40, 46]
```

--------------------------------

### Define a model with a list

Source: https://isar.dev/queries

Example of a data model containing a list of strings.

```Dart
class Tweet {
  late int id;

  String? text;

  List<String> hashtags = [];
}
```

--------------------------------

### Get Object by ID (Async and Sync)

Source: https://isar.dev/crud.html

Retrieve a single object from a collection by its ID asynchronously using `get()` or synchronously using `getSync()`.

```dart
final recipe = await isar.recipes.get(123);

```

```dart
final recipe = isar.recipes.getSync(123);

```

--------------------------------

### Get Multiple Objects by IDs

Source: https://isar.dev/crud.html

Fetch multiple objects from a collection simultaneously by providing a list of their IDs using `getAll()` or `getAllSync()`.

```dart
final recipe = await isar.recipes.getAll([1, 2]);

```

--------------------------------

### Write and Read Data

Source: https://isar.dev/tutorials/quickstart.html

Perform basic CRUD operations like inserting, updating, getting, and deleting data using Isar.

```dart
final newUser = User()..name = 'Jane Doe'..age = 36;

await isar.writeTxn(() async {
  await isar.users.put(newUser); // insert & update
});

final existingUser = await isar.users.get(newUser.id); // get

await isar.writeTxn(() async {
  await isar.users.delete(existingUser.id!); // delete
});

```

--------------------------------

### Get Collection Instance

Source: https://isar.dev/crud.html

Access a specific collection (e.g., 'recipes') from the Isar instance using collection accessors or the generic `collection()` method.

```dart
final recipes = isar.recipes;

```

```dart
final recipes = isar.collection<Recipe>();

```

--------------------------------

### Define Collection with Various Number Types

Source: https://isar.dev/schema.html

Example of an Isar collection demonstrating the use of byte, short, int, float, and double types. Note that 'short' and 'float' are aliases for Dart's 'int' and 'double' respectively, offering space efficiency.

```dart
@collection
class TestCollection {
  late int id;

  late byte byteValue;

  short? shortValue;

  int? intValue;

  float? floatValue;

  double? doubleValue;
}

```

--------------------------------

### Define Collection with Embedded Objects

Source: https://isar.dev/schema.html

Example of an Isar collection featuring an embedded object ('Recepient') within an 'Email' object. Embedded objects can be nested deeply and must have a default constructor without required parameters.

```dart
@collection
class Email {
  late int id;

  String? title;

  Recepient? recipient;
}

@embedded
class Recepient {
  String? name;

  String? address;
}

```

--------------------------------

### Lazy Watch a Specific Object - Isar

Source: https://isar.dev/watchers.html

Get notified about changes to a specific object without fetching its new value. This is more efficient if you only need to know that a change occurred.

```dart
Stream<void> userChanged = isar.users.watchObjectLazy(5);
userChanged.listen(() {
  print('User 5 changed');
});

final user = User(id: 5)..name = 'David';
await isar.users.put(user);
// prints: User 5 changed

```

--------------------------------

### Open Isar Instance

Source: https://isar.dev/tutorials/quickstart.html

Open a new Isar instance, passing your collection schemas and optionally specifying a directory.

```dart
final dir = await getApplicationDocumentsDirectory();
final isar = await Isar.openAsync(
  schemas: [UserSchema],
  directory: dir.path,
);

```

--------------------------------

### Dynamic Queries with buildQuery()

Source: https://isar.dev/queries

This section covers the `buildQuery()` method for creating dynamic queries, which is generally discouraged unless absolutely necessary. It allows for custom query languages.

```APIDOC
## Dynamic Queries with buildQuery()

**Danger**: This section is most likely not relevant to you. It is discouraged to use dynamic queries unless you absolutely need to (and you rarely do).

All the examples above used the QueryBuilder and the generated static extension methods. Maybe you want to create dynamic queries or a custom query language (like the Isar Inspector). In that case, you can use the `buildQuery()` method:

### Parameters

- **whereClauses** (List<WhereClause>) - The where clauses of the query.
- **whereDistinct** (bool) - Whether where clauses should return distinct values (only useful for single where clauses).
- **whereSort** (Sort | Sort?) - The traverse order of the where clauses (only useful for single where clauses).
- **filter** (Filter?) - The filter to apply to the results.
- **sortBy** (List<SortProperty>) - A list of properties to sort by.
- **distinctBy** (List<String>) - A list of properties to distinct by.
- **offset** (int) - The offset of the results.
- **limit** (int) - The maximum number of results to return.
- **property** (String?) - If non-null, only the values of this property are returned.

### Request Example

```dart
final shoes = await isar.shoes.buildQuery(
  whereClauses: [
    WhereClause(
      indexName: 'size',
      lower: [42],
      includeLower: true,
      upper: [46],
      includeUpper: true,
    )
  ],
  filter: FilterGroup.and([
    FilterCondition(
      type: ConditionType.contains,
      property: 'model',
      value: 'nike',
      caseSensitive: false,
    ),
    FilterGroup.not(
      FilterCondition(
        type: ConditionType.contains,
        property: 'model',
        value: 'adidas',
        caseSensitive: false,
      ),
    ),
  ]),
  sortBy: [
    SortProperty(
      property: 'model',
      sort: Sort.desc,
    )
  ],
  offset: 10,
  limit: 10,
).findAll();
```

### Equivalent Static Query Example

```dart
final shoes = await isar.shoes.where()
  .sizeBetween(42, 46)
  .filter()
  .modelContains('nike', caseSensitive: false)
  .not()
  .modelContains('adidas', caseSensitive: false)
  .sortByModelDesc()
  .offset(10).limit(10)
  .findAll();
```
```

--------------------------------

### Equivalent Static Query in Isar

Source: https://isar.dev/queries

This static query is equivalent to the dynamic query built with buildQuery. It demonstrates a more concise way to achieve the same results for common query patterns.

```dart
final shoes = await isar.shoes.where()
  .sizeBetween(42, 46)
  .filter()
  .modelContains('nike', caseSensitive: false)
  .not()
  .modelContains('adidas', caseSensitive: false)
  .sortByModelDesc()
  .offset(10).limit(10)
  .findAll();

```

--------------------------------

### Build Dynamic Query with Isar

Source: https://isar.dev/queries

Use buildQuery to construct dynamic queries with complex filtering, sorting, and pagination. This is useful for custom query languages or tools like the Isar Inspector.

```dart
final shoes = await isar.shoes.buildQuery(
  whereClauses: [
    WhereClause(
      indexName: 'size',
      lower: [42],
      includeLower: true,
      upper: [46],
      includeUpper: true,
    )
  ],
  filter: FilterGroup.and([
    FilterCondition(
      type: ConditionType.contains,
      property: 'model',
      value: 'nike',
      caseSensitive: false,
    ),
    FilterGroup.not(
      FilterCondition(
        type: ConditionType.contains,
        property: 'model',
        value: 'adidas',
        caseSensitive: false,
      ),
    ),
  ]),
  sortBy: [
    SortProperty(
      property: 'model',
      sort: Sort.desc,
    )
  ],
  offset: 10,
  limit: 10,
).findAll();

```

--------------------------------

### Run Code Generator (Dart)

Source: https://isar.dev/tutorials/quickstart.html

Execute the build_runner to generate Isar schema files.

```dart
dart run build_runner build

```

--------------------------------

### Prefix Matching with Full-Text Index

Source: https://isar.dev/recipes/full_text_search.html

Enable prefix matching by using `IndexType.value` and the `.titleWordsAnyStartsWith()` query. This allows searching for words that begin with a specific prefix.

```dart
final posts = await isar.posts
  .where()
  .titleWordsAnyStartsWith('hel')
  .or()
  .titleWordsAnyStartsWith('welco')
  .or()
  .titleWordsAnyStartsWith('howd')
  .findAll();
```

--------------------------------

### Open Isar and Watch Changes in Main Isolate

Source: https://isar.dev/recipes/multi_isolate.html

Opens an Isar instance in the main isolate and sets up a lazy watcher for changes. This watcher can detect modifications made from other isolates.

```dart
void main() {
  // Open Isar in the UI isolate
  final dir = await getApplicationDocumentsDirectory();

  final isar = await Isar.openAsync(
    schemas: [MessageSchema],
    directory: dir.path,
    name: 'myInstance',
  );

  // listen to changes in the database
  isar.messages.watchLazy(() {
    print('omg the messages changed!');
  });

  // start a new isolate and create 10000 messages
  compute(createDummyMessages, 10000).then(() {
    print('isolate finished');
  });

  // after some time:
  // > omg the messages changed!
  // > isolate finished
}
```

--------------------------------

### Create Dummy Messages in a New Isolate

Source: https://isar.dev/recipes/multi_isolate.html

This function is designed to run in a separate isolate. It opens the same Isar instance by name and performs a bulk insertion of messages using a synchronous transaction, which is efficient for blocking operations within an isolate.

```dart
// function that will be executed in the new isolate
Future createDummyMessages(int count) async {
  // we don't need the path here because the instance is already open
  final dir = await getApplicationDocumentsDirectory();

  final isar = await Isar.openAsync(
    schemas: [PostSchema],
    directory: dir.path,
    name: 'myInstance',
  );

  final messages = List.generate(count, (i) => Message()..content = 'Message $i');
  // we use synchronous transactions in isolates
  isar.writeTxnSync(() {
    isar.messages.insertAllSync(messages);
  });
}
```

--------------------------------

### Add Isar Dependencies

Source: https://isar.dev/tutorials/quickstart.html

Add the necessary Isar packages to your pubspec.yaml file.

```yaml
flutter pub add isar isar_flutter_libs path_provider
flutter pub add -d isar_generator build_runner

```

--------------------------------

### Define User Collection Version 1

Source: https://isar.dev/recipes/data_migration.html

Initial schema definition for the User collection.

```dart
@collection
class User {
  late int id;

  late String name;

  late DateTime birthday;
}
```

--------------------------------

### Execute Basic Query

Source: https://isar.dev/queries

Retrieve records matching a specific condition.

```dart
final result = await isar.shoes.filter()
  .sizeEqualTo(46)
  .findAll();
```

--------------------------------

### Run Code Generator (Flutter)

Source: https://isar.dev/tutorials/quickstart.html

Execute the build_runner for Flutter projects to generate Isar schema files.

```dart
flutter pub run build_runner build

```

--------------------------------

### Implementing Suffix Matching

Source: https://isar.dev/recipes/full_text_search.html

Achieve suffix matching by indexing the reversed words of the title and searching for the reversed suffix. This requires reversing both the indexed words and the search term.

```dart
class Post {
    late int id;

    late String title;

    @Index(type: IndexType.value, caseSensitive: false)
    List<String> get revTitleWords {
        return Isar.splitWords(title).map(
          (word) => word.reversed).toList()
        );
    }
}
```

```dart
final posts = await isar.posts
  .where()
  .revTitleWordsAnyStartsWith('lcome'.reversed)
  .findAll();
```

--------------------------------

### Save IsarLink with putSync

Source: https://isar.dev/links

When using synchronous transactions, putSync automatically saves all links. It also creates the related objects if they don't exist.

```dart
final englishTeacher = Teacher()..subject = 'English';

final david = Student()
  ..name = 'David'
  ..teacher.value = englishTeacher;

isar.writeTxnSync(() {
  isar.students.putSync(david);
});
```

--------------------------------

### Basic Full-Text Index for Words

Source: https://isar.dev/recipes/full_text_search.html

Define a basic full-text index by splitting the content into words. This allows searching for individual words but has limitations with punctuation and whitespace.

```dart
class Message {
  late int id;

  late String content;

  @Index()
  List<String> get contentWords => content.split(' ');
}
```

--------------------------------

### Execute property queries

Source: https://isar.dev/queries

Retrieve only specific properties to reduce deserialization time.

```Dart
List<String> models = await isar.shoes.where()
  .modelProperty()
  .findAll();

List<int> sizes = await isar.shoes.where()
  .sizeProperty()
  .findAll();
```

--------------------------------

### Filter Students by Number of Teachers

Source: https://isar.dev/queries

Finds students with exactly zero teachers using 'teachersLengthEqualTo(0)'. This is an efficient way to check for empty links.

```dart
final result = await isar.students.filter().teachersLengthEqualTo(0).findAll();

```

--------------------------------

### Combine Where Clauses and Filters

Source: https://isar.dev/queries

Combines a where clause on 'isUnisex' with a filter on 'model' to find Nike shoes that are unisex. Where clauses are applied before filters for better performance.

```dart
final result = isar.shoes.where()
  .isUnisexEqualTo(true)
  .filter()
  .modelContains('Nike')
  .findAll();

```

--------------------------------

### Querying with multiple values

Source: https://isar.dev/queries

Compare manual OR chaining with the anyOf modifier for cleaner dynamic queries.

```Dart
final shoes1 = await isar.shoes.filter()
  .sizeEqualTo(38)
  .or()
  .sizeEqualTo(40)
  .or()
  .sizeEqualTo(42)
  .findAll();

final shoes2 = await isar.shoes.filter()
  .anyOf(
    [38, 40, 42],
    (q, int size) => q.sizeEqualTo(size)
  ).findAll();

// shoes1 == shoes2
```

--------------------------------

### Save IsarLink with Manual Link Save

Source: https://isar.dev/links

When using asynchronous transactions, manually save the link after assigning its value and putting the objects. Links are lazy and require explicit saving.

```dart
final mathTeacher = Teacher()..subject = 'Math';

final linda = Student()
  ..name = 'Linda'
  ..teacher.value = mathTeacher;

await isar.writeTxn(() async {
  await isar.students.put(linda);
  await isar.teachers.put(mathTeacher);
  await linda.teacher.save();
});
```

--------------------------------

### Query Using Composite Index

Source: https://isar.dev/queries

Efficiently finds unisex shoes of size 46 using the composite index on 'isUnisex' and 'size'. Where clauses leverage indexes for speed.

```dart
final result = isar.shoes.where()
  .isUnisexSizeEqualTo(true, 46)
  .findAll();

```

--------------------------------

### Splitting Text into Words with Isar

Source: https://isar.dev/recipes/full_text_search.html

Utilize `Isar.splitWords()` for correct word splitting according to Unicode Annex #29 standards. This handles various languages and punctuation more effectively than simple splitting.

```dart
Isar.splitWords('hello world'); // -> ['hello', 'world']
```

```dart
Isar.splitWords('The quick (“brown”) fox can’t jump 32.3 feet, right?');
// -> ['The', 'quick', 'brown', 'fox', 'can’t', 'jump', '32.3', 'feet', 'right']
```

--------------------------------

### Perform an indexed sorted query

Source: https://isar.dev/indexes

Using a where clause to leverage an existing index for efficient sorting.

```dart
final cheapestFast = await isar.products.where()
  .anyPrice()
  .limit(4)
  .findAll();
```

--------------------------------

### Define a Collection Model

Source: https://isar.dev/queries

The data model used for demonstrating query operations.

```dart
@collection
class Shoe {
  late int id;

  int? size;

  late String model;

  late bool isUnisex;
}
```

--------------------------------

### Define Multi-entry Index for Description Words

Source: https://isar.dev/indexes

Use `IndexType.value` to create a multi-entry index for a list of strings derived from a text field. `Isar.splitWords()` is used here to tokenize the description for full-text indexing.

```dart
@collection
class Product {
  late int id;

  late String description;

  @Index(type: IndexType.value, caseSensitive: false)
  List<String> get descriptionWords => Isar.splitWords(description);
}
```

--------------------------------

### Fast 64-bit FNV-1a hash function for Dart Strings

Source: https://isar.dev/recipes/string_ids.html

Implement the FNV-1a 64-bit hash algorithm optimized for Dart Strings. This function generates a stable and efficient 64-bit integer ID from a String. Avoid using Dart's built-in `string.hashCode` due to potential instability.

```dart
/// FNV-1a 64bit hash algorithm optimized for Dart Strings
int fastHash(String string) {
  var hash = 0xcbf29ce484222325;

  var i = 0;
  while (i < string.length) {
    final codeUnit = string.codeUnitAt(i++);
    hash ^= codeUnit >> 8;
    hash *= 0x100000001b3;
    hash ^= codeUnit & 0xFF;
    hash *= 0x100000001b3;
  }

  return hash;
}

```

--------------------------------

### User model with String ID and fastHash

Source: https://isar.dev/recipes/string_ids.html

Define a User model that uses a String ID and derives an efficient integer ID using the fastHash function. Ensure the String ID is non-nullable when used with fastHash.

```dart
@collection
class User {
  String? id;

  Id get isarId => fastHash(id!)

  String? name;

  int? age;
}

```

--------------------------------

### Filter Students by Empty Teacher Links

Source: https://isar.dev/queries

Finds students with no teachers using the 'teachersIsEmpty()' filter. This is an alternative to 'teachersLengthEqualTo(0)'.

```dart
final result = await isar.students.filter().teachersIsEmpty().findAll();

```

--------------------------------

### Insert or Update Multiple Objects

Source: https://isar.dev/crud.html

Efficiently insert or update multiple objects in a collection at once using `putAll()` within a write transaction.

```dart
await isar.writeTxn(() async {
  await isar.recipes.putAll([pancakes, pizza]);
})

```

--------------------------------

### Perform Replace and PutBy Operations

Source: https://isar.dev/indexes

Demonstrates replacing existing records and using generated putBy methods to update objects while reusing IDs.

```dart
final user1 = User()
  ..id = 1
  ..username = 'user1'
  ..age = 25;

await isar.users.put(user1);
print(await isar.user.where().findAll());
// > [{id: 1, username: 'user1', age: 25}]

final user2 = User()
  ..id = 2;
  ..username = 'user1'
  ..age = 30;

await isar.users.put(user2);
print(await isar.user.where().findAll());
// > [{id: 2, username: 'user1' age: 30}]
```

```dart
final user1 = User()
  ..id = 1
  ..username = 'user1'
  ..age = 25;

// user does not exist so this is the same as put()
await isar.users.putByUsername(user1);
await isar.user.where().findAll(); // -> [{id: 1, username: 'user1', age: 25}]

final user2 = User()
  ..id = 2;
  ..username = 'user1'
  ..age = 30;

await isar.users.put(user2);
await isar.user.where().findAll(); // -> [{id: 1, username: 'user1' age: 30}]
```

--------------------------------

### Define Linkable Collections in Isar

Source: https://isar.dev/queries

Defines 'Teacher' and 'Student' collections with a one-to-many link from Student to Teacher. Ensure your models are annotated with @collection.

```dart
@collection
class Teacher {
  late int id;

  late String subject;
}

@collection
class Student {
  late int id;

  late String name;

  final teachers = IsarLinks<Teacher>();
}

```

--------------------------------

### Paginate query results

Source: https://isar.dev/queries

Limit the number of results or apply an offset to paginate through large datasets.

```Dart
final firstTenShoes = await isar.shoes.where()
  .limit(10)
  .findAll();
```

```Dart
final firstTenShoes = await isar.shoes.where()
  .offset(20)
  .limit(10)
  .findAll();
```

--------------------------------

### Case-Insensitive Full-Text Index

Source: https://isar.dev/recipes/full_text_search.html

Create a case-insensitive full-text index by setting `caseSensitive: false`. This allows searching for words regardless of their casing.

```dart
class Post {
  late int id;

  late String title;

  @Index(type: IndexType.value, caseSensitive: false)
  List<String> get titleWords => title.split(' ');
}
```

--------------------------------

### Query Using Composite Indexes

Source: https://isar.dev/indexes

Utilize generated methods from composite indexes to perform efficient queries across multiple fields.

```dart
final result = await isar.where()
  .ageNameEqualTo(24, 'Carl')
  .hometownProperty()
  .findAll() // -> ['San Diego', 'London']
```

```dart
final result = await isar.where()
  .ageEqualToNameStartsWith(20, 'Da')
  .findAll() // -> [Daniel, David]
```

--------------------------------

### Define a basic Isar collection

Source: https://isar.dev/schema.html

A simple class definition annotated with @collection to represent a database table.

```dart
@collection
class User {
  late int id;

  String? firstName;

  String? lastName;
}
```

--------------------------------

### Querying for Specific Words

Source: https://isar.dev/recipes/full_text_search.html

Search for messages containing a specific word using the `contentWordsAnyEqualTo` query. This is a fast query but only matches whole words.

```dart
final posts = await isar.messages
  .where()
  .contentWordsAnyEqualTo('hello')
  .findAll();
```

--------------------------------

### Perform Write Transaction

Source: https://isar.dev/crud.html

Execute database modifications (create, update, delete) within a write transaction using `isar.writeTxn()`. Ensures atomicity.

```dart
await isar.writeTxn(() async {
  final recipe = await isar.recipes.get(123)

  recipe.isFavorite = false;
  await isar.recipes.put(recipe); // perform update operations

  await isar.recipes.delete(123); // or delete operations
});

```

--------------------------------

### Add and Save to IsarLinks

Source: https://isar.dev/links

Add related objects to an IsarLinks collection and then explicitly save the changes using the save() method within a transaction.

```dart
final biologyTeacher = Teacher()..subject = 'Biology';

final linda = isar.students.where()
  .filter()
  .nameEqualTo('Linda')
  .findFirst();

print(linda.teachers); // {Teacher('Math')}

linda.teachers.add(biologyTeacher);

await isar.writeTxn(() async {
  await linda.teachers.save();
});

print(linda.teachers); // {Teacher('Math'), Teacher('Biology')}
```

--------------------------------

### Define Composite Indexes

Source: https://isar.dev/indexes

Create an index on multiple properties to enable efficient multi-property sorting and advanced where clauses.

```dart
@collection
class Person {
  late int id;

  late String name;

  @Index(composite: [CompositeIndex('name')])
  late int age;

  late String hometown;
}
```

--------------------------------

### Perform efficient write transactions in Isar

Source: https://isar.dev/transactions

Group multiple write operations into a single transaction to minimize overhead. Avoid wrapping individual operations in separate transactions within a loop.

```dart
@collection
class Contact {
  late int id;

  String? name;
}

// GOOD
await isar.writeTxn(() async {
  for (var contact in getContacts()) {
    await isar.contacts.put(contact);
  }
});

// BAD: move loop inside transaction
for (var contact in getContacts()) {
  await isar.writeTxn(() async {
    await isar.contacts.put(contact);
  });
}
```

--------------------------------

### Define User Collection Version 2

Source: https://isar.dev/recipes/data_migration.html

Updated schema definition including a birthYear getter.

```dart
@collection
class User {
  late int id;

  late String name;

  late DateTime birthday;

  short get birthYear => birthday.year;
}
```

--------------------------------

### Configure Replace Index

Source: https://isar.dev/indexes

Set the replace property to true on a unique index to overwrite existing objects instead of throwing a constraint error.

```dart
@collection
class User {
  late int id;

  @Index(unique: true, replace: true)
  late String username;
}
```

--------------------------------

### Handle unique constraint violations

Source: https://isar.dev/indexes

Demonstrates how inserting a duplicate value into a unique index results in an error.

```dart
final user1 = User()
  ..id = 1
  ..username = 'user1'
  ..age = 25;

await isar.users.put(user1); // -> ok

final user2 = User()
  ..id = 2;
  ..username = 'user1'
  ..age = 30;

// try to insert user with same username
await isar.users.put(user2); // -> error: unique constraint violated
print(await isar.user.where().findAll());
// > [{id: 1, username: 'user1', age: 25}]
```

--------------------------------

### Sort results using where clauses

Source: https://isar.dev/queries

Queries using a single where clause are automatically sorted by the index. Use the sort parameter to change the order.

```Dart
final bigShoes = isar.shoes.where()
  .sizeGreaterThan(42) // also sorts the results by size
  .findAll(); // -> [43, 45, 48]
```

```Dart
final bigShoesDesc = await isar.shoes.where(sort: Sort.desc)
  .sizeGreaterThan(42)
  .findAll(); // -> [48, 45, 43]
```

```Dart
final shoes = await isar.shoes.where()
  .anySize()
  .findAll(); // -> [39, 40, 42, 43, 45, 48]
```

--------------------------------

### Aggregation Operations

Source: https://isar.dev/queries

Isar supports aggregating values of a property query using .min(), .max(), .sum(), and .average(). These operations are significantly faster than manual aggregation.

```APIDOC
## Aggregation Operations

Isar supports aggregating the values of a property query. The following aggregation operations are available:

- `.min()`: Finds the minimum value or `null` if none matches.
- `.max()`: Finds the maximum value or `null` if none matches.
- `.sum()`: Sums all values.
- `.average()`: Calculates the average of all values or `NaN` if none matches.

Using aggregations is vastly faster than finding all matching objects and performing the aggregation manually.
```

--------------------------------

### Perform a slow sorted query

Source: https://isar.dev/indexes

A query that sorts results in memory, which is inefficient for large datasets.

```dart
final cheapest = await isar.products.filter()
  .sortByPrice()
  .limit(4)
  .findAll();
```

--------------------------------

### Define Backlink for Reverse Relationship

Source: https://isar.dev/links

Annotate an IsarLink or IsarLinks with @Backlink(to: 'linkName') to define a backlink, allowing access to related objects in the reverse direction.

```dart
@collection
class Teacher {
  Id id;

  late String subject;

  @Backlink(to: 'teacher')
  final student = IsarLinks<Student>();
}
```

--------------------------------

### Watch a Query - Isar

Source: https://isar.dev/watchers.html

Subscribe to the results of a query. Isar attempts to notify you only when the query results change, excluding changes caused by links. Use `watchLazy()` to avoid fetching results if only notification is needed.

```dart
Query<User> usersWithA = isar.users.filter()
    .nameStartsWith('A')
    .build();

Stream<List<User>> queryChanged = usersWithA.watch(fireImmediately: true);
queryChanged.listen((users) {
  print('Users with A are: $users');
});
// prints: Users with A are: []

await isar.users.put(User()..name = 'Albert');
// prints: Users with A are: [User(name: Albert)]

await isar.users.put(User()..name = 'Monika');
// no print

await isar.users.put(User()..name = 'Antonia');
// prints: Users with A are: [User(name: Albert), User(name: Antonia)]

```

--------------------------------

### Define IsarLink for To-One Relationship

Source: https://isar.dev/links

Use IsarLink<T> to define a to-one relationship between collections. Ensure the id property of source and target collections is non-final.

```dart
class Teacher {
  late int id;

  late String subject;
}

class Student {
  late int id;

  late String name;

  final teacher = IsarLink<Teacher>();
}
```

--------------------------------

### Perform a linear search query

Source: https://isar.dev/indexes

A query on an unindexed collection that requires scanning all objects.

```dart
final expensiveProducts = await isar.products.filter()
  .priceGreaterThan(30)
  .findAll();
```

--------------------------------

### Filter Students by Linked Teacher Subjects

Source: https://isar.dev/queries

Finds all students who have a teacher with the subject 'Math' or 'English'. Link queries can be expensive; consider embedded objects for performance.

```dart
final result = await isar.students.filter()
  .teachers((q) {
    return q.subjectEqualTo('Math')
      .or()
      .subjectEqualTo('English');
  }).findAll();

```

--------------------------------

### Combine Filters with Logical Operators

Source: https://isar.dev/queries

Use logical operators to chain multiple conditions together.

```dart
final result = await isar.shoes.filter()
  .sizeEqualTo(46)
  .and() // Optional. Filters are implicitly combined with logical and.
  .isUnisexEqualTo(true)
  .findAll();
```

--------------------------------

### Query Objects

Source: https://isar.dev/crud.html

Find objects within a collection based on specific criteria using `.where()` and `.filter()`. `findAll()` executes the query.

```dart
final allRecipes = await isar.recipes.where().findAll();

final favorites = await isar.recipes.filter()
  .isFavoriteEqualTo(true)
  .findAll();

```

--------------------------------

### Querying list properties

Source: https://isar.dev/queries

Filter objects based on the length of a list or the presence of specific elements.

```Dart
final tweetsWithoutHashtags = await isar.tweets.filter()
  .hashtagsIsEmpty()
  .findAll();

final tweetsWithManyHashtags = await isar.tweets.filter()
  .hashtagsLengthGreaterThan(5)
  .findAll();
```

```Dart
final flutterTweets = await isar.tweets.filter()
  .hashtagsElementEqualTo('flutter')
  .findAll();
```

--------------------------------

### Delete Objects by Query in Isar

Source: https://isar.dev/crud.html

Use `collection.filter()...deleteAll()` to delete objects that match a specific query. This method returns the count of deleted objects.

```dart
await isar.writeTxn(() async {
  final count = await isar.recipes.filter()
    .isFavoriteEqualTo(false)
    .deleteAll();
  print('We deleted $count recipes');
});
```

--------------------------------

### Sort Results Without Using Indexes

Source: https://isar.dev/queries

Sorts shoes by model name ascending and then by size descending using filter methods. Note that these sorting methods do not use indexes and can be slow for large datasets.

```dart
final sortedShoes = isar.shoes.filter()
  .sortByModel()
  .thenBySizeDesc()
  .findAll();

```

--------------------------------

### Enum Storage Strategies in Isar

Source: https://isar.dev/schema.html

Demonstrates different strategies for storing enums in Isar: ordinal (byte index), ordinal32 (short index), name (string), and value (custom property). The 'ordinal' and 'ordinal32' strategies are efficient but sensitive to enum value order changes.

```dart
@collection
class EnumCollection {
  late int id;

  @enumerated // same as EnumType.ordinal
  late TestEnum byteIndex; // cannot be nullable

  @Enumerated(EnumType.ordinal)
  late TestEnum byteIndex2; // cannot be nullable

  @Enumerated(EnumType.ordinal32)
  TestEnum? shortIndex;

  @Enumerated(EnumType.name)
  TestEnum? name;

  @Enumerated(EnumType.value, 'myValue')
  TestEnum? myValue;
}

enum TestEnum {
  first(10),
  second(100),
  third(1000);

  const TestEnum(this.myValue);

  final short myValue;
}

```

--------------------------------

### Define Indexed Collection Schema

Source: https://isar.dev/queries

Adds indexes to the 'Shoe' collection for 'size' and a composite index for 'isUnisex' and 'size'. Indexes significantly speed up queries.

```dart
@collection
class Shoe {
  late int id;

  @Index()
  Id? size;

  late String model;

  @Index(composite: [CompositeIndex('size')])
  late bool isUnisex;
}

```

--------------------------------

### Define an indexed collection

Source: https://isar.dev/indexes

Adding the @Index annotation to a property to create a sorted lookup table.

```dart
@collection
class Product {
  late int id;

  late String name;

  @Index()
  late int price;
}
```

--------------------------------

### Watch an Entire Collection - Isar

Source: https://isar.dev/watchers.html

Subscribe to changes within an entire collection. You will be notified when any object in the collection is added, updated, or deleted.

```dart
Stream<void> userChanged = isar.users.watchLazy();
userChanged.listen(() {
  print('A User changed');
});

final user = User()..name = 'David';
await isar.users.put(user);
// prints: A User changed

```

--------------------------------

### Rename collections and fields

Source: https://isar.dev/schema.html

Use the @Name annotation to map Dart class and field names to different database table and column names.

```dart
@collection
@Name("User")
class MyUserClass1 {

  @Name("id")
  Id myObjectId;

  @Name("firstName")
  String theFirstName;

  @Name("lastName")
  String familyNameOrWhatever;
}
```

--------------------------------

### Insert or Update Object

Source: https://isar.dev/crud.html

Persist a new object or update an existing one in a collection using `put()`. If the ID is null or `Isar.autoIncrement`, Isar assigns an ID.

```dart
final pancakes = Recipe()
  ..name = 'Pancakes'
  ..lastCooked = DateTime.now()
  ..isFavorite = true;

await isar.writeTxn(() async {
  await isar.recipes.put(pancakes);
})

```

--------------------------------

### Annotate Collection Class

Source: https://isar.dev/tutorials/quickstart.html

Annotate your Dart class with @collection and define an Id field for your Isar collection.

```dart
import 'package:isar/isar.dart';

part 'user.g.dart';

@collection
class User {
  Id id = Isar.autoIncrement; // you can also use id = null to auto increment

  String? name;

  int? age;
}

```

--------------------------------

### Bulk Delete Objects by IDs in Isar

Source: https://isar.dev/crud.html

Use `collection.deleteAll([ids])` to efficiently delete multiple objects by their IDs. This method returns the count of deleted objects.

```dart
await isar.writeTxn(() async {
  final count = await isar.recipes.deleteAll([1, 2, 3]);
  print('We deleted $count recipes');
});
```

--------------------------------

### Define an unindexed collection

Source: https://isar.dev/indexes

A standard collection definition without any explicit indexing.

```dart
@collection
class Product {
  late int id;

  late String name;

  late int price;
}
```

--------------------------------

### Define Case-Insensitive Indexes

Source: https://isar.dev/indexes

Use the caseSensitive option to create indexes that ignore character casing for String or List<String> properties.

```dart
@collection
class Person {
  late int id;

  @Index(caseSensitive: false)
  late String name;

  @Index(caseSensitive: false)
  late List<String> tags;
}
```

--------------------------------

### Watch a Specific Object - Isar

Source: https://isar.dev/watchers.html

Subscribe to changes in a specific object by its ID. The watcher is notified when the object is created, updated, or deleted. Set `fireImmediately` to `true` to receive the object's current value upon subscription.

```dart
Stream<User> userChanged = isar.users.watchObject(5);
userChanged.listen((newUser) {
  print('User changed: ${newUser?.name}');
});

final user = User(id: 5)..name = 'David';
await isar.users.put(user);
// prints: User changed: David

final user2 = User(id: 5)..name = 'Mark';
await isar.users.put(user);
// prints: User changed: Mark

await isar.users.delete(5);
// prints: User changed: null

```

--------------------------------

### Define IsarLinks for To-Many Relationship

Source: https://isar.dev/links

Use IsarLinks<T> to define a to-many relationship, allowing a single object to be linked to multiple related objects. It extends Set<T>.

```dart
class Student {
  late int id;

  late String name;

  final teachers = IsarLinks<Teacher>();
}
```

--------------------------------

### Access IsarLink Value

Source: https://isar.dev/links

Retrieve the linked object from an IsarLink by accessing its 'value' property after loading the parent object.

```dart
final linda = await isar.students.where().nameEqualTo('Linda').findFirst();

final teacher = linda.teacher.value; // > Teacher(subject: 'Math')
```

--------------------------------

### Querying embedded objects

Source: https://isar.dev/queries

Efficiently query nested properties within embedded objects using grouped filters.

```Dart
final germanCars = await isar.cars.filter()
  .brand((q) => q
    .nameEqualTo('BMW')
    .and()
    .countryEqualTo('Germany')
  ).findAll();
```

```Dart
final germanCars = await isar.cars.filter()
  .brand((q) => q.nameEqualTo('BMW'))
  .and()
  .brand((q) => q.countryEqualTo('Germany'))
  .findAll();
```

--------------------------------

### Negate Conditions

Source: https://isar.dev/queries

Use the not operator to exclude specific criteria.

```dart
final result = await isar.shoes.filter()
  .not().sizeEqualTo(46)
  .and()
  .not().isUnisexEqualTo(true)
  .findAll();
```

--------------------------------

### Perform distinct operations via where clause

Source: https://isar.dev/queries

Use the distinct parameter in a where clause to leverage the index for distinct operations, which is more efficient than filtering after sorting.

```Dart
final shoes = await isar.shoes.where(distinct: true)
  .anySize()
  .findAll();
```

--------------------------------

### Define a unique index

Source: https://isar.dev/indexes

Using the unique: true parameter in the @Index annotation to prevent duplicate values.

```dart
@collection
class User {
  late int id;

  @Index(unique: true)
  late String username;

  late int age;
}
```

--------------------------------

### Group Filter Conditions

Source: https://isar.dev/queries

Use grouping to control the order of evaluation for complex queries.

```dart
final result = await isar.shoes.filter()
  .sizeBetween(43, 46)
  .and()
  .group((q) => q
    .modelNameContains('Nike')
    .or()
    .isUnisexEqualTo(false)
  )
  .findAll()
```

--------------------------------

### Update Object in Isar

Source: https://isar.dev/crud.html

Use `collection.put(object)` to update an existing object. If the object's ID is null or does not exist, it will be inserted.

```dart
await isar.writeTxn(() async {
  pancakes.isFavorite = false;
  await isar.recipes.put(pancakes);
});
```

--------------------------------

### Conditionally apply query filters

Source: https://isar.dev/queries

Use the optional modifier to apply a filter only when a specific condition is met.

```Dart
Future<List<Shoe>> findShoes(Id? sizeFilter) {
  return isar.shoes.filter()
    .optional(
      sizeFilter != null, // only apply filter if sizeFilter != null
      (q) => q.sizeEqualTo(sizeFilter!),
    ).findAll();
}
```

--------------------------------

### Define embedded objects

Source: https://isar.dev/queries

Model definition for a collection containing an embedded object.

```Dart
@collection
class Car {
  late int id;

  Brand? brand;
}

@embedded
class Brand {
  String? name;

  String? country;
}
```

--------------------------------

### Filter for unique values

Source: https://isar.dev/queries

Use the distinct predicate to return only entries with unique values or combinations of values.

```Dart
final shoes = await isar.shoes.filter()
  .distinctByModel()
  .findAll();
```

```Dart
final shoes = await isar.shoes.filter()
  .distinctByModel()
  .distinctBySize()
  .findAll();
```

--------------------------------

### Ignore fields in a collection

Source: https://isar.dev/schema.html

Exclude specific properties from persistence using the @ignore annotation or the ignore parameter in the @Collection annotation.

```dart
@collection
class User {
  late int id;

  String? firstName;

  String? lastName;

  @ignore
  String? password;
}
```

```dart
@collection
class User {
  Image? profilePicture;
}

@Collection(ignore: {'profilePicture'})
class Member extends User {
  late int id;

  String? firstName;

  String? lastName;
}
```

--------------------------------

### Delete Single Object by ID in Isar

Source: https://isar.dev/crud.html

Use `collection.delete(id)` to remove a single object by its ID. This method returns a boolean indicating if the object was found and deleted.

```dart
await isar.writeTxn(() async {
  final success = await isar.recipes.delete(123);
  print('Recipe deleted: $success');
});
```
Tokens:
Raw