Merge edgeql ref/high-level sections

docs/redirects.js

@@ -162,7 +162,17 @@ module.exports = [
   },
   {
     source: "/reference/reference/configuration",
-    destination: "/reference/running/configuration",
+    destination: "/reference/edgeql/session",
+    permanent: false,
+  },
+  {
+    source: "/reference/reference/edgeql/sess_reset_alias",
+    destination: "/reference/edgeql/session#reset",
+    permanent: false,
+  },
+  {
+    source: "/reference/reference/edgeql/sess_set_alias",
+    destination: "/reference/edgeql/session#set",
     permanent: false,
   },
   {

docs/reference/datamodel/globals.rst

@@ -59,22 +59,10 @@ behavior and principles are the same across all libraries.
 
 .. tabs::
 
-  .. code-tab:: typescript
-
-    import createClient from 'gel';
-
-    const baseClient = createClient();
-
-    // returns a new Client instance, that shares the underlying
-    // network connection with `baseClient` , but sends the configured
-    // globals along with all queries run through it:
-    const clientWithGlobals = baseClient.withGlobals({
-      current_user_id: '2141a5b4-5634-4ccc-b835-437863534c51',
-    });
+  .. code-tab:: edgeql
 
-    const result = await clientWithGlobals.query(
-      `select global current_user_id;`
-    );
+    set global current_user_id :=
+      <uuid>'2141a5b4-5634-4ccc-b835-437863534c51';
 
   .. code-tab:: python
 
@@ -93,6 +81,23 @@ behavior and principles are the same across all libraries.
         select global current_user_id;
     """)
 
+  .. code-tab:: typescript
+
+    import createClient from 'gel';
+
+    const baseClient = createClient();
+
+    // returns a new Client instance, that shares the underlying
+    // network connection with `baseClient` , but sends the configured
+    // globals along with all queries run through it:
+    const clientWithGlobals = baseClient.withGlobals({
+      current_user_id: '2141a5b4-5634-4ccc-b835-437863534c51',
+    });
+
+    const result = await clientWithGlobals.query(
+      `select global current_user_id;`
+    );
+
   .. code-tab:: go
 
     package main
@@ -150,11 +155,6 @@ behavior and principles are the same across all libraries.
         .expect("Returning value");
     println!("Result: {val}");
 
-  .. code-tab:: edgeql
-
-    set global current_user_id :=
-      <uuid>'2141a5b4-5634-4ccc-b835-437863534c51';
-
 
 Cardinality
 ===========

docs/reference/edgeql/analyze.rst

@@ -3,11 +3,17 @@
 Analyze
 =======
 
+:eql-statement:
+
+``analyze`` -- trigger performance analysis of the appended query
+
+Overview
+--------
+
 .. index:: explain, performance, postgres query planner
 .. api-index:: analyze
 
-Prefix an EdgeQL query with ``analyze`` to run a performance analysis of that
-query.
+Prefix an EdgeQL query with ``analyze`` to run a performance analysis of that query.
 
 .. code-block:: edgeql-repl
 
@@ -21,8 +27,9 @@ query.
   ...     }
   ...   }
   ... };
-  ──────────────────────────────────────── Query ────────────────────────────────────────
-  analyze select ➊  Hero {name, secret_identity, ➋  villains: {name, ➌  nemesis: {name}}};
+  ────────────────────────────────── Query ──────────────────────────────────
+  analyze select ➊  Hero {name, secret_identity, ➋  villains:
+  {name, ➌  nemesis: {name}}};
 
   ──────────────────────── Coarse-grained Query Plan ────────────────────────
                     │ Time     Cost Loops Rows Width │ Relations
@@ -33,20 +40,28 @@ query.
 
 .. note::
 
-    In addition to using the ``analyze`` statement in the CLI or UI's REPL, you
-    may also run performance analysis via our CLI's :ref:`analyze command
-    <ref_cli_gel_analyze>` and the UI's query builder (accessible by running
-    :ref:`ref_cli_gel_ui` to invoke your instance's UI) by prepending your
-    query with ``analyze``. This method offers helpful visualizations to to
-    make it easy to understand your query's performance.
+    In addition to using the ``analyze`` statement in the CLI or UI's REPL, you may also run performance analysis via our CLI's :gelcmd:`analyze` command and the UI's query builder (accessible by running :ref:`ref_cli_gel_ui` to invoke your instance's UI) by prepending your query with ``analyze``. This method offers helpful visualizations to to make it easy to understand your query's performance.
 
 After analyzing a query, you may run the ``\expand`` command in the REPL to see
 more fine-grained performance metrics on the previously analyzed query.
 
 
-.. list-table::
-  :class: seealso
+.. _ref_eql_statements_analyze:
+
+EdgeQL Syntax
+-------------
+
+.. eql:synopsis::
+
+    analyze <query>;
+
+    # where <query> is any EdgeQL query
+
+``analyze`` returns a table with performance metrics broken down by node.
+
+You may prepend the ``analyze`` keyword in either of our REPLs (CLI or :ref:`UI
+<ref_cli_gel_ui>`) or you may prepend in the UI's query builder for a
+helpful visualization of your query's performance.
 
-  * - **See also**
-  * - :ref:`CLI > gel analyze <ref_cli_gel_analyze>`
-  * - :ref:`Reference > EdgeQL > analyze <ref_eql_statements_analyze>`
+After any ``analyze`` in a REPL, run the ``\expand`` command to see
+fine-grained performance analysis of the previously analyzed query.

docs/reference/edgeql/delete.rst

@@ -3,9 +3,12 @@
 Delete
 ======
 
+:eql-statement:
+:eql-haswith:
+
 .. api-index:: delete
 
-The ``delete`` command is used to delete objects from the database.
+``delete`` -- remove objects from a database.
 
 .. code-block:: edgeql
 
@@ -104,9 +107,65 @@ permanently deleted.
     title: 'Untitled',
   }}
 
+.. _ref_eql_statements_delete:
+
+EdgeQL Syntax
+-------------
+
+.. eql:synopsis::
+
+    [ with <with-item> [, ...] ]
+
+    delete <expr>
+
+    [ filter <filter-expr> ]
+
+    [ order by <order-expr> [direction] [then ...] ]
+
+    [ offset <offset-expr> ]
+
+    [ limit  <limit-expr> ] ;
+
+:eql:synopsis:`with`
+    Alias declarations.
+
+    The ``with`` clause allows specifying module aliases as well
+    as expression aliases that can be referenced by the ``delete``
+    statement.  See :ref:`ref_eql_statements_with` for more information.
+
+:eql:synopsis:`delete ...`
+    The entire :eql:synopsis:`delete ...` statement is syntactic
+    sugar for ``delete (select ...)``. Therefore, the base
+    :eql:synopsis:`<expr>` and the following :eql:synopsis:`filter`,
+    :eql:synopsis:`order by`, :eql:synopsis:`offset`, and
+    :eql:synopsis:`limit` clauses shape the set to
+    be deleted the same way an explicit :eql:stmt:`select` would.
+
+On successful completion, a ``delete`` statement returns the set
+of deleted objects.
+
+Examples
+^^^^^^^^
+
+Here's a simple example of deleting a specific user:
+
+.. code-block:: edgeql
+
+    with module example
+    delete User
+    filter User.name = 'Alice Smith';
+
+And here's the equivalent ``delete (select ...)`` statement:
+
+.. code-block:: edgeql
+
+    with module example
+    delete (select User
+            filter User.name = 'Alice Smith');
+
+
 .. list-table::
   :class: seealso
 
   * - **See also**
-  * - :ref:`Reference > Commands > Delete <ref_eql_statements_delete>`
   * - :ref:`Cheatsheets > Deleting data <ref_cheatsheet_delete>`

docs/reference/edgeql/index.rst

@@ -25,6 +25,7 @@ EdgeQL
     analyze
     path_resolution
     transactions
+    session
 
 EdgeQL is a next-generation query language designed to match SQL in power and
 surpass it in terms of clarity, brevity, and intuitiveness. It's used to query

docs/reference/edgeql/insert.rst

@@ -3,10 +3,14 @@
 Insert
 ======
 
+:eql-statement:
+:eql-haswith:
+
 .. api-index:: insert, :=
 
-The ``insert`` command is used to create instances of object types. The code
-samples on this page assume the following schema:
+``insert`` -- create a new object in a database
+
+The code samples on this page assume the following schema:
 
 .. code-block:: sdl
 
@@ -271,6 +275,7 @@ can reference earlier ones.
 
 
 .. _ref_eql_insert_conflicts:
+.. _ref_eql_statements_insert_unless:
 
 Conflicts
 ---------
@@ -453,9 +458,120 @@ using a :ref:`for loop <ref_eql_for>` to insert the objects.
   }
 
 
+.. _ref_eql_statements_insert:
+
+EdgeQL Syntax
+-------------
+
+.. eql:synopsis::
+
+    [ with <with-spec> [ ,  ... ] ]
+    insert <expression> [ <insert-shape> ]
+    [ unless conflict
+        [ on <property-expr> [ else <alternative> ] ]
+    ] ;
+
+
+Overview
+^^^^^^^^
+
+When evaluating an ``insert`` statement, *expression* is used solely to
+determine the *type* of the inserted object and is not evaluated in any
+other way.
+
+If a value for a *required* link is evaluated to an empty set, an error is
+raised.
+
+It is possible to insert multiple objects by putting the ``insert``
+into a :eql:stmt:`for` statement.
+
+See :ref:`ref_eql_forstatement` for more details.
+
+:eql:synopsis:`with`
+    Alias declarations.
+
+    The ``with`` clause allows specifying module aliases as well
+    as expression aliases that can be referenced by the :eql:stmt:`update`
+    statement.  See :ref:`ref_eql_statements_with` for more information.
+
+:eql:synopsis:`<expression>`
+    An arbitrary expression returning a set of objects to be updated.
+
+    .. eql:synopsis::
+
+        insert <expression>
+        [ "{" <link> := <insert-value-expr> [, ...]  "}" ]
+
+.. _ref_eql_statements_conflict:
+
+:eql:synopsis:`unless conflict [ on <property-expr> ]`
+    :index: unless conflict
+
+    Handler of conflicts.
+
+    This clause allows to handle specific conflicts arising during
+    execution of ``insert`` without producing an error.  If the
+    conflict arises due to exclusive constraints on the properties
+    specified by *property-expr*, then instead of failing with an
+    error the ``insert`` statement produces an empty set (or an
+    alternative result).
+
+    The exclusive constraint on ``<property-expr>`` cannot be defined on a
+    parent type.
+
+    The specified *property-expr* may be either a reference to a property (or
+    link) or a tuple of references to properties (or links).
+
+    A caveat, however, is that ``unless conflict`` will not prevent
+    conflicts caused between multiple DML operations in the same
+    query; inserting two conflicting objects (through use of ``for``
+    or simply with two ``insert`` statements) will cause a constraint
+    error.
+
+    Example:
+
+    .. code-block:: edgeql
+
+        insert User { email := 'user@example.org' }
+        unless conflict on .email
+
+    .. code-block:: edgeql
+
+        insert User { first := 'Jason', last := 'Momoa' }
+        unless conflict on (.first, .last)
+
+:eql:synopsis:`else <alternative>`
+    Alternative result in case of conflict.
+
+    This clause can only appear after ``unless conflict`` clause. Any
+    valid expression can be specified as the *alternative*. When a
+    conflict arises, the result of the ``insert`` becomes the
+    *alternative* expression (instead of the default ``{}``).
+
+    In order to refer to the conflicting object in the *alternative*
+    expression, the name used in the ``insert`` must be used (see
+    the :ref:`example <ref_eql_statements_insert_unless>`.)
+
+Output
+^^^^^^
+
+The result of an ``insert`` statement used as an *expression* is a
+singleton set containing the inserted object.
+
+
+.. note::
+
+    Statements in EdgeQL represent an atomic interaction with the
+    database. From the point of view of a statement all side-effects
+    (such as database updates) happen after the statement is executed.
+    So as far as each statement is concerned, it is some purely
+    functional expression evaluated on some specific input (database
+    state).
+
+
+
 .. list-table::
   :class: seealso
 
   * - **See also**
-  * - :ref:`Reference > Commands > Insert <ref_eql_statements_insert>`
   * - :ref:`Cheatsheets > Inserting data <ref_cheatsheet_insert>`