@directus/api/dist/database/run-ast/README.md

Directus is a real-time API and App dashboard for managing SQL database content

# Internal RunAst Documentation

As the `runAst()` function is a crucial and complex part of Directus, this document intends to get you started by
providing a high level overview.

## AST

When a request is made through REST, GQL or WebSockets, we internally turn this request into an AST before this AST
get's translated into one or more SQL requests which are then send to the database.

On the root level of an AST is the root node which then references a list of child nodes. Each child node can be either
a primitive field (FieldNode), a relational field (M2ONode, O2MNode, A2MNode) or a function field (FunctionFieldNode).
Relational fields can also have additional children and nested queries.

### FieldNode

Describes a primitive field and is also a leaf node of the AST.

### Relational Fields

The M2ONode, O2MNode and A2MNode all will recursively call the `runAst()` function and the resulting data will then be
injected into the data of the level above.

### FunctionFieldNode

The only case where a function field node get's inserted into the ast, is for the count(o2m_relation) case, all other
functions are kept as FieldNode's with the name containing the function.

## RunAst()

The `runAst()` does translates the AST into an executable SQL request, requests the appropiate data from the database
and then returns a single or a list of items as the result.

### GetDBQuery()

The RootNode and relational fields have each their own query parameters. These parameters need to be applied to the SQL
query. This is done by the `getDBQuery()` function which internally uses `applyQuery()`.

<!-- TODO: Describe in larger detail what the GetDBQuery exactly does, i.e. why and when does it need an inner query, why does it sometimes call applyQuery() multiple times in different places -->

#### ApplyQuery()

`applyQuery()` takes the query and modifies the SQL request so that filters, sorts and all the other variants of query
parameters are applied.A special behaviour is filtering, sorting or other parameters on nested fields. To make this
possible, the `addJoin()` joins the required tables and then registers itself into the aliasMap so that the next time
the same collection should be joined, instead it will just reuse the already existing join.