Docs: Add simple examples to Introspection > Object Types

Throughout the last couple of weeks, I have been spending some time going through the documentation and trying understand the fundamentals of SDL and EdgeQL. One part that was particularly elusive for me was figuring out how to perform a basic introspection to determine the names of properties and links that are associated with a specific object.

Here’s the Movie and Person SDL migration from the tutorial (transaction omitted):

CREATE MIGRATION movies TO {
    type Movie {
        required property title -> str;
        # the year of release
        property year -> int64;
        required link director -> Person;
        multi link cast -> Person;
    },
    type Person {
        required property first_name -> str;
        required property last_name -> str;
    },
};

Now let’s say the user wanted to query the data stored in any Movie object, but forgot the names of the links and properties. In a real-world scenario, the user could be using a preexisting database where they aren’t familiar with the schema structure. In order to determine those names, it would be very useful to know how to use a simple introspect:

 SELECT INTROSPECT Movie { 
     properties: { 
         name,
     },
     links: { 
         name,
     }, 
 } 

I think something like this would definitely be worth mentioning in the EdgeQL section of the tutorial, perhaps just after the section starting with “The above query simply returned all the Movie objects…”.

As someone primarily experienced with RDBMS with some minimal experience using document-object DBs, I had an unanswered question that bothered me for the remainder of the tutorial after seeing this example:

SELECT Movie;
{
    Object { id: <uuid>'4d0c8ddc-54d4-11e9-8c54-7776f6130e05' },
    Object { id: <uuid>'64d024dc-54d5-11e9-8c54-a3f59e1d995e' },
}

If I were entering a preexisting database or don’t recall the schema definition for a given object, how am supposed to figure out the names? I couldn’t exactly use SELECT * from table or a GUI dropdown menu to look at the schema structure. I knew that SELECT * wouldn’t be at all be suitable for EdgeQL as a strongly static language and that a GUI wasn’t a necessity, but my question was still unanswered.

As is apparent from the above examples, I later figured it out from the Introspection > Object Types section. But even the first example wasn’t immediately obvious that it was showing me what I was looking for:

WITH MODULE schema
SELECT ObjectType {
    name,
    links: {
        name,
    },
    properties: {
        name,
    },
}
FILTER .name = 'schema::ObjectType';

This example is fairly abstract and uses a filter that wouldn’t be needed if the user only wanted a specific object. This example and the one below it lead me to believe something like this would be the minimum way to figure out the properties and links for Movie:

WITH MODULE schema
SELECT ObjectType {
    name,
    links: {
        name,
    },
    properties: {
        name,
    },
}
FILTER .name = 'default::Movie';

As a result, I think it would be worthwhile to add something along the lines of my introspection example to the tutorial and perhaps a couple of additional simple examples to Introspection > Object Types. I’d be glad to open a couple of PRs to add (one for the tutorial and another for Introspection > Object Types) an example either or both sections.

[1st1]

@ambv Please take a look.

[aeros]

Changed title of the PR to reflect the modified proposal, since @elprans mentioned the introspection examples might be too advanced for the tutorial.