Add TypeQL guides (#1006)

## Goal

We add three new language guides in Guides : TypeQL and move what was
previously Tutorials under Guides : Integrations. We also move the
TypeQL vs SQL comparison page under Guides : TypeQL.

## Implementation

Author: dmitrii-ubskii

core-concepts/modules/ROOT/pages/typeql/index.adoc

@@ -67,10 +67,4 @@ A deeper look at invalid patterns involving disjoint variable reuse
 ****
 Short definitions of terms used throughout the guide, with links to the section which introduces them.
 ****
-
-.xref:{page-version}@core-concepts::typeql/sql-vs-typeql.adoc[]
-[.clickable]
-****
-A guide of relational constructs in SQL compared to similar concepts in TypeQL.
-****
 --

core-concepts/modules/ROOT/partials/nav.adoc

@@ -22,7 +22,6 @@
 ** xref:{page-version}@core-concepts::typeql/invalid-patterns.adoc[]
 // ** xref:{page-version}@core-concepts::typeql/best-practices.adoc[]
 ** xref:{page-version}@core-concepts::typeql/glossary.adoc[]
-** xref:{page-version}@core-concepts::typeql/sql-vs-typeql.adoc[]
 
 
 * xref:{page-version}@core-concepts::drivers/index.adoc[]

tutorials/antora.yml guides/antora.ymltutorials/antora.yml renamed to guides/antora.yml

@@ -1,5 +1,5 @@
-name: tutorials
-title: Tutorials
+name: guides
+title: Guides
 version: '3.x'
 nav:
   - modules/ROOT/nav.adoc 

guides/modules/ROOT/attachments/bookstore-data.tql

@@ -0,0 +1,300 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+define
+
+entity book @abstract,
+    owns isbn @card(0..2),
+    owns isbn-13 @key,
+    owns isbn-10 @unique,
+    owns title,
+    owns page-count,
+    owns genre @card(0..),
+    owns price,
+    plays contribution:work,
+    plays publishing:published,
+    plays promotion-inclusion:item,
+    plays order-line:item,
+    plays rating:rated,
+    plays recommendation:recommended;
+
+entity hardback sub book,
+    owns stock;
+
+entity paperback sub book,
+    owns stock;
+
+entity ebook sub book;
+
+entity contributor,
+    owns name,
+    plays contribution:contributor,
+    plays authoring:author,
+    plays editing:editor,
+    plays illustrating:illustrator;
+
+entity company @abstract,
+    owns name;
+
+entity publisher sub company,
+    plays publishing:publisher;
+
+entity courier sub company,
+    plays delivery:deliverer;
+
+entity publication,
+    owns year,
+    plays publishing:publication,
+    plays locating:located;
+
+entity user,
+    owns id @key,
+    owns name,
+    owns birth-date,
+    owns total-spending,
+    owns loyalty-tier,
+    plays action-execution:executor,
+    plays locating:located,
+    plays recommendation:recipient;
+
+entity order,
+    owns id @key,
+    owns status,
+    plays order-line:order,
+    plays action-execution:action,
+    plays delivery:delivered;
+
+entity promotion,
+    owns code @key,
+    owns name,
+    owns start-timestamp,
+    owns end-timestamp,
+    plays promotion-inclusion:promotion;
+
+entity review,
+    owns id @key,
+    owns score,
+    owns verified,
+    plays rating:review,
+    plays action-execution:action;
+
+entity login,
+    owns success,
+    plays action-execution:action;
+
+entity address,
+    owns street,
+    plays delivery:destination,
+    plays locating:located;
+
+entity place @abstract,
+    owns name,
+    plays locating:located,
+    plays locating:location;
+
+entity city sub place;
+
+entity state sub place;
+
+entity country sub place;
+
+relation contribution,
+    relates contributor,
+    relates work;
+
+relation authoring sub contribution,
+    relates author as contributor;
+
+relation editing sub contribution,
+    relates editor as contributor;
+
+relation illustrating sub contribution,
+    relates illustrator as contributor;
+
+relation publishing,
+    relates publisher,
+    relates published,
+    relates publication;
+
+relation promotion-inclusion,
+    relates promotion,
+    relates item,
+    owns discount;
+
+relation order-line,
+    relates order,
+    relates item,
+    owns quantity;
+
+relation rating,
+    relates review,
+    relates rated;
+
+relation action-execution,
+    relates action,
+    relates executor,
+    owns timestamp;
+
+relation delivery,
+    relates deliverer,
+    relates delivered,
+    relates destination;
+
+relation locating,
+    relates located,
+    relates location;
+
+relation recommendation,
+    relates recommended,
+    relates recipient;
+
+attribute isbn @abstract, value string;
+attribute isbn-13 sub isbn;
+attribute isbn-10 sub isbn;
+attribute title, value string;
+attribute page-count, value integer;
+attribute genre, value string;
+attribute stock, value integer;
+attribute price, value double;
+attribute discount, value double;
+attribute id, value string;
+attribute code, value string;
+attribute name, value string;
+attribute birth-date, value datetime;
+attribute street, value string;
+attribute year, value integer;
+attribute quantity, value integer;
+attribute score, value integer;
+attribute verified, value boolean;
+attribute timestamp, value datetime;
+attribute start-timestamp, value datetime;
+attribute end-timestamp, value datetime;
+attribute status, value string @values("invalid", "pending", "paid", "dispatched", "delivered", "returned", "canceled");
+attribute success, value boolean;
+attribute total-spending, value double;
+attribute loyalty-tier, value integer @range(0..5);
+
+# TODO: Change to check
+fun is_review_verified_by_purchase($review: review) -> { order }:
+  match
+    ($review, $product) isa rating;
+    ($order, $product) isa order-line;
+    ($user, $review) isa action-execution, has timestamp $review-time;
+    ($user, $order) isa action-execution, has timestamp $order-time;
+    $review-time > $order-time;
+  return { $order };
+
+fun book_recommendations_for($user: user) -> {book}:
+  match
+    $new-book isa book;
+    {
+        let $new-book in book_recommendations_by_author($user);
+    } or {
+        let $new-book in book_recommendations_by_genre($user);
+    };
+  return { $new-book };
+
+fun book_recommendations_by_genre($user: user) -> { book }:
+match
+    $user isa user;
+    $liked-book isa book;
+    {
+        ($user, $order-for-liked) isa action-execution;
+        ($order-for-liked, $liked-book) isa order-line;
+    } or {
+        ($user, $review-for-liked) isa action-execution;
+        ($review-for-liked, $liked-book) isa rating;
+        $review-for-liked has score >= 7;
+    };
+    $new-book isa book;
+    not { {
+        ($user, $order-for-new) isa action-execution;
+        ($order-for-new, $new-book) isa order-line;
+    } or {
+        ($user, $review-for-new) isa action-execution;
+        ($review-for-new, $new-book) isa rating;
+    }; };
+    $liked-book has genre $shared-genre;
+    $new-book has genre $shared-genre;
+    not { {
+        $shared-genre == "fiction";
+    } or {
+        $shared-genre == "nonfiction";
+    }; };
+  return { $new-book };
+
+fun book_recommendations_by_author($user: user) -> { book }:
+  match
+    $user isa user;
+    $liked-book isa book;
+    {
+        ($user, $order-for-liked) isa action-execution;
+        ($order-for-liked, $liked-book) isa order-line;
+    } or {
+        ($user, $review-for-liked) isa action-execution;
+        ($review-for-liked, $liked-book) isa rating;
+        $review-for-liked has score >= 7;
+    };
+    $new-book isa book;
+    not { {
+        ($user, $order-for-new) isa action-execution;
+        ($order-for-new, $new-book) isa order-line;
+    } or {
+        ($user, $review-for-new) isa action-execution;
+        ($review-for-new, $new-book) isa rating;
+    }; };
+    ($liked-book, $shared-author) isa authoring;
+    ($new-book, $shared-author) isa authoring;
+  return { $new-book };
+
+fun order_line_best_price($line: order-line) -> { double }:
+  match
+    ($order) isa action-execution, has timestamp $order-time;
+    $line isa order-line, links ($order, $item);
+    $item has price $retail-price;
+    let $time_value = $order-time;
+    let $best-discount = best_discount_for_item($item, $time_value);
+    let $discounted-price = round(100 * $retail-price * (1 - $best-discount)) / 100;
+    $line has quantity $quantity;
+    let $line-total = $quantity * $discounted-price;
+  return { $line-total };
+
+fun best_discount_for_item($item: book, $order-time: datetime) -> double:
+  match
+    {
+        $inclusion isa promotion-inclusion,
+            links ($promotion, $item),
+            has discount $discount-attr;
+        $promotion has start-timestamp <= $order-time,
+            has end-timestamp >= $order-time;
+        let $discount = $discount-attr;
+    } or {
+        let $discount = 0.0; # default
+    };
+return max($discount);
+
+fun transitive_places($place: place) -> { place }:
+  match
+    {
+      locating (located: $place, location: $parent);
+    } or {
+      locating (located: $place, location: $middle);
+      let $parent in transitive_places($middle);
+    };
+  return { $parent };

guides/modules/ROOT/attachments/bookstore-schema.tql

@@ -1,3 +1,3 @@
-// Tutorials
+// Guides
 
 include::{page-version}@home::partial$nav-main.adoc[]

tutorials/modules/ROOT/nav.adoc guides/modules/ROOT/nav.adoctutorials/modules/ROOT/nav.adoc renamed to guides/modules/ROOT/nav.adoc

@@ -0,0 +1,25 @@
+= Guides
+
+In this section, you will find guides for accomplishing specific TypeDB tasks.
+
+**New users** - We recommend new users begin with the xref:{page-version}@home::get-started/index.adoc[get started] guide
+in the home section.
+
+[cols-2]
+--
+.xref:{page-version}@guides::integrations/index.adoc[]
+[.clickable]
+****
+Integrate TypeDB into your application or platform
+****
+
+.xref:{page-version}@guides::typeql/index.adoc[]
+[.clickable]
+****
+Learn how to write TypeQL queries
+****
+--
+
+Got other guides you'd like to see?
+Get in touch at link:mailto:[email protected]?subject=Request%20new%20guide[[email protected]]
+or link:https://typedb.com/discord[join our discord server].

guides/modules/ROOT/pages/index.adoc

@@ -1,11 +1,11 @@
 = Deploy TypeDB via the Cloud API
-:keywords: typedb, typeql, tutorial, api, cloud, cluster, deploy
+:keywords: typedb, typeql, tutorial, guide, api, cloud, cluster, deploy
 :pageTitle: Deploy TypeDB via the Cloud API
-:summary: A tutorial on deploying TypeDB through the API
+:summary: A guide on deploying TypeDB through the API
 :page-toclevels: 2
 :tabs-sync-option:
 
-This tutorial will walk you through the creation of a script
+This guide will walk you through the creation of a script
 to automate deployment of a TypeDB cluster on TypeDB Cloud.
 
 We're going to build a script that authenticates with the API,
@@ -653,7 +653,7 @@ If successful, TypeDB Cloud will deploy your cluster, and the script will poll i
 
 == Conclusion
 
-This tutorial has shown you how to set up a script to deploy TypeDB through the Cloud API.
+This guide has shown you how to set up a script to deploy TypeDB through the Cloud API.
 
 Similar approaches can be used for other common actions,
 such as pausing or resuming your clusters when not in use.