Add "CRUD operations" and "Understanding FerretDB" sections

website/docs/Basic_operations/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Basic CRUD Operations",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Perform basic CRUD operations using FerretDB."
+  }
+}

website/docs/Basic_operations/create.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 2
+---
+
+# Insert operation
+
+The insert operation adds a new document to a collection.
+
+## Insert a single document
+
+The `insertOne()` command is used to add a single document into a collection, using this syntax format:
+
+```sh
+db.collection.insertOne({field1: value1, field2: value2,.... fieldN: valueN})
+```
+
+The example below depicts how a single document can be added to a collection.
+
+```sh
+db.scientists.insertOne({name:{firstname: "Thomas", lastname: "Edison"}, born: 1847, invention: "lightbulb"})
+```
+
+If the operation is successful, you will get a response with acknowledged set to true, and the autogenerated ObjectId of the document.
+
+:::note
+If a collection does not exist, the insert command automatically creates one.
+:::
+
+## Insert multiple documents at once
+
+A collection can contain multiple documents.
+Using the `insertMany()` command, you can add multiple documents to a collection at once.
+
+```sh
+db.collection_name.insertMany([{document1}, {document2},... {documentN}])
+```
+
+The following example shows how to insert multiple documents into a collection:
+
+```sh
+db.scientists.insertMany([{name:{firstname: "Alan", lastname: "Turing"}, born: 1912, invention: "Turing Machine"},{name:{firstname: "Graham", lastname: "Bell"}, born: 1847, invention: "telephone"},{name:{firstname: "Ada", lastname: "Lovelace"}, born: 1815, invention: "computer programming"}])
+```
+
+You can retrieve all the documents in the collection with this command: `db.scientists.find({})`

website/docs/Basic_operations/delete.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 5
+---
+
+
+# Delete operation
+
+The delete operation removes a document from the database when a given query is met.
+Two methods for deleting documents in a collection include `deleteOne()` and `deleteMany()`.
+
+## Delete a single document
+
+The `deleteOne()` method removes a single document (the first document that matches the query parameter) completely from the collection.
+
+```sh
+db.collection.deleteOne({<query_params>})
+```
+
+Insert the following list of documents:
+
+```sh
+db.scientists.insertMany([{firstname: "Thomas", lastname: "Edison", born: 1847, invention: "LightBulb", nobel:true},{firstname: "Graham", lastname: "Bell", born: 1847, invention: "telephone", nobel:false},{firstname: "Nikola", lastname: "Tesla", born: 1856, invention: "Tesla coil", nobel:false}, {firstname: "Ada", lastname: "Lovelace", born: 1815, invention: "Computer programming", nobel:false}])
+```
+
+Next, delete a document from the collection where the field `nobel` is set to false.
+
+```sh
+db.scientists.deleteOne({nobel:false})
+```
+
+## Deletes multiple documents
+
+To delete multiple documents at once, use the  `deleteMany()` method.
+Using the same record from earlier, let's delete all the documents with `nobel` set to false.
+
+```sh
+db.scientists.deleteMany({nobel:false})
+```
+
+This command removes all the documents in the collection that matches the query.

