Put more emphasis on parameterized queries in the documentation

[CodesInChaos]

As a developer I'd like to use parameterized queries as much as possible. EdgeDB's powerful support for json should allow this for pretty complex queries.

Unfortunately the documentation treats parameterized queries and variables as an afterthought. It'd be nice if you added some examples, especially for non trivial mutation scenarios,

For example the frontpage showcase for mutations is a query that hardcodes the data to be inserted:

UPDATE
  Issue
FILTER
  # Get the Issue to be updated based
  # on the name.
  Issue.title = 'Update EdgeQL examples'

SET {
  time_spent_log := (
    # Add one more LogEntry to existing
    # logs.
    Issue.time_spent_log UNION (
      INSERT
        LogEntry {
          body := 'Fix typos',
          owner := Issue.owner,
          spent_time := 5
        }
    )
  )
};

You could add a variant of this query where the query is fixed and the data to be inserted is passed as a json document like:

{
    "title":"Update EdgeQL examples",
    "log_time":[
        {
            "body":"Fix typos",
            "spent_time":5
        }
    ]
}

The tutorial has a similar example where a movie contains nested INSERTs for actors while inserting a movie. That one would also make a nice example for parameterized queries.

[1st1]

Unfortunately the documentation treats parameterized queries and variables as an afterthought. It'd be nice if you added some examples, especially for non trivial mutation scenarios,

I cannot agree more.

EdgeDB does extract constants and parametrises queries automatically, but in this isn't just the performance issue: using parametrized queries is simply more convenient to the user.

@CodesInChaos Would you be interested in submitting a PR?

[elprans]

Is there a way to extract that into the WITH statement?

We are adding support for array/tuple destructuring of JSON via a cast, so this will be possible soon:

WITH 
json_data := to_json(
  '{
    "title":"Test Title",
    "body":"Test Body",
    "authors":[
        {
            "name":"tester",
            "email":"[email protected]"
        }
    ]
  }'
),

data := (
<tuple<
    title: str,
    body: str,
    authors: array<tuple<
        name: str,
        email: str
    >>
>>json_data)

INSERT Text {
    title := data.title,
    body := data.body,
    author := (
      WITH user := data.authors[0]
      INSERT User {
        name := user.name,
        email := user.email
      }
    )
};

[elprans]

Also why does the author part work without a LIMIT 1, since it's a single link not a multi link

Hm. I get:

error: possibly more than one element returned by an expression for a computable property 'name' declared as 'single'
   ┌─ query:20:9
   │
20 │         name := <str>user["name"],
   │         ^^^^^^^^^^^^^^^^^^^^^^^^^^ error

This is because user may be a set with cardinality > 1, and so user["name"] would be also. You probably wanted to write this to iterate over the user array and insert a user for each entry:

WITH
data := to_json(
  '{
    "title":"Test Title",
    "body":"Test Body",
    "authors":[
        {
            "name":"tester",
            "email":"[email protected]"
        }
    ]
  }'
),
INSERT Text {
    title := <str>data["title"],
    body := <str>data["body"],
    author := (
      FOR user IN { array_unpack(<array<json>>data["authors"]) }
      UNION (
      INSERT User {
        name := <str>user["name"],
        email := <str>user["email"]
      } )
    )
};

And in this case I also get a correct compile error:

error: possibly more than one element returned by an expression for a computable link 'author' declared as 'single'
   ┌─ query:17:5
   │
17 │ ╭     author := (
18 │ │       FOR user IN { array_unpack(<array<json>>data["authors"]) }
19 │ │       UNION (
20 │ │       INSERT User {
21 │ │         name := <str>user["name"],
22 │ │         email := <str>user["email"]
23 │ │       } )
24 │ │     )
25 │ │ };
   │ ╰^ error

[CodesInChaos]

The tuple destructuring support looks just like what I had in mind. 👍

Will drivers in statically typed languages (like Rust) be able to pass a named tuple like that to a query directly?

[CodesInChaos]

Concerning the cardinality issue, adding FOR makes sense. However the above code successfully inserted the data for me.

{
    Object
    {
        id:<uuid>"eded9f34-cd28-11ea-85a5-cf9220004e67"
    }
}

...

{
    Object
    {
        title:'Test Title',
        body:'Test Body2',
        post_date:<std::datetime>"Thu Jul 23 2020 23:10:26 GMT+0200 (Central European Summer Time)",
        author:Object
        {
            name:'tester',
            email:'[email protected]'
        }
    }
}

and if I add a second entry to the array I get the following runtime error:

Error: duplicate key value violates unique constraint "253ce7c6-bb0d-11ea-9837-1bca77db0e16_pkey"

[elprans]

Ah. The tutorial backend is running a slightly outdated version of EdgeDB, which is why we got different outcomes. Thanks!