From de44347229b5a8f6a3202e69fb1914d7ce8c3c5d Mon Sep 17 00:00:00 2001 From: Scott Trinh Date: Wed, 4 Dec 2024 13:53:31 -0500 Subject: [PATCH] Doc fixes from quickstart (#1142) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Had some feedback about some friction in the quickstart flow, so I went through it myself again and found lots of small things we can do to improve some of this. There are larger changes we should consider as well, but this seems like a good low-effort/high-value start. Especially egregious is that we were using the `Movie` type, but not selecting the full shape that fits that interface! 😱 --- docs/index.rst | 164 ++++++++++++++++++++++++++++++------------------- 1 file changed, 100 insertions(+), 64 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index fa3de5a68..382e73e77 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -107,21 +107,22 @@ a working EdgeDB project. Let's update the schema to make the ``title`` property of the ``Movie`` type exclusive. This will help with filtering by ``Movie.title`` in our queries. -.. code-block:: sdl +.. code-block:: sdl-diff :caption: dbschema/default.esdl - module default { - type Movie { - required title: str { - constraint exclusive; - }; - multi actors: Person; - } + module default { + type Person { + required name: str; + } - type Person { - required name: str; + type Movie { + - required title: str; + + required title: str { + + constraint exclusive; + + }; + multi actors: Person; + } } - } Generate the new migration and apply them: @@ -209,8 +210,10 @@ Iron Man 2: async function main() { const result = await client.querySingle(` select Movie { + id, title, actors: { + id, name, } } filter .title = "Iron Man 2" @@ -240,29 +243,32 @@ equivalent TypeScript interfaces. Now we can annotate our query since we are selecting the whole ``Movie`` type: -.. code-block:: typescript +.. code-block:: typescript-diff :caption: query.ts - import * as edgedb from "edgedb"; - import { Movie } from "./dbschema/interfaces" - - const client = edgedb.createClient(); - - async function main() { - // result will be inferred as Movie | null - const result = await client.querySingle(` - select Movie { - title, - actors: { - name, - } - } filter .title = "Iron Man 2" - `); + import * as edgedb from "edgedb"; + import { Movie } from "./dbschema/interfaces" + + const client = edgedb.createClient(); + + async function main() { + // result will be inferred as Movie | null + - const result = await client.querySingle(` + + const result = await client.querySingle(` + select Movie { + id, + title, + actors: { + id, + name, + } + } filter .title = "Iron Man 2" + `); - console.log(JSON.stringify(result, null, 2)); - } + console.log(JSON.stringify(result, null, 2)); + } - main(); + main(); You can now run the script with ``tsx``: @@ -278,8 +284,23 @@ function that we could call? Good news, that's exactly what the next generator does! The :ref:`queries generator ` scans your project for ``*.edgeql`` files and generates a file containing a strongly-typed function. -First, move the query into a separate file called ``getMovie.edgeql``. Next, -we'll run the ``queries`` generator: +First, move the query into a separate file called ``getMovie.edgeql``. + +.. code-block:: edgeql + :caption: getMovie.edgeql + + select Movie { + id, + title, + actors: { + id, + name, + } + }; + + +Next, we'll run the ``queries`` generator, specifying the ``--file`` option +which will compile all the queries it finds into a single TypeScript module: .. code-block:: bash @@ -288,22 +309,33 @@ we'll run the ``queries`` generator: Now, let's update our query script to call the generated function, which will provide us with type-safe querying. -.. code-block:: typescript +.. code-block:: typescript-diff :caption: query.ts - import * as edgedb from "edgedb"; - import { getMovie } from "./dbschema/queries" - - const client = edgedb.createClient(); - - async function main() { - // result will be inferred as Movie | null - const result = await getMovie(client); - - console.log(JSON.stringify(result, null, 2)); - } + import * as edgedb from "edgedb"; + - import { Movie } from "./dbschema/interfaces" + + import { getMovie } from "./dbschema/queries" + + const client = edgedb.createClient(); + + async function main() { + // result will be inferred as Movie | null + - const result = await client.querySingle(` + - select Movie { + - id, + - title, + - actors: { + - id, + - name, + - } + - } filter .title = "Iron Man 2" + - `); + + const result = await getMovie(client); + + console.log(JSON.stringify(result, null, 2)); + } - main(); + main(); Now, if you change the query to return different data, or take parameters, and run the queries generator again, the type of the newly generated function will @@ -338,28 +370,32 @@ First, we'll run the query builder generator: Now, we can import the generated query builder and express our query completely in TypeScript, getting editor completion, type checking, and type inferrence: -.. code-block:: typescript +.. code-block:: typescript-diff :caption: query.ts - import * as edgedb from "edgedb"; - import e from "./dbschema/edgeql-js"; - - const client = edgedb.createClient(); - - async function main() { - // result will be inferred based on the query - const result = await e - .select(e.Movie, () => ({ - title: true, - actors: () => ({ name: true }), - filter_single: { title: "Iron Man 2" }, - })) - .run(client); - - console.log(JSON.stringify(result, null, 2)); - } + import * as edgedb from "edgedb"; + - import { getMovie } from "./dbschema/queries"; + + import e from "./dbschema/edgeql-js"; + + const client = edgedb.createClient(); + + async function main() { + - // result will be inferred as Movie | null + + // result will be inferred based on the query + - const result = await getMovie(client); + + const result = await e + + .select(e.Movie, () => ({ + + id: true, + + title: true, + + actors: () => ({ id: true, name: true }), + + filter_single: { title: "Iron Man 2" }, + + })) + + .run(client); + + console.log(JSON.stringify(result, null, 2)); + } - main(); + main(); What's next ===========