Merge pull request #217 from gramian/main

Mostly SQL improvements and version in manual title page

pom.xml

@@ -10,7 +10,7 @@
 
     <groupId>com.arcadedb</groupId>
     <artifactId>arcadedb-doc</artifactId>
-    <version>23.1.1</version>
+    <version>23.10.1</version>
     <packaging>war</packaging>
 
     <properties>

src/main/asciidoc/concepts/basics.adoc

@@ -122,6 +122,7 @@ It is comparable to the "collection" in Document databases, the "table" in Relat
 You can have up to 2,147,483,648 buckets in a database.
 
 A bucket can only be part of one type. This means two types can not share the same bucket.
+Also, <<Inheritance,sub-types>> have their separate buckets from their super-types.
 
 When you create a new type, the <<SQL-Create-Type,`CREATE TYPE`>> statement automatically creates the physical buckets (files) that serve as the default location in which to store data for that type.
 ArcadeDB forms the bucket names by using the type name + underscore + a sequential number starting from 0. For example, the first bucket for the type `Beer` will be `Beer_0` and the correspondent file in the file system will be `Beer_0.31.65536.bucket`.
@@ -237,7 +238,7 @@ It can manage relationships in a schema-full or schema-less scenario.
 ==== Referenced Relationships
 
 In Relational databases, tables are linked through `JOIN` commands, which can prove costly on computing resources.
-ArcadeDB manages relationships natively without computing a `JOIN` but storing direct links to the target objects of the relationship. This boosts the load speed for the entire graph of connected objects, such as in graph and object database systems.
+ArcadeDB manages relationships natively without computing a `JOIN` but storing a direct `LINK` to the target object of the relationship. This boosts the load speed for the entire graph of connected objects, such as in graph and object database systems.
 
 Example
 