website/docs/Basic_operations/index.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 1
+---
+
+
+
+# Performing CRUD operations
+
+CRUD (Create, Read, Update, and Delete) operations in FerretDB uses the same protocols and drivers as MongoDB.
+
+## Create operations in FerretDB
+
+The create operation adds a new document to a collection.
+If the collection does not exist, this operation will create it.
+The following methods are available for adding documents to a collection:
+
+[`db.collection.insertOne()`](./create.md#insert-a-single-document), [`db.collection.insertMany()`](./create.md#insert-many-documents-at-once)
+
+## Read operations in FerretDB
+
+The read operation retrieves document records in a collection.
+You can also filter the documents by targeting specific criteria for retrieval.
+The following commands are used to retrieve documents from a collection:
+
+[`db.collection.find()`](./read.md#retrieve-all-documents-in-a-collection), [`db.collection.findOne()`](./read.md#retrieve-a-single-document)
+
+The read operation can also retrieve subdocuments that are nested within a document.
+
+## Update operations in FerretDB
+
+The update operation modifies document records in a collection.
+It changes existing documents in a collection according to the query criteria.
+The following update operations are supported:
+
+[`db.collection.updateOne()`](./update.md#modify-a-single-document), [`db.collection.updateMany()`](./update.md#modify-many-documents), [`db.collection.replaceOne()`](./update.md#replace-a-document)
+
+## Delete operations in FerretDB
+
+The delete operation removes document records from a collection.
+The following delete operations are supported:
+
+[`db.collection.deleteOne()`](./delete.md#delete-a-single-document), [`db.collection.deleteMany()`](./delete.md#deletes-multiple-documents)
+
+Similar to the update operation, this operation retrieves documents matching specific criteria in a collection and deletes them.

website/docs/Basic_operations/read.md

@@ -0,0 +1,69 @@
+---
+sidebar_position: 3
+---
+
+# Read operation
+
+The read operation retrieves documents in a collection.
+You can either retrieve all the documents in a collection, or only the documents that match a given query parameter.
+
+## Retrieve all documents in a collection
+
+The `find()` command is used for retrieveing all the documents in a collection.
+
+```sh
+db.collection.find()
+```
+
+First, populate the database with a new collection containing a list of documents.
+
+```sh
+db.scientists.insertMany([{name:{firstname: "Alan", lastname: "Turing"}, born: 1912, invention: "Turing Machine"},{name:{firstname: "Graham", lastname: "Bell"}, born: 1847, invention: "telephone"},{name:{firstname: "Ada", lastname: "Lovelace"}, born: 1815, invention: "computer programming"}])
+```
+
+Run `db.scientists.find()` to see the complete list of documents in the collection.
+
+### Retrieve documents based on a specific query
+
+Using the `find()` command, you can also filter a collection for only the documents that match the provided query.
+For example, find the document with the field `born` set as 1857.
+
+```sh
+db.scientists.find({born: 1857})
+```
+
+### Retrieve documents using operator queries
+
+The operator syntax allows users to query and retrieve a document.
+There are several operator methods that you can use, such as `$gt` or `$lt`.
+For example, to find the list of scientists born after the 1900s, we'll need the `$gt` operator:
+
+```sh
+db.scientists.find({born:{$gt:1900}})
+```
+
+Here is a list of the most commonly used operators.
+
+`$gt`: selects records that are greater than a specific value
+
+`$lt`:  selects records that are less than a specific value
+
+`$gte`: selects records greater or equal to a specific value
+
+`$lte`: selects records less than or equal to a specific value
+
+`$in`: selects any record that contains any of the items present in a defined array
+
+`$nin`: selects any record that does not contain any of the items in a defined array
+
+`$ne`: selects records that are not equal to a specific value
+
+`$eq`: select records that are equal to a specific value
+
+## Retrieve a single document
+
+The `findOne()` command retrieves a single document from a collection.
+
+```sh
+db.scientists.findOne({invention: "Turing Machine"})
+```

website/docs/Basic_operations/update.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 4
+---
+
+
+# Update operation
+
+The update operation modifies a document record in a collection, based on a given query parameter and update.
+The `$set` operator assigns the updated record to the document.
+
+## Modify a single document
+
+Use the `updateOne()` method to update a single document in a collection.
+This operation filters a collection using a query parameter, and updates given fields within that document.
+
+```sh
+db.collection.updateOne({<query-params>}, {$set: {<update fields>}})
+```
+
+First, populate the database with a collection containing a list of documents.
+
+```sh
+db.scientists.insertMany([{firstname: "Thomas", lastname: "Edison", born: 1847, invention: "LightBulb", nobel:true},{firstname: "Graham", lastname: "Bell", born: 1847, invention: "telephone", nobel:false},{firstname: "Nikola", lastname: "Tesla", born: 1856, invention: "Tesla coil", nobel:false}, {firstname: "Ada", lastname: "Lovelace", born: 1815, invention: "Computer programming", nobel:false}])
+```
+
+Using the document record in the collection, update the document where name is `firstname` is "Graham", and set the `firstname` as "Alexander Graham".
+The `updateOne()` operation will only affect the first document that’s retrieved in the collection.
+
+```sh
+db.scientists.updateOne({name:"Graham"}, {$set: {name:"Alexander Graham"}})
+```
+
+## Modify many documents
+
+Using the `updateMany()` command, you can modify many documents at once.
+In the example below, where `nobel` is set as false, update and set to true.
+
+```sh
+db.scientists.updateMany({nobel:false}, {$set: {nobel:true}})
+```
+
+This operation updates all the documents where the field `nobel` was previously false.
+
+## Replace a document
+
+Besides updating a documenting, you can also replace it completely using the `replaceOne()` method.
+
+```sh
+db.league.replaceOne({lastname: "Bell"}, {firstname: "Albert", lastname: "Einstein", born: 1879, invention: "Quantum Theory", nobel:true})
+```

website/docs/contributing.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 5
 ---
 
 # How to contribute to FerretDB
@@ -19,7 +19,7 @@ Please take a look at this post on [how to contribute to open source software](h
 ## Get Started
 
 You don’t have to be a developer to contribute to FerretDB projects, you can even get started by helping us improve this documentation.
-If you have any questions or suggestions on how we can improve, kindly join our [Slack chat](/intro/#community) or [GitHub discussions](https://github.com/FerretDB/FerretDB/discussions).
+If you have any questions or suggestions on how we can improve, kindly join our [Slack chat](https://docs.ferretdb.io/intro/#community) or [GitHub discussions](https://github.com/FerretDB/FerretDB/discussions).
 We appreciate your feedback.
 
 ## Contributing to this documentation

website/docs/diff.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 6
 ---
 
 # Known differences

website/docs/understanding_ferretdb.md

@@ -1,13 +1,96 @@
 ---
-sidebar_position: 4
+sidebar_position: 2
 ---
 
 # Understanding FerretDB
 
-## Databases
+FerretDB is a document database that uses similar commands, drivers, and tools to those of MongoDB for storing data.
+Unlike relational databases, which use tables, rows, and columns to define the schema of the database, document databases use key-value pairs to build the structure of a document.
 
-## Collections
+Document databases can collect, store, and retrieve any data type.
+In FerretDB, data is stored as [BSON](https://bsonspec.org/spec.html) - a binary representation of JSON - so you can store more types of data than in regular JSON.
+However, we do not currently support "128-bit decimal floating points".
+
+Before inserting data into a document, you do not need to declare a schema.
+That makes it ideal for applications and workloads requiring flexible schemas, such as blogs, chat apps, and video games.
 
 ## Documents
 
-## Data Model
+Documents are self-describing records containing both data types and a description of the data being stored.
+They are similar to rows in relational databases.
+Here is an example of a single document:
+
+```json
+{
+    first: "Thomas",
+    last: "Edison",
+    invention: "Lightbulb",
+    birth: 1847
+}
+
+```
+
+The above data is stored in a single document.
+
+:::note
+FerretDB follows almost the same naming conventions as MongoDB.
+However, there are a few restrictions, which you can find  [here](https://docs.ferretdb.io/diff/).
+:::
+
+For complex documents, you can nest objects (subdocuments) inside a document.
+
+```json
+{
+    name: { first: "Thomas", last: "Edison" },
+    invention: "Lightbulb",
+    birth: 1847
+}
+```
+
+In the example above, the `name` field is a subdocument embedded into a document.
+
+## Collections
+
+Collections are a repository for documents.
+To some extent, they are similar to tables in a relational database.
+If a collection does not exist, this operation creates a new one.
+A collection may contain one or more documents.
+For example, the following collection contains threee documents.
+
+```json
+ Scientists: {
+    first : "Alan",
+    last : "Turing",
+    born : 1912
+    },
+    {
+    first : "Thomas",
+    last : "Edison",
+    birth : 1847
+    },
+    {
+    first : "Nikola",
+    last : "Tesla",
+    birth : 1856
+    }
+
+```
+
+## Indexing
+
+FerretDB does not currently support indexing.
+Kindly check [our roadmap](https://github.com/orgs/FerretDB/projects/2) or the [open issue on indexing support](https://github.com/FerretDB/FerretDB/issues/78) to know when this will be made available available.
+
+## Data Storage
+
+ FerretDB converts MongoDB drivers and protocols to SQL, with the data stored in PostgreSQL or Tigris Data.
+For PostgreSQL, we convert MongoDB bson to jsonb and store it as a value in a row.
+
+In Tigris case, we convert bson to tigirs tjson.
+There are a few things to take note of here.
+For example, you cannot overwrite the data type of a value.
+Please check here for more details on the differences.
+
+:::caution
+FerretDB is still under development and not currently suitable for production-ready environments.
+:::