From 3fffe06ea377d8ab7fa667211b3329d6803d08da Mon Sep 17 00:00:00 2001 From: Sayan Nandan Date: Sat, 6 Apr 2024 18:20:27 +0000 Subject: [PATCH 1/2] querying: Add new section on queries and pipelines --- docs/protocol/specification.md | 27 +++++++++++++++++++++++++++ docs/querying.md | 23 +++++++++++++++++++++++ sidebars.ts | 1 + 3 files changed, 51 insertions(+) create mode 100644 docs/querying.md diff --git a/docs/protocol/specification.md b/docs/protocol/specification.md index 6b6fb6742..993a82e4f 100644 --- a/docs/protocol/specification.md +++ b/docs/protocol/specification.md @@ -101,3 +101,30 @@ When the client sends a [simple query](#simple-query), the server will respond w > **Note**: A `` or `` 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\n +\n\n +\n\n +... +``` + +#### Pipeline response + +The server will return multiple responses: + +``` + + +... +``` diff --git a/docs/querying.md b/docs/querying.md new file mode 100644 index 000000000..f9b210c99 --- /dev/null +++ b/docs/querying.md @@ -0,0 +1,23 @@ +--- +id: querying +title: Querying +--- + +In this document we explore different query modes that Skytable supports. + +## 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). + +Overall, all DDL and DCL queries are guaranteed to be ACID while DML queries are of a delayed-durability nature. + +## 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 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. + +For example, instead of sending multiple queries you could re-initialize a database in one query by putting it into a pipeline: + +```sql +CREATE SPACE IF NOT EXISTS myspace +CREATE MODEL IF NOT EXISTS myspace.mymodel(username: string, password: string) +``` diff --git a/sidebars.ts b/sidebars.ts index 9b1e3f9a3..3d8cb09e9 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -19,6 +19,7 @@ module.exports = { id: 'blueql/index' } }, + "querying", { type: 'category', label: 'System Administration', From 9e72cbc7d5d3b758d5b4cbb47f20803b31dfcbea Mon Sep 17 00:00:00 2001 From: Sayan Nandan Date: Wed, 24 Apr 2024 08:19:38 +0000 Subject: [PATCH 2/2] querying: Improve docs --- docs/index.md | 1 + docs/querying.md | 21 +++++++++++---------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/index.md b/docs/index.md index 7e279ca7c..c02587b2f 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/querying.md b/docs/querying.md index f9b210c99..31a0147d8 100644 --- a/docs/querying.md +++ b/docs/querying.md @@ -3,21 +3,22 @@ id: querying title: Querying --- -In this document we explore different query modes that Skytable supports. - ## 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). +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. -Overall, all DDL and DCL queries are guaranteed to be ACID while DML queries are of a delayed-durability nature. +:::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 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. +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. -For example, instead of sending multiple queries you could re-initialize a database in one query by putting it into a pipeline: +**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. -```sql -CREATE SPACE IF NOT EXISTS myspace -CREATE MODEL IF NOT EXISTS myspace.mymodel(username: string, password: string) -``` +> **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