@@ -247,6 +248,10 @@ Example
     RID #5:23               RID #10:2
 ```
 
+Note, that referenced relationships differ from edges:
+references are properties connecting any record while edges are types connecting vertices,
+and particularly, graph traversal is only applicable to edges.
+
 [discrete]
 ==== Embedded Relationships
 

src/main/asciidoc/manual.adoc

@@ -1,3 +1,6 @@
+
+include::version.adoc[]
+
 = ArcadeDB Manual
 :title-logo-image: images/arcadedb-logo.png
 :toc:
@@ -12,5 +15,4 @@ ifdef::backend-pdf[:imagesdir: {docdir}/{imagesdir}]
 :lang: en
 :source-highlighter: rouge
 
-include::version.adoc[]
 include::content.adoc[]

src/main/asciidoc/sql/SQL-Drop-Type.adoc

@@ -19,7 +19,7 @@ DROP TYPE <type> [UNSAFE] [IF EXISTS]
 * *`UNSAFE`* Defines whether the command drops non-empty edge and vertex types. Note, this can disrupt data consistency. Be sure to create a backup before running it.
 * *`IF EXISTS`* Prevent errors if the type does not exits when attempting to drop it.
 
-NOTE: Bear in mind, that the schema must remain coherent. For instance, avoid removing calsses that are super-types to others. This operation won't delete the associated bucket.
+NOTE: Bear in mind, that the schema must remain coherent. For instance, avoid removing types that are super-types to others. This operation won't delete the associated bucket.
 
 *Examples*
 

src/main/asciidoc/sql/SQL-Insert.adoc

@@ -201,17 +201,14 @@ ArcadeDB> INSERT INTO GermanyClient FROM SELECT *, true AS copied FROM Client
 
 This inserts all records from the type `Client` where the country is Germany into the type `GermanClient`, with the addition field `copied` to the value `true`.
 
-* Insert a vertex or edge.
+* Insert a vertex.
 
-Besides the specialized commands <<SQL-Create-Vertex,CREATE VERTEX>> and <<SQL-Create-Edge,CREATE EDGE>>,
+Besides the specialized command <<SQL-Create-Vertex,CREATE VERTEX>>,
 vertices and edges can be inserted via the `INSERT` command:
 
 [source,sql]
 ----
 ArcadeDB> INSERT INTO MyVertexType SET name = 'John Doe'
 ----
 
-[source,sql]
-----
-ArcadeDB> INSERT INTO MyEdgeType SET @out = #34:23, @in = #91:2323
-----
+However, edges have to be created with <<SQL-Create-Edge,CREATE EDGE>>.

src/main/asciidoc/sql/SQL-Rebuild-Index.adoc

@@ -14,13 +14,16 @@ REBUILD INDEX <index-name>
 
 ----
 
-* *`&lt;index-name&gt;`* It is the index name that you want to rebuild. Use `*` to rebuild all automatic indexes. Quote the index name
- if it contains special characters like square brackets.
+* *`&lt;index-name&gt;`* It is the index name that you want to rebuild.
+Use `*` to rebuild all automatic indexes.
+Quote the index name if it contains special characters like square brackets.
 
 NOTE: During the rebuild, any idempotent queries made against the index, skip the index and perform sequential scans. This means
 that queries run slower during this operation. Non-idempotent commands, such as <<SQL-Insert,`INSERT`>>, <<SQL-Update,`UPDATE`>>,
 and <<SQL-Delete,`DELETE`>> are blocked waiting until the indexes are rebuilt.
 
+NOTE: During normal operations an index rebuild is not necessary. Rebuild an index only if it breaks.
+
 *Examples*
 
 * Rebuild an index on the `email` property on the type `Profile`:

src/main/asciidoc/sql/SQL-Script.adoc

@@ -56,6 +56,7 @@ Note the usage of `$account` and `$city` in further SQL commands.
 
 [[Conditional-Execution]]
 *Conditional execution*
+
 SQL Batch provides IF constructor to allow conditional execution.
 The syntax is
 
@@ -68,17 +69,7 @@ IF( <sql-predicate> ){
 }
 ----
 
-`&lt;sql-predicate&gt;` is any valid SQL predicate (any condition that can be used in a `WHERE` clause).
-In current release it's mandatory to have `IF(){`, `&lt;statement&gt;` and `}` on separate lines, eg. the following is not a valid script
-
-[source,sql]
-----
-if( $a.size() > 0 ) {
-  ROLLBACK;
-}
-----
-
-The right syntax is following:
+`&lt;sql-predicate&gt;` is any valid SQL predicate (any condition that can be used in a `WHERE` clause):
 
 [source,sql]
 ----
@@ -90,15 +81,16 @@ IF( $a.size() > 0 ) {
 [[Loops]]
 *Loops*
 
-SQL Batch provides two different loop blocks: `FOREACH` and `WHILE`
+SQL Batch provides two different loop blocks: `FOREACH` and `WHILE`.
 
 [discrete]
 
 ==== FOREACH
 
-Loops on all the items of a collection and, for each of them, executes a set of SQL statements
+Loops on all the items of a collection and, for each of them, executes a set of SQL statements.
+The expression argument should return an array, and can be a literal array, variable, or result of a sub-query.
 
-The syntax is
+The syntax is:
 
 [source,sql]
 ----
@@ -122,9 +114,9 @@ FOREACH( $i IN [1, 2, 3] ){
 
 ==== WHILE
 
-Loops while a condition is true
+Loops while a condition is true.
 
-The syntax is
+The syntax is:
 
 [source,sql]
 ----

src/main/asciidoc/sql/SQL-Update.adoc

@@ -20,7 +20,7 @@ UPDATE <type>|BUCKET:<bucket>|<recordID>
 ----
 
 * *`SET`* Defines the fields to update.
-* *`REMOVE`* Removes an item in collection and map fields.
+* *`REMOVE`* Removes an item in collection and map fields or a property.
 * *`CONTENT`* Replaces the record content with a JSON document.
 * *`MERGE`* Merges the record content with a JSON document.
 * *`UPSERT`* Updates a record if it exists or inserts a new record if it doesn't. This avoids the need to execute two commands, (one for each condition, inserting and updating). 
@@ -40,8 +40,6 @@ Practically `UPSERT` means: `UPDATE` if the `WHERE` condition is fulfilled, othe
 
 ----
 ArcadeDB> UPDATE Profile SET nick = 'Luca' WHERE nick IS NULL
-  
-  Updated 2 record(s) in 0.008000 sec(s).
 ----
 
 * Update to remove a field from all records:
@@ -86,6 +84,12 @@ This remove the second element from a list, (position numbers start from `0`, so
 ArcadeDB> UPDATE Account REMOVE addresses = 'Luca'
 ----
 
+* Update to remove a property values from records
+
+----
+ArcadeDB> UPDATE Account REMOVE addresses WHERE addresses = 'unknown'
+----
+
 * Update an embedded document. The <<SQL-Update,`UPDATE`>> command can take JSON as a value to update.
 
 ----