Meet the new Lucy

The type union operator: |

Another operator related to types is |, which is used to combine them (similar to writing OR). This query for example pulling up all Person types will return true:

SELECT (SELECT Person FILTER .name = 'Lucy Westenra') IS NPC | MinorVampire | Vampire;

It returns true if the Person type selected is of type NPC, MinorVampire, or Vampire. Since both Lucy the Person and Lucy the MinorVampire match any of the three types, the return value is {true, true}.

One cool thing about the type union operator is that you can also add it to links in your schema. Let’s say for example there are other Vampire objects in the game, and one Vampire that is extremely powerful can control the other. Right now though Vampires can only control MinorVampires:

type Vampire extending Person {
  multi link slaves -> MinorVampire;
}

So to represent this change, you could just use | and add another type:

type Vampire extending Person {
  multi link slaves -> MinorVampire | Vampire;
}

We only have Count Dracula in our database as the main Vampire type so we won’t change our schema in this way, but keep this | operator in mind in case you need it.

On target delete

We’ve decided to keep the old NPC type for Lucy, because that Lucy will be in the game until September 1887. Maybe later PC types will interact with her, for example. But this might make you wonder about deleting links. What if we had chosen to delete the old type when she became a MinorVampire? Or more realistically, what if all MinorVampire types connected to a Vampire should be deleted when the vampire dies? We won’t do that for our game, but you can do it with on target delete. on target delete means “when the target is deleted”, and it goes inside {} after the link declaration. For this we have four options:

• restrict: forbids you from deleting the target object.

So if you declared MinorVampire like this:

type MinorVampire extending Person {
  link former_self -> Person {
    on target delete restrict;
  }
}

then you wouldn’t be able to delete Lucy the NPC once she was connected to Lucy the MinorVampire.

• delete source: in this case, deleting Lucy the Person (the target of the link) will automatically delete Lucy the MinorVampire (the source of the link).

• allow: this one simply lets you delete the target (this is the default setting).

• deferred restrict - forbids you from deleting the target object, unless it is no longer a target object by the end of a transaction. So this option is like restrict but with a bit more flexibility.

So if you wanted to have all the MinorVampire types automatically deleted when their Vampire dies, you would add a link from MinorVampire to the Vampire type. Then you would add on target delete delete source to this: Vampire is the target of the link, and MinorVampire is the source that gets deleted.

Now let’s look at some tips for making queries.

Using DISTINCT

DISTINCT is easy: just change SELECT to SELECT DISTINCT to get only unique results. We can see that right now there are quite a few duplicates in our Person objects if we SELECT Person.strength;. It looks something like this:

{5, 4, 4, 4, 4, 4, 10, 2, 2, 2, 2, 2, 2, 2, 7, 5}

Change it to SELECT DISTINCT Person.strength; and the output will now be {2, 4, 5, 7, 10}.

DISTINCT works by item and doesn’t unpack, so SELECT DISTINCT {[7, 8], [7, 8], [9]}; will return {[7, 8], [9]} and not {7, 8, 9}.

Getting __type__ all the time

We saw that we can use __type__ to get object types in a query, and that __type__ always has .name that shows us the type’s name (otherwise we will only get the uuid). In the same way that we can get all the names with SELECT Person.name, we can get all the type names like this:

SELECT Person.__type__ {
  name
};

It shows us all the types attached to Person so far:

{
  Object {name: 'default::Person'},
  Object {name: 'default::MinorVampire'},
  Object {name: 'default::Vampire'},
  Object {name: 'default::NPC'},
  Object {name: 'default::PC'},
  Object {name: 'default::Crewman'},
  Object {name: 'default::Sailor'},
}

Or we can use it in a regular query to return the types as well. Let’s see what types there are that have the name Lucy Westenra:

SELECT Person {
  __type__: {
    name
  },
  name
} FILTER .name = 'Lucy Westenra';

This shows us the objects that match, and of course they are NPC and MinorVampire.

{
  Object {__type__: Object {name: 'default::NPC'}, name: 'Lucy Westenra'},
  Object {__type__: Object {name: 'default::MinorVampire'}, name: 'Lucy Westenra'},
}

But there is a setting you can use to always see the type when you make a query: just type \set introspect-types on. Once you do that, you’ll always see the type name instead of just Object. Now even a simple search like this will give us the type:

