edgedb · Dhghomon · Jan 3, 2024 · Jan 8, 2024 · Jan 9, 2024 · Jan 9, 2024
diff --git a/docs/guides/auth/index.rst b/docs/guides/auth/index.rst
@@ -292,7 +292,7 @@ to define access policies and make authenticated queries.
 Select your method for detailed configuration:
 
 .. toctree::
-    :maxdepth: 3
+    :maxdepth: 1
 
     built_in_ui
     email_password

diff --git a/docs/index.rst b/docs/index.rst
@@ -20,5 +20,6 @@ Welcome to the EdgeDB |version| documentation.
     stdlib/index
     clients/index
     cli/index
+    ui/index
     reference/index
     changelog/index
diff --git a/docs/ui/auth_admin.rst b/docs/ui/auth_admin.rst
@@ -0,0 +1,16 @@
+.. _ref_ui_auth_admin:
+
+==========
+Auth admin
+==========
+
+The auth page inside the EdgeDB UI allows you to set up authentication for
+your app built into the EdgeDB server. The details for setting up auth
+admin are in the :ref:`EdgeDB Auth guide <ref_guide_auth>`.
+
+.. image:: ../guides/auth/images/ui-auth.png
+    :alt: The EdgeDB local development server UI highlighting the auth admin
+          icon in the left-hand toolbar. The icon is two nested shield
+          outlines, the inner being a light pink color and the outer being
+          a light blue when selected.
+    :width: 100%
diff --git a/docs/ui/client_settings.rst b/docs/ui/client_settings.rst
@@ -0,0 +1,62 @@
+===============
+Client settings
+===============
+
+.. Note: id is written as I D in the alt text below as 'id' is pronounced
+.. by screen readers as id (rhymes with 'did').
+
+.. image:: images/client_settings.gif
+    :alt: The EdgeDB client settings dropdown bar showing a user changing
+          a client setting called implicit limit from 50 to 100. Two other
+          client settings that can be modified are displayed: allow bare
+          ddl, and allow user specified I D.
+    :width: 100%
+
+The UI exposes a number of :ref:`configuration parameters <ref_std_cfg>`
+in a dropdown bar at the top of all database dashboard screens. Clicking
+on the Client Settings button will show the bar, after which a double
+click allows you to modify them.
+
+The parameters are as follows:
+
+Globals
+-------
+
+- Nothing by default. Any globals defined in your schema will show up and
+  can be set here.
+
+Config
+------
+
+- ``allow_bare_ddl``: Whether DDL may be used outside the normal migration
+  flow. Default: ``NeverAllow``, can be set to ``AlwaysAllow``.
+  Note: This parameter accepts enum values, not booleans.
+- ``allow_user_specified_id``: Whether users are allowed to manually set the
+  'id' property. Default: ``false``.
+- ``apply_access_policies``: Whether
+  :ref:`access policies <ref_datamodel_access_policies>` will be applied
+  when running queries. Default: ``true``. When set to ``false``, access
+  policies will no longer restrict any operations they would naturally
+  restrict.
+- ``force_database_error``: A hook to force all queries to produce an error.
+  Default: ``'false'`` (note: a string ``'false'``, not a boolean). This 
+  parameter takes a ``str`` instead of a ``bool`` to allow more verbose
+  messages. The database will attempt to deserialize this ``str`` into a 
+  JSON object that must include a ``type`` (which must be an EdgeDB error
+  type name), and may also include ``message``, ``hint``, and ``details`` 
+  which can be set ad-hoc by the user. For example, the following is
+  valid input: ``'{ "type": "QueryError", "message": "Did not
+  work", "hint": "Try doing something else", "details": "Indeed, something
+  went really wrong" }'``
+- ``query_execution_timeout``: How long an individual query can run before
+  being aborted. Disabled when set to zero seconds (``<datetime>'PT0S'``),
+  which is the default.
+- ``session_idle_transaction_timeout``: How long client connections can
+  stay active while in a transaction. Disabled when set to zero seconds
+  (``<datetime>'PT0S'``). Default: 10 seconds.
+
+Query Options
+-------------
+
+- Implicit Limit (``int64``): The maximum number of results to display 
+  per query. Default: 100.
diff --git a/docs/ui/data_explorer.rst b/docs/ui/data_explorer.rst
@@ -0,0 +1,25 @@
+.. _ref_ui_data_explorer:
+
+=============
+Data explorer
+=============
+
+.. image:: images/data_explorer.png
+    :alt: The data explorer page in the EdgeDB UI. The icon is three bars
+          stacked on top of each other: blue, purple, and orange. A sample
+          query via the Data Explorer shows information about a user-defined
+          object type called a Booking.
+    :width: 100%
+
+The data explorer is similar to the UI editor in facilitating queries on
+database objects, but involves no direct query building (aside from filters,
+which by nature must be specified manually). Instead, the data explorer gives
+point-and-click access to the database's objects, including inserting
+new objects and modifying existing ones.
+
+This makes the data explorer the ideal solution for EdgeDB users without
+a technical background or new users lacking the time needed to learn the
+ins and outs of a new database. It is also useful for skilled users
+who are looking to explore the links between object types over possible
+multiple levels of depth without having to continually write new queries
+to do so.
diff --git a/docs/ui/database_dashboard.rst b/docs/ui/database_dashboard.rst
@@ -0,0 +1,22 @@
+.. _ref_db_dashboard:
+
+==================
+Database dashboard
+==================
+
+.. image:: images/database_dashboard.png
+    :alt: The database dashboard page in the EdgeDB UI. Large green buttons
+          give access to other pages such as the REPL, editor, and
+          schema viewer. The total number of objects and object types in
+          the database are displayed below, along with links to parts of the
+          EdgeDB website such as the Quickstart, Tutorial, and Easy EdgeDB
+          book.
+    :width: 100%
+
+The dashboard for each database displays the number of object types and
+total number of objects contained within.
+
+Besides this, the dashboard is simply a minimal set of buttons leading to the
+other parts of the UI (the REPL, editor, schema viewer, and data viewer),
+and some parts of the EdgeDB documentation that a new user will find
+most useful.
diff --git a/docs/ui/images/client_settings.gif b/docs/ui/images/client_settings.gif
diff --git a/docs/ui/images/data_explorer.png b/docs/ui/images/data_explorer.png
diff --git a/docs/ui/images/database_dashboard.png b/docs/ui/images/database_dashboard.png
diff --git a/docs/ui/images/query_builder.png b/docs/ui/images/query_builder.png
diff --git a/docs/ui/images/query_editor.png b/docs/ui/images/query_editor.png
diff --git a/docs/ui/images/schema_selection_dropdown.png b/docs/ui/images/schema_selection_dropdown.png
diff --git a/docs/ui/images/schema_viewer.png b/docs/ui/images/schema_viewer.png
diff --git a/docs/ui/images/stdlib_search.png b/docs/ui/images/stdlib_search.png
diff --git a/docs/ui/images/ui_home.png b/docs/ui/images/ui_home.png
diff --git a/docs/ui/images/ui_repl.png b/docs/ui/images/ui_repl.png
diff --git a/docs/ui/index.rst b/docs/ui/index.rst
@@ -0,0 +1,169 @@
+.. _ref_ui_overview:
+
+==
+UI
+==
+
+EdgeDB's UI is a beautiful, feature-rich admin panel baked directly into all 
+EdgeDB instances.
+
+The UI automatically opens in your default browser on a ``localhost`` page
+via a single command:
+
+.. code-block:: bash
+
+  $ edgedb ui
+
+Alternatively, you can print a url to paste into the browser instead of
+automatically opening the UI:
+
+.. code-block:: bash
+
+  $ edgedb ui --print-url
+
+The UI for :ref:`EdgeDB Cloud <ref_cli_edgedb_cloud>` is nearly
+identical to non-Cloud EdgeDB UI, aside from extra pages on Cloud-related
+items such as org settings, billing, and usage metrics.
+
+The command to open the EdgeDB UI is a CLI command, documented
+:ref:`here <ref_cli_edgedb_ui>`.
+
+The UI is served by default by development instances. To enable the UI on a
+production instance, use the ``--admin-ui`` option with ``edgedb-server``
+or set the ``EDGEDB_SERVER_ADMIN_UI`` :ref:`environment variable
+<ref_reference_envvar_admin_ui>` to ``enabled``.
+
+The UI has three similar pages that each allow users to query the database:
+the REPL, the editor, and the data explorer. Which one to use can generally
+be decided based on your use case.
+
+The *data explorer* offers simple point-and-click access to objects without
+needing any EdgeQL, making it the recommended for:
+
+- Outright new users to EdgeDB who lack a technical background or the time
+  to familiarize themself with EdgeQL
+- Existing users of EdgeDB looking to "walk" the database's objects without
+  needing to construct a new query each time
+- Users with a desire to double- or triple-check inserts, updates, and
+  deletions, as as the data explorer will first collect and display all user
+  changes in a double-confirm dialog before allowing an operation to proceed.
+
+.. image:: images/data_explorer.png
+    :alt: The data explorer page in the EdgeDB UI. The icon is three bars
+          stacked on top of each other: blue, purple, and orange. A sample
+          query via the Data Explorer shows information about a user-defined
+          object type called a Booking.
+    :width: 100%
+
+The Editor page's *query builder* is recommended for:
+
+- Users who are learning EdgeQL but still lacking the muscle memory to compose
+  queries on the fly,
+- Users querying objects with a large number of properties or links, as the
+  query builder displays all properties and links by default. This makes
+  visualizing an object's structure easier compared to using a command like
+  ``describe type <TypeName>`` to see its internals.
+
+.. image:: images/query_builder.png
+    :alt: The editor page in the EdgeDB UI, inside which the query builder
+          is shown as the user puts together a query to see the name property
+          for a user-defined type called Book. A filter on the object's id
+          and a limit to the number of object types returned are being set.
+          The Editor icon is a blue square resembling a pad, with an orange
+          line resembling a pencil on top.
+    :width: 100%
+
+The Editor page's *query editor* is recommended for:
+
+- Users experimenting with various raw queries who want quick visual
+  point-and-click access to past queries in order to call them up again
+  and refine them.
+
+.. image:: images/query_editor.png
+    :alt: The editor tab in the EdgeDB UI editor page, showing a query
+          appended with the analyze keyword to analyze performance. The
+          performance results show up in a graph on the right, with separate
+          colored rectangles for each link traversed by the query.
+    :width: 100%
+
+The UI's REPL is recommended for:
+
+- Users comfortable with EdgeQL.
+
+.. image:: images/ui_repl.png
+    :alt: The REPL page in the EdgeDB UI. The icon is a blue right-facing
+          angle bracket followed by an orange underscore, representing a
+          cursor awaiting user input. The output for a query on a
+          user-defined type called Person is displayed.
+    :width: 100%
+
+Additionally, users who spend a lot of time comparing raw queries may
+wish to give the CLI's REPL a try. A general rule of thumb is that the
+UI's REPL provides a slicker experience and more verbose output, while
+the CLI's REPL is a more performant tool that usually returns query results
+instantaneously.
+
+For example, the output from selecting objects of a type in the UI's REPL will
+show more information on a scalar object's type name:
+
+.. code-block:: edgeql-repl
+    :caption: CLI REPL
+
+    db> select Sailor {*};
+    default::Sailor {
+      id: f0b4aaf0-be4c-11ee-b84b-6b87ec260333,
+      cents: 0,
+      dollars: 0,
+      pence: 149,
+      pounds: 14,
+      shillings: 28,
+      total_cents: 0,
+      total_pence: 4069,
+      approx_wealth_in_pounds: 17,
+    },
+
+.. code-block:: edgeql-repl
+    :caption: UI REPL
+
+    db> select Sailor {*};
+    default::Sailor {
+      id: <uuid>'f0b4aaf0-be4c-11ee-b84b-6b87ec260333',
+      cents: <default::Money>0,
+      dollars: <default::Money>0,
+      pence: <default::Money>149,
+      pounds: <default::Money>14,
+      shillings: <default::Money>28,
+      total_cents: 0,
+      total_pence: 4069,
+      approx_wealth_in_pounds: 17,
+    },
+
+One more example of CLI vs. UI output, showing a user-defined function:
+
+.. code-block::
+    :caption: CLI REPL
+
+    'function default::get_url() ->  std::str using
+    (<std::str>\'https://geohack.toolforge.org/geohack.php?params=\');'}
+
+.. code-block::
+    :caption: UI REPL
+
+    function default::get_url() -> std::str {
+    volatility := 'Immutable';
+    using (<std::str>'https://geohack.toolforge.org/geohack.php?params=');
+    }
+
+.. toctree::
+  :maxdepth: 1
+
+  instance_dashboard
+  database_dashboard
+  client_settings
+  ui_repl
+  query_editor
+  schema_viewer
+  data_explorer
+  auth_admin
+
+`UI souce code <https://github.com/edgedb/edgedb-ui>`_
diff --git a/docs/ui/instance_dashboard.rst b/docs/ui/instance_dashboard.rst
@@ -0,0 +1,34 @@
+.. _ref_instance_dashboard:
+
+==================
+Instance dashboard
+==================
+
+.. image:: images/ui_home.png
+    :alt: The instance dashboard in the EdgeDB UI. The instance name, called
+          myinstance, is shown on the top. One button gives access to a
+          database known as edgedb, another button to create an example
+          database, and a third button allows for the creation of a
+          new database.
+    :width: 100%
+
+The instance dashboard displays one button per database inside an instance.
+New instances will contain a database called ``edgedb`` by default.
+
+A new database can be added to the current instance by clicking on
+``Create new database`` and choosing a name.
+
+The instance dashboard also includes a ``Create example database`` option for
+those new to EdgeDB. Clicking on this will create a database called
+``_example`` that contains the same schema and objects as those in the
+EdgeDB tutorial.
+
+This is the quickest way for newcomers to start interacting with a
+populated database. Take these three simple steps:
+
+- ``edgedb project init`` on the command line to start an instance,
+- ``edgedb ui`` on the command line to open the UI,
+- Clicking on ``Create example database`` to create the example database.
+
+Clicking on any of the databases on the instance dashboard will take you to its
+own dashboard.
diff --git a/docs/ui/query_editor.rst b/docs/ui/query_editor.rst
@@ -0,0 +1,43 @@
+.. _ref_ui_query_editor:
+
+============
+Query editor
+============
+
+.. image:: images/query_editor.png
+    :alt: The Editor tab in the EdgeDB UI editor page, showing a query
+          appended with the analyze keyword to analyze performance. The
+          performance results show up in a graph on the right, with separate
+          colored rectangles for each link traversed by the query.
+    :width: 100%
+
+The query editor outwardly resembles the REPL with some auto-completion
+functionality, but is most useful when paired with the ``analyze`` keyword.
+Prepending ``analyze`` to the front of any query will display a visual
+analyzer to help you understand the performance of your EdgeQL queries.
+
+Query builder
+-------------
+
+.. image:: images/query_builder.png
+    :alt: The editor tab in the EdgeDB UI, inside which the query builder
+          is shown as the user puts together a query to see the name property
+          for a user-defined type called Book. A filter on the object's id
+          and a limit to the number of object types returned are being set.
+          The Editor icon is a blue square resembling a pad, with an orange
+          line resembling a pencil on top.
+    :width: 100%
+
+The visual query builder (not to be confused with our `TypeScript query builder
+</docs/clients/js/querybuilder>`_) is by far the easiest way for new users to
+EdgeDB to put together a ``select`` query. It is an entirely point-and-click
+interface that walks you through the steps of a ``select`` query, including
+selecting properties and links inside an object, ``filter``, ``order by``, and
+setting an ``offset`` and ``limit`` (the maximum number of items to return from
+a query).
+
+History
+-------
+
+The History button inside the Editor tab pulls up the most recently used
+queries for both the query editor and query builder.