In the last articles we have dealt with the basics of Isar and with the schemas. Today we will look at how we can access our Isar entries and create, edit or delete new entries.

Happy reading!

Opening Isar

If you want to access a database in Isar, the first thing you need to do is open an Isar instance. We already did this in Part 1, but let’s do it again in more detail.

This looked like this:

Here is a quick recap:

schemas is a list of collection schemas you want to use. By generating code after you have created a class (in our case our Contact), such a schema is created. It will always be schema.

directory is the path where your database is stored. For iOS it is default NSDocumentDirectory and for Android it is default getDataDirectory. The final location is then the path you specified. You don't need directory for the web.

It is recommended to use the package path_provider to get the correct path on each system.

However, there are two other properties you can set. One of them is name.

Since you can open multiple instances of isar, they need to be named somehow. By default "isar" is used, but you can give an arbitrary name to the instance.

The second property I haven’t told you about yet is relaxedDurability. What is that again? Well, the less "durability" the instance has, the faster something can be changed in the database. However, it can happen that in case of a system crash (not an app crash) the last transaction can be lost. Corruption is not possible though.

Now your newly created instance can look like this:

But what happens now if an instance is already open and you call Isar.open() again? The previous instance will be yielded no matter what parameters you specify. This is useful in isolation mode.

Collections

You may remember when we created our Contact class. There we annotated the class with @Collection(). Now this annotation becomes useful. We need it to find, query and create records.

Here is a quick reminder of what our Contacts class looked like:

Getting the contacts collection is quite simple. Just use your previously created instance and call .contacts on it. Now you have the contacts collection.

Next we want to get an entry after the id. To do this, we call .get() on contacts.

As you can see, we use the await keyword here, because by default all Isar operations are asynchronous. However, there is also a synchronous counterpart for most operations. In this case it is getSync().

But when should you use what? Well, in UI isolation you should rather use asynchronous. But since Isar is very fast, it is often okay to use synchronous. But in general you can say: With asynchronous you are on the safe side.

Now we finally want to get several entries. To get all entries, we call the collection and on it where().findAll().

But now we want to find all people where the name starts with A. To do this, we call .where().nameStartsWith(). Now this is something extremely interesting. One of our properties is called name and is of type String. Functions were generated automatically, which then fit for the type string. For bools there is also EqualTo() for example.

Okay, let’s write our code:

As you can see, after this we called findAll() again. As the name says, you find all elements with it. If you put limit() in front of findAll, then you will only get a certain number. This looks like this:

We will deal with queries more in the next article, but for now what we have learned today about queries is enough.

Modifying

It is of little use if we can get entries but cannot create, edit or delete them.

That’s why we want to take a closer look at it now.

No matter what you want to do, you always wrap the execution in writeTxn(). This will look like this:

Now we want to create a new entry:

First we create a new variable of Contact. There we specify all our parameters:

Now we call put() inside our writeTxn() function and pass our new variable:

Note: Isar will automatically assign an id to the object as long as the id is not set to read-only.

Now you want to update an object. This is done with the exact same procedure. But this time you have to specify an already existing id in your new variable, so Isar knows that this record should be updated. As long as no id is specified / the id does not exist yet, a new record will be created.

Finally we want to delete an entry. There are two ways to do it. Once there is the function delete(), with which you delete an entry.

But there is also the function deleteAll(), with which you delete all specified entries. With this function you will not delete all entries of the database, but only the ones you filtered out before. However, you can delete all of them by calling where().findAll() before and then passing this variable.

Conclusion

Today you have learned a lot. We now know how to access our database and edit entries there. The next article will be very big, because Isar offers many ways to filter entries.

If you liked this article and you could learn something, I would be very happy if you give this article some claps! Thanks a lot!

Have a nice day, thanks for reading!