diff --git a/assets/banner.svg b/assets/banner.svg index 221b61b..3939945 100644 --- a/assets/banner.svg +++ b/assets/banner.svg @@ -1,442 +1,915 @@ - + - - - + + + - - - - - - - - - - - - + + + + + + + + + + + + - - + + - - - - - - - + + + + + + + - - - - + + + + - - - + + + - - - - + + + + - - - + + + - - + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + - - - - - - - - + + + + + + + + - - - - - - + + + + + + - - - - - - - - - + + + + + + + + + - - + + - - - - - - - - - - - - - - + + + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + - - - - - + + + + + - - - - - - - - - - - - - + + + + + + + + + + + + + - - - - - + + + + + - - + + - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + - - - - - + + + + + - - - - - - - - - - - + + + + + + + + + + + - - - - - - + + + + + + - - - - + + + + - - - - + + + + - - + + - - + + - - - + + + diff --git a/flutter-sdk/collection/indexing.md b/flutter-sdk/collection/indexing.md new file mode 100644 index 0000000..7602d9e --- /dev/null +++ b/flutter-sdk/collection/indexing.md @@ -0,0 +1,45 @@ +--- +label: Indexing +icon: list-ordered +order: 14 +--- + +Indexing is a way to optimize the performance of a database by minimizing the number of disk accesses required when a query is processed. It is a data structure technique which is used to quickly locate and access the data in a database. + +Nitrite supports indexing on a collection. It supports indexing on a single field or multiple fields. It also supports full-text indexing. + +## Index Types + +Nitrite supports the following types of index out of the box: + +- Unique Index +- Non-Unique Index +- Full-text Index + +### Unique Index + +A unique index ensures that the indexed field contains unique value. It does not allow duplicate value in the indexed field. It also ensures that the indexed field is not `null`. + +### Non-unique Index + +A non-unique index does not ensure that the indexed field contains unique value. It allows duplicate value in the indexed field. + +### Full-text Index + +A full-text index is used to search text content in a document. It is useful when you want to search text content in a document. It is also useful when you want to search text content in a document in a language other than English. + +!!!info +- Document's `_id` field is always indexed. +- Indexing on non-comparable value is not supported. +!!! + +### Custom Index + +You can also create your own custom index. You need to implement `NitriteIndexer` interface to create your own custom index. `NitriteIndexer` is a [`NitritePlugin`](../modules/module-system.md#nitriteplugin), so you need to register it using `loadModule()` method while opening a database. During index creation you need to pass the type of the custom index in `IndexOptions` object. + +## Creating an Index + +You can create an index on a collection using `createIndex()` method. There are several overloaded version of `createIndex()` method. You can create an index on a single field or multiple fields. + +### Creating a Unique Index + diff --git a/flutter-sdk/collection/write.md b/flutter-sdk/collection/write.md new file mode 100644 index 0000000..a278db9 --- /dev/null +++ b/flutter-sdk/collection/write.md @@ -0,0 +1,177 @@ +--- +label: Write Operations +icon: pencil +order: 16 +--- + +## Inserting Documents + +Documents can be inserted into a collection using `insert()` or `insertMany()` methods. It takes one or multiple `Document` objects as input parameter respectively. It returns a `Future` object. + +If the document has a `NitriteId` already in it's `_id` field, then it will be used as a unique key to identify the document in the collection. Otherwise, a new `NitriteId` will be generated and inserted into the document. + +If any of the field is already indexed in the collection, then the index will be updated accordingly. + +!!!info +This operation will notify all the registered `CollectionEventListener` with `EventType.insert` event. +!!! + +### Inserting a Single Document + +```dart +var doc = createDocument("firstName", "John") + ..put("lastName", "Doe") + ..put("age", 30) + ..put("data", Uint8List.fromList([1, 2, 3, 4, 5])); + +var result = await collection.insert(doc); +``` + +### Inserting Multiple Documents + +```dart +var doc1 = createDocument("firstName", "John") + ..put("lastName", "Doe") + ..put("age", 30) + ..put("data", Uint8List.fromList([1, 2, 3, 4, 5])); + +var doc2 = createDocument("firstName", "Jane") + ..put("lastName", "Doe") + ..put("age", 25) + ..put("data", Uint8List.fromList([1, 2, 3, 4, 5])); + +var result = await collection.insertMany([doc1, doc2]); +``` + +### Error Scenarios + +- If the document contains invalid value in it's `_id` field, then it will throw a `InvalidIdException`. +- If there is another document with the same `_id` value in the collection, then it will throw a `UniqueConstraintException`. +- If a field of the document is unique indexed and it's value violates the index constraint, then it will throw a `UniqueConstraintException`. + +### WriteResult + +`WriteResult` contains the result of a write operation. It contains the following information: + +- Number of documents affected by the write operation. You can get this value using `getAffectedCount()` method. +- List of `NitriteId` of the documents affected by the write operation. The `WriteResults` implements `Iterable` interface. So you can iterate over the `WriteResult` to get the `NitriteId` of the documents affected by the write operation. + +## Updating Documents + +Documents can be updated using any of the following methods: + +- `updateOne()` - Updates a single document. +- `update()` - Update the filtered documents in the collection. + +All update methods returns a `Future` object. + +!!!info +This operation will notify all the registered `CollectionEventListener` with `EventType.update` event. +!!! + +### Updating a Single Document + +You can update a single document using `updateOne()` method. It takes a `Document` object as input parameter. It returns a `Future` object. The document must contain a valid `NitriteId` in it's `_id` field. + +```dart +var doc = createDocument("_id", existingDoc.id) + ..put("age", 30); + +var result = await collection.updateOne(doc); +``` + +!!!warning +If the document does not contain a valid `NitriteId` in it's `_id` field, then it will throw a `NotIdentifiableException`. +!!! + +### Upserting a Single Document + +You can also upsert a single document using `updateOne()` method. Along with the `document` parameter, you need to pass a named parameter `insertIfAbsent` with value `true`. If the document does not exist in the collection, then it will be inserted. Otherwise, it will be updated. The default value of `insertIfAbsent` is `false`. + +```dart +var doc = createDocument("_id", existingDoc.id) + ..put("lastName", "Doe") + ..put("age", 30); + +var result = await collection.updateOne(doc, insertIfAbsent: true); +``` + +### Updating Using a Filter + +You can update a document using a filter. It takes a `Filter` object as the first input parameter. It takes a `Document` object as the second input parameter. It returns a `Future` object. + +```dart +var update = createDocument("_id", existingDoc.id) + ..put("lastName", "Doe") + ..put("age", 30) + ..put("data", Uint8List.fromList([1, 2, 3, 4, 5])); + +var result = await collection.update(where("firstName").eq("John"), update); +``` + +### Updating Using a Filter and Options + +You can update a document using a filter and options. It takes a `Filter` object as the first input parameter. It takes a `Document` object as the second input parameter. It takes a `UpdateOptions` object as the optional third input parameter. It returns a `Future` object. + +#### UpdateOptions + +`UpdateOptions` is a class that contains several options for update operation. It has the following options: + +- `insertIfAbsent`: If this option is `true`, then it will insert the document if it does not exist in the collection. Otherwise, it will update the document if it exists in the collection. +- `justOnce`: If this option is `true`, then it will update only the first document matched by the filter. Otherwise, it will update all the documents matched by the filter. + +```dart +var update = createDocument("_id", existingDoc.id) + ..put("lastName", "Doe") + ..put("age", 30) + ..put("data", Uint8List.fromList([1, 2, 3, 4, 5])); + +var updateOptions = UpdateOptions(); +updateOptions.insertIfAbsent = true; +updateOptions.justOnce = true; + +var result = await collection.update(where("firstName").eq("John"), update, updateOptions); +``` + +## Removing Documents + +Documents can be removed from a collection using any of the following methods: + +- `removeOne()` - Removes a single document. +- `remove()` - Removes the filtered documents from the collection. + +All remove methods returns a `Future` object. + +!!!info +This operation will notify all the registered `CollectionEventListener` with `EventType.remove` event. +!!! + +### Removing a Single Document + +You can remove a single document using `removeOne()` method. It takes a `Document` object as input parameter. It returns a `Future` object. The document must contain a valid `NitriteId` in it's `_id` field. + +```dart +var doc = createDocument("_id", existingDoc.id); + +var result = await collection.removeOne(doc); +``` + +!!!warning +If the document does not contain a valid `NitriteId` in it's `_id` field, then it will throw a `NotIdentifiableException`. +!!! + +### Removing Using a Filter + +You can remove a document using a filter. It takes a `Filter` object as the input parameter. It returns a `Future` object. + +```dart +var result = await collection.remove(where("firstName").eq("John")); +``` + +### Removing Using a Filter and Options + +You can remove a document using a filter and options. It takes a `Filter` object as the first input parameter. It takes a named parameter `justOne` with value `true` or `false`. If the value is `true`, then it will remove only the first document matched by the filter. Otherwise, it will remove all the documents matched by the filter. The default value of `justOne` is `false`. It returns a `Future` object. + +```dart +var result = await collection.remove(where("firstName").eq("John"), justOne: true); +``` \ No newline at end of file diff --git a/flutter-sdk/getting-started.md b/flutter-sdk/getting-started.md index caef8f9..eb639e7 100644 --- a/flutter-sdk/getting-started.md +++ b/flutter-sdk/getting-started.md @@ -7,6 +7,8 @@ order: 20 # Getting Started in Flutter +Nitrite is a pure Dart database. It does not depend on any native library. So it can be used in any platform where Dart is supported. It is a server-less embedded database ideal for desktop, mobile, or web applications. It is written in pure Dart and runs in Flutter, Dart VM, and the browser. + To get started with Nitrite database, you need to add the dependency to your pubspec.yaml file. ## Add dependency @@ -37,4 +39,8 @@ dependencies: nitrite_hive_adapter: ^[latest version] ``` -More details about the hive adapter can be found [here](modules/store-modules/hive.md). \ No newline at end of file +More details about the hive adapter can be found [here](modules/store-modules/hive.md). + +!!!info +Nitrite is null safe. So you can use it in your null safe project. +!!! \ No newline at end of file diff --git a/java-sdk/collection/read.md b/java-sdk/collection/read.md index 25032b0..2699b51 100644 --- a/java-sdk/collection/read.md +++ b/java-sdk/collection/read.md @@ -4,8 +4,6 @@ icon: search order: 15 --- - - ## Find Operations You can search documents in a collection using `find()` method. There are several overloaded version of `find()` method using a filter or find options or both. You can also search a document using it's `NitriteId`. diff --git a/retype.yml b/retype.yml index 7082181..6e6dcef 100644 --- a/retype.yml +++ b/retype.yml @@ -12,7 +12,7 @@ favicon: /assets/favicon.png links: - text: Home icon: home - link: https://nitrite.github.io + link: https://nitrite.github.io/nitrite-doc - text: Github link: https://github.com/nitrite diff --git a/welcome.md b/welcome.md index 3e79d75..62a628b 100644 --- a/welcome.md +++ b/welcome.md @@ -3,7 +3,6 @@ icon: home label: Welcome description: 'Nitrite is a serverless, embedded, and self-contained NoSQL database. It is an open-source project that provides a simple API for persistent data storage. Nitrite database is designed to be lightweight, fast, and easy to use.' order: 10 -layout: blog --- ![](assets/banner.svg) @@ -64,3 +63,7 @@ Contributions, issues and feature requests are welcome!
Feel free to open a ## 🎞️ Showcase If you are using Nitrite database in your project, please let us know. We will be happy to showcase your project [here](/showcase). + + +

+Image by Freepik