querying: Add new section on queries and pipelines (#117)

* querying: Add new section on queries and pipelines

* querying: Improve docs

docs/index.md

@@ -17,6 +17,7 @@ To develop using Skytable and maintain your deployment you will want to learn ab
       - [**DDL**](blueql/ddl): Data definition with BlueQL
       - [**DML**](blueql/dml): Data manipulation with BlueQL
       - [**DCL**](blueql/dcl): Data control with BlueQL
+    - [**Querying**](querying): Introduces different query modes and when to choose a specific query mode
     - [**System administration**](system):
       - [**Configuration**](system/configuration): Information to help you configure Skytable with custom settings such as custom ports, hosts, TLS, and etc.
       - [**User management**](system/user-management): Information on access control, user and other administration features

docs/protocol/specification.md

@@ -100,3 +100,30 @@ When the client sends a [simple query](#simple-query), the server will respond w
 > **Note**: A `<row count>` or `<column cnt>` is the value of the length in question converted to an ASCII string. 
 
 [^1]: See the [discussion here](https://github.com/skytable/skytable/issues/332)
+
+### Pipeline
+
+A pipeline is a type of query that is used to send multiple queries to the server at once, and the server will return the responses in the same order. There is nothing special about the structure of pipelines. Consider [reviewing this section on pipelines](/querying/#pipelines).
+
+**⚠️ Illegal packet error escape**: If the client incorrectly encodes a pipeline (even though some of the first queries may be encoded correctly), the server will execute the correctly encoded queries and then instead of sending any further responses it will respond with a `0xFF` byte. This is equivalent to [*Query Error 25*](errors#query-errors).
+
+#### Pipeline query
+
+The client is expected to encode the query in the following way:
+
+```
+P<full packet size>\n
+<query size>\n<param payload size>\n<query><param>
+<query size>\n<param payload size>\n<query><param>
+...
+```
+
+#### Pipeline response
+
+The server will return multiple responses:
+
+```
+<response 1>
+<response 2>
+...
+```

docs/querying.md

@@ -0,0 +1,24 @@
+---
+id: querying
+title: Querying
+---
+
+## Simple queries
+
+A simple query is a type of query in which the client sends one query to the server and the server returns an appropriate response (or an error). There are no explicit guarantees provided about the execution of a simple query, other than what was described earlier in the [section on BlueQL](blueql). DDL and DCL queries are guaranteed to be ACID. DML queries are guaranteed to be atomic but have delayed durability.
+
+**When should you use simple queries?** The majority of use-cases will involve running simple queries.
+
+> **Note**: The execution guarantees for queries only apply when the are executed as simple queries.
+
+:::info
+Fully ACID transactions are being worked on and will be available for use soon.
+:::
+
+## Pipelines
+
+A pipeline is a method of sending multiple queries to the server at once, instead of being sent individually. The server keeps the queries in a queue and then executes them one-by-one in order, writing each response to the connection. **Pipelines do not provide any concurrency and execution guarantees** and should not be used in place of ACID transactions. It is merely a convenience provided to reduce round-trip-times (RTTs) associated with multiple requests to the server.
+
+**When should you use pipelines?** Pipelines are to be used when you have to run queries that can run *independently* of one another. For example, if you're "banning some users" you could just put all your `UPDATE` queries in a pipeline and send them to the server. The server will serially execute all the `UPDATE`s independently of one another. If someone `DELETE`s their "account" (i.e the row is gone) that's still fine because you were banning them anyway.
+
+> **Note**: To use pipelines, both your client and server should support pipelines. Pipelines were re-added in 0.8.2 so any client that supports pipelines should be paired with server versions >= 0.8.2

sidebars.ts

@@ -19,6 +19,7 @@ module.exports = {
         id: 'blueql/index'
       }
     },
+    "querying",
     {
       type: 'category',
       label: 'System Administration',