Project#

A query gives rows, and ordering arranges them. project shapes each row into the document that the caller needs. The caller receives that document without a second assembly step.

The examples start from Ada, Bob and Cy. They also add Grace as Ada's manager. A reference points to an existing entity, so create Grace first:

#_grace {name Grace}

The first commit returns Grace's ID, 1, in this fresh database. The next patch creates Ada, Bob and Cy with IDs 3, 4 and 5. Ada's manager references Grace:

#_ada {name    Ada
       role    engineer
       age     36
       manager {#link 1}}
#_bob {name   Bob
       role   engineer
       age    41
       mentor {#link #_ada}}
#_cy  {name Cy
       role designer
       age  29}

Root and fields#

project has root and fields members. root is an expression that gives the entity to read for each row. fields is the shape of the output, and it cannot be empty.

find    [?e]
where   [[?e name Ada]
         [?e age ?v]]
project {root   ?e
         fields {who     .name
                 boss    .manager.name
                 missing .unknown
                 info    {doubled [* ?v 2]}}}

The query selects Ada and gives one row:

[{who     Ada
  boss    Grace
  missing null
  info    {doubled 72}}]

Field kinds#

The value determines the field kind.

A path follows entity references, so .manager.name reads the name of the entity that manager refers to. A path that reaches nothing gives null instead of an error, as .unknown does above.

A nested object gives a nested document. An expression reads the row's variables, so info.doubled doubles ?v from the where clause.

Building text#

An expression field builds text with format. The template comes first, and each {} accepts the next argument.

find    [?e]
where   [[?e name Ada]
         [?e age ?v]
         [?e name ?n]]
project {root   ?e
         fields {label [format
                        '{} is {}'
                        ?n
                        ?v]}}

[{label 'Ada is 36'}]

An argument is an expression, never a path. A path reads a field only as the whole value of a field, so .name inside format gives the text .name. The query above binds ?n in where, which is how a field of the root entity reaches a template.

Names and paths#

A field name cannot be empty, and it cannot start with $. Each segment of a path must be a name, so .. and a trailing . are errors. A segment cannot use the reserved array storage prefix stardust/list/.

project {root   ?e
         fields {who .name.}}

The path .name. ends with an empty segment. .name reads that field, and .manager.name follows the reference in manager to read a field of another entity.

Result mode#

project selects positional rows when the query does not have resultMode. You can also set resultMode positional.

resultMode object and project give two shapes for one row. A query that contains both gives an error.

find       [?e]
where      [[?e name Ada]
            [?e age ?v]]
resultMode object
project    {root   ?e
            fields {who .name}}

Project and page limits#

A projected shape is not a page boundary, so project and page together are an error.

find    [?e]
where   [[?e name Ada]
         [?e age ?v]]
orderBy [?v]
page    {size 1}
project {root   ?e
         fields {who .name}}

A projection reads the current document of each entity, so project with a temporal read is also an error. Queries covers the temporal forms.

Run it#

database query · query run.