diff --git a/docs/index.rst b/docs/index.rst index 63a674fe61a..41322f8c386 100644 --- 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 new file mode 100644 index 00000000000..efb0be4664d --- /dev/null +++ b/docs/ui/auth_admin.rst @@ -0,0 +1,16 @@ +.. _ref_ui_auth_admin: + +========== +Auth Admin +========== + +The Auth page inside the EdgeDB is used to set up authentication for +your app built into the EdgeDB server. The details for setting up auth +admin via are in their own guide :ref:`here `. + +.. 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 new file mode 100644 index 00000000000..87011ec6fe5 --- /dev/null +++ b/docs/ui/client_settings.rst @@ -0,0 +1,57 @@ +=============== +Client settings +=============== + +.. image:: images/client_settings.png + :alt: The EdgeDB client settings dropdown bar showing two sample settings + that can be set: apply access policies, and implicit limit. Apply + access policies is set to false, and implicit limit is set to 100. + :width: 100% + +The UI exposes a number of :ref:`configuration parameters ` +in a dropdown bar at the top of all database dashboard screens when the +Client Settings button is clicked. They can be modified by double +clicking on the bar. + +The parameters are as follows: + +Globals +------- + +- Nothing by default. Any globals defined in your schema will show up and + can be modified here. + +Config +------ + +- ``allow_bare_ddl``: Whether DDL is allowed to 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 ` will be applied + when running queries. Default: ``true``. When set to ``false``, any + and all operations can be used on any object in the database. +- ``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 (``'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 + (``'PT0S'``). Default: 10 seconds. + +Query Options +------------- + +- Implicit Limit (``int64``): The maximum number of results to display + per query. Default: 100. \ No newline at end of file diff --git a/docs/ui/data_explorer.rst b/docs/ui/data_explorer.rst new file mode 100644 index 00000000000..8fb4f2e4b14 --- /dev/null +++ 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 any users of an EdgeDB +database who lack a technical background or 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 multiple object types in +possible multiple levels of depth without having to continually modify a +query to do so. \ No newline at end of file diff --git a/docs/ui/database_dashboard.rst b/docs/ui/database_dashboard.rst new file mode 100644 index 00000000000..b94a83b3abe --- /dev/null +++ b/docs/ui/database_dashboard.rst @@ -0,0 +1,22 @@ +.. _ref_ui_dashboard: + +========= +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. \ No newline at end of file diff --git a/docs/ui/editor.rst b/docs/ui/editor.rst new file mode 100644 index 00000000000..2aa58067a03 --- /dev/null +++ b/docs/ui/editor.rst @@ -0,0 +1,47 @@ +.. _ref_ui_editor: + +====== +Editor +====== + +.. image:: images/editor.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% + +Query Editor +------------ + +.. image:: images/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 is outwardly similar to the REPL besides some +auto-completion, but is most useful when paired with the ``analyze`` +keyword. Prepending ``analyze`` to the front of any query will +display a visual query analyzer to help you tweak performance on your +EdgeQL queries. + +Query Builder +------------- + +The Query Builder is by far the easiest way for new users to EdgeDB to +put together a ``select`` query, and the second easiest part of the UI +to use after the Data Explorer. The Query Builder 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. \ No newline at end of file diff --git a/docs/ui/images/client_settings.png b/docs/ui/images/client_settings.png new file mode 100644 index 00000000000..ea03efe009f Binary files /dev/null and b/docs/ui/images/client_settings.png differ diff --git a/docs/ui/images/data_explorer.png b/docs/ui/images/data_explorer.png new file mode 100644 index 00000000000..4a693786b73 Binary files /dev/null and b/docs/ui/images/data_explorer.png differ diff --git a/docs/ui/images/database_dashboard.png b/docs/ui/images/database_dashboard.png new file mode 100644 index 00000000000..0fa4c352be5 Binary files /dev/null and b/docs/ui/images/database_dashboard.png differ diff --git a/docs/ui/images/editor.png b/docs/ui/images/editor.png new file mode 100644 index 00000000000..162bf2f6bf1 Binary files /dev/null and b/docs/ui/images/editor.png differ diff --git a/docs/ui/images/query_editor.png b/docs/ui/images/query_editor.png new file mode 100644 index 00000000000..ba62e722dd1 Binary files /dev/null and b/docs/ui/images/query_editor.png differ diff --git a/docs/ui/images/schema_viewer.png b/docs/ui/images/schema_viewer.png new file mode 100644 index 00000000000..da79b7ac536 Binary files /dev/null and b/docs/ui/images/schema_viewer.png differ diff --git a/docs/ui/images/ui_home.png b/docs/ui/images/ui_home.png new file mode 100644 index 00000000000..25f211b0ffc Binary files /dev/null and b/docs/ui/images/ui_home.png differ diff --git a/docs/ui/images/ui_repl.png b/docs/ui/images/ui_repl.png new file mode 100644 index 00000000000..3d0706a72cd Binary files /dev/null and b/docs/ui/images/ui_repl.png differ diff --git a/docs/ui/index.rst b/docs/ui/index.rst new file mode 100644 index 00000000000..3440cc96858 --- /dev/null +++ b/docs/ui/index.rst @@ -0,0 +1,59 @@ +.. _ref_ui_overview: + +== +UI +== + +EdgeDB UI is a beautiful, feature-rich admin panel baked directly into all +EdgeDB 2.0+ 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 interface for :ref:`EdgeDB Cloud ` is nearly +identical to the standard 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 `. + +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 +` to ``enabled``. + +The UI has three similar pages that each allow users to query the database: +the REPL, the Editor, and the Data Explorer. + +Outright new users to EdgeDB who need to query or work with objects in a +database will find the Data Explorer tab the easiest to use, as it allows +simple point-and-click access to objects without using any EdgeQL. The next +easiest page to use is the Query Builder inside the Editor tab, which does +use EdgeQL but is also point-and-click as it walks users through every step +of a query. The REPL is the most advanced tab in the UI as it requires the +user to be able to compose queries in EdgeQL. + +.. toctree:: + :maxdepth: 1 + + ui_home + database_dashboard + client_settings + ui_repl + editor + schema_viewer + data_explorer + auth_admin + +`UI souce code `_ \ No newline at end of file diff --git a/docs/ui/schema_viewer.rst b/docs/ui/schema_viewer.rst new file mode 100644 index 00000000000..c996ce11cc8 --- /dev/null +++ b/docs/ui/schema_viewer.rst @@ -0,0 +1,64 @@ +.. _ref_ui_schema_viewer: + +============= +Schema Viewer +============= + +.. image:: images/schema_viewer.png + :alt: The Schema Viewer page in the EdgeDB UI. The icon is two small + squares of blue and orange, connected by a purple line. A small + user-defined sample schema is shown with two concrete types + called Book and Library, along with an abstract type called + HasAddress that is extended by the Library type. + :width: 100% + +The UI schema viewer allows you to see your schema either as text, graph, +or both. + +Text view +--------- + +The UI's text view is similar to what is produced in the CLI through the +``describe schema as sdl`` command, but includes inherited properties and +links. + +The schema viewer shows the user's defined schema by default under the +name ``User``, and also includes ``Stdlib`` and ``System`` as a convenience. +Along with the schema viewer's built-in search function, this makes +the schema viewer often even more convenient than searching through EdgeDB's +online documentation. + +For example, a search for 'max val' immediately shows the following output: + +.. code-block:: sdl + + abstract constraint std::max_value(max: anytype) { + using ((__subject__ <= max)); + } errmessage := + 'Maximum allowed value for {__subject__} is {max}.'; + annotation std::description := + 'Specifies the maximum value for the subject.'; + ; + + abstract constraint std::max_ex_value(max: anytype) { + using ((__subject__ < max)); + } errmessage := + '{__subject__} must be less than {max}.'; + annotation std::description := + 'Specifies the maximum value (as an open interval) for the subject.'; + ; + + abstract constraint std::max_len_value(max: std::int64) on (std::len(__subject__)) { + using ((__subject__ <= max)); + } errmessage := + '{__subject__} must be no longer than {max} characters.'; + annotation std::description := + 'Specifies the maximum length of subject string representation.'; + ; + +Graph view +---------- + +- Types are shown as boxes with +- Links are shown as arrows from one type to another, with any link + properties shown tucked inside the arrow. \ No newline at end of file diff --git a/docs/ui/ui_home.rst b/docs/ui/ui_home.rst new file mode 100644 index 00000000000..c996ce11cc8 --- /dev/null +++ b/docs/ui/ui_home.rst @@ -0,0 +1,64 @@ +.. _ref_ui_schema_viewer: + +============= +Schema Viewer +============= + +.. image:: images/schema_viewer.png + :alt: The Schema Viewer page in the EdgeDB UI. The icon is two small + squares of blue and orange, connected by a purple line. A small + user-defined sample schema is shown with two concrete types + called Book and Library, along with an abstract type called + HasAddress that is extended by the Library type. + :width: 100% + +The UI schema viewer allows you to see your schema either as text, graph, +or both. + +Text view +--------- + +The UI's text view is similar to what is produced in the CLI through the +``describe schema as sdl`` command, but includes inherited properties and +links. + +The schema viewer shows the user's defined schema by default under the +name ``User``, and also includes ``Stdlib`` and ``System`` as a convenience. +Along with the schema viewer's built-in search function, this makes +the schema viewer often even more convenient than searching through EdgeDB's +online documentation. + +For example, a search for 'max val' immediately shows the following output: + +.. code-block:: sdl + + abstract constraint std::max_value(max: anytype) { + using ((__subject__ <= max)); + } errmessage := + 'Maximum allowed value for {__subject__} is {max}.'; + annotation std::description := + 'Specifies the maximum value for the subject.'; + ; + + abstract constraint std::max_ex_value(max: anytype) { + using ((__subject__ < max)); + } errmessage := + '{__subject__} must be less than {max}.'; + annotation std::description := + 'Specifies the maximum value (as an open interval) for the subject.'; + ; + + abstract constraint std::max_len_value(max: std::int64) on (std::len(__subject__)) { + using ((__subject__ <= max)); + } errmessage := + '{__subject__} must be no longer than {max} characters.'; + annotation std::description := + 'Specifies the maximum length of subject string representation.'; + ; + +Graph view +---------- + +- Types are shown as boxes with +- Links are shown as arrows from one type to another, with any link + properties shown tucked inside the arrow. \ No newline at end of file diff --git a/docs/ui/ui_repl.rst b/docs/ui/ui_repl.rst new file mode 100644 index 00000000000..862e8e49313 --- /dev/null +++ b/docs/ui/ui_repl.rst @@ -0,0 +1,26 @@ +.. _ref_ui_repl: + +==== +REPL +==== + +.. 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 a Booking Log Entry is displayed. + :width: 100% + +The REPL used in the EdgeDB UI is largely the same as the CLI REPL, +so most of the commands :ref:`here ` will pertain to the +UI REPL as well. + +Some behavior differs from that of the CLI REPL: + +- The UI REPL currently does not support transactions, +- Slash commands may differ slightly inside the CLI REPL. See the + `source code `_ for more details (note: the UI REPL + has its own ``\retro`` slash command to change the UI layout to a 1980s + classic green-on-black feel!) + +.. _slash_command: https://github.com/edgedb/edgedb-ui/blob/e1b63d9395d8ea8cfac4069811f9d6ffb0bf8a8d/shared/studio/tabs/repl/state/commands.ts#L31 \ No newline at end of file