SELECT Person {
  name
} FILTER .name = 'Lucy Westenra';

Here’s the output:

{default::NPC {name: 'Lucy Westenra'}, default::MinorVampire {name: 'Lucy Westenra'}}

Because it’s so convenient, from now on this book will show results as given with \set introspect-types on.

Being introspective

The word introspect we just used in \set introspect-types on is also its own keyword: INTROSPECT. Every type has the following fields that we can access: name, properties, links and target, and INTROSPECT lets us see them. Let’s give that a try and see what we get. We’ll start with this on our Ship type, which is fairly small but has all four. Here are the properties and links of Ship again so we don’t forget:

type Ship {
  property name -> str;
  multi link sailors -> Sailor;
  multi link crew -> Crewman;
}

First, here is the simplest INTROSPECT query:

SELECT (INTROSPECT Ship);

This query isn’t very useful to us but it does show how it works: it returns {'default::Ship'}. Note that INTROSPECT and the type go inside brackets; it’s sort of a SELECT expression for types that you then select again to capture.

Now let’s put name, properties and links inside the introspection:

SELECT (INTROSPECT Ship) {
  name,
  properties,
  links,
};

This gives us:

{
  schema::ObjectType {
    name: 'default::Ship',
    properties: {
      schema::Property {id: 4332bd76-0134-11eb-b20a-777e9cc80030},
      schema::Property {id: 43379841-0134-11eb-a427-dd28c7eae0ce},
    },
    links: {
      schema::Link {id: 4339bd5f-0134-11eb-bdca-21c31be0f932},
      schema::Link {id: 43360bf2-0134-11eb-b89c-a1211cb5d40e},
      schema::Link {id: 43383b6f-0134-11eb-86db-17f19f35ac2f},
    },
  },
}

Just like using SELECT on a type, if the output contains another type, property etc. we will just get an id. We will have to specify what we want there as well.

So let’s add some more to the query to get the information we want:

SELECT (INTROSPECT Ship) {
  name,
  properties: {
    name,
    target: {
      name
    }
  },
  links: {
    name,
    target: {
      name
    },
  },
};

So what this will give is:

1. The type name for Ship,

2. The properties, and their names. But we also use target, which is what a property points to (the part after the ->). For example, the target of property name -> str is std::str. And we want the target name too; without it we’ll get an output like target: schema::ScalarType {id: 00000000-0000-0000-0000-000000000100}.

3. The links and their names, and the targets to the links…and the names of their targets too.

With all that together, we get something readable and useful. The output looks like this:

{
  schema::ObjectType {
    name: 'default::Ship',
    properties: {
      schema::Property {name: 'id', target: schema::ScalarType {name: 'std::uuid'}},
      schema::Property {name: 'name', target: schema::ScalarType {name: 'std::str'}},
    },
    links: {
      schema::Link {name: 'crew', target: schema::ObjectType {name: 'default::Crewman'}},
      schema::Link {name: '__type__', target: schema::ObjectType {name: 'schema::Type'}},
      schema::Link {name: 'sailors', target: schema::ObjectType {name: 'default::Sailor'}},
    },
  },
}

This type of query seems complex but it is just built on top of adding things like {name} every time you get output that only a machine can understand.

Plus, if the query isn’t too complex (like ours), you might find it easier to read without so many new lines and indentation. Here’s the same query written that way, which looks much simpler now:

SELECT (INTROSPECT Ship) {
  name,
  properties: {name, target: {name}},
  links: {name, target: {name}},
};

Here is all our code so far up to Chapter 13.

1. How would you insert an NPC named ‘Mr. Swales’ who has visited the City called ‘York’, the Country called ‘England’, and the OtherPlace called ‘Whitby Abbey’? Try it in a single insert.

   Show answer

2. How readable is this introspect query?

   Copy

   SELECT (INTROSPECT Ship) {
     name,
     properties,
     links
   };
   

   Show answer

3. What would be the shortest way to see what links from the Vampire type?

   Show answer

4. What do you think the output of SELECT DISTINCT {1, 2} + {1, 2}; will be?

   Hint: don’t forget the Cartesian multiplication.

   Show answer

5. What do you think the output of SELECT DISTINCT {2, 2} + {2, 2}; will be?

   Show answer

Up next: An old friend returns.