OmniQuery

1 - Abstract

The State of Union.

OmniQuery (OQ, or OmniQuery Language - OQL / "Ockle") is a LISP dialect for database-agnostic
querying.

2 - Contents

$3

#### 2.1.1 - Conventions

##### 2.1.1.1 - Standard Fusion LISP

OmniQuery borrows the logic and arithmetic operators of
Standard Fusion LISP.

Additionally, it also borrows the return operator, uses modified versions of certain list-related
operators, and uses the dynamic LISP
conventions.

##### 2.1.1.2 - Data

###### 2.1.1.2.1 - State

OmniQuery is, in and of itself, stateless.

###### 2.1.1.2.2 - Contexts

OmniQuery contexts are objects which act as cursors that point to specific databases and sets of
data therein.

Contexts may be serialized or expressed as literals by rendering OQL expressions which resolve to
said contexts as nested string lists.

###### 2.1.1.2.3 - Dynamic Mapping

OmniQuery represents any database it interacts with, and the contexts it uses to interact with
them, as dynamic lists. The resulting mapping is referred to as a dynamic mapped database (DMDB).

As such, when a context is returned to an external environment, its contents are returned as a
dynamic list. Usually, the returned contents are in the form JSON.

A relational database may be mapped to a dynamic list, where each table in the database is
represented as a list dynamic value in said dynamic list, the key of the value being the name of
the table and the value itself being the contents of the table.

Each element of said list shall be a dynamic list representing a row in said table, with each value
of said list being a dynamic value and representing a column in said table, the key of the value
being the name of the column, and the value itself being the value of the column, converted to a
JSON compatible types.

###### 2.1.1.2.4 - Type LISP

Type LISP is a LISP convention where a value may be assigned metadata using a list where the
operator is "type", where said value is the first argument, and where the second argument is a
dynamic list containing said metadata.

Codified conventions for the content or application of such metadata are referred to as type LISP
conventions.

##### 2.1.1.3 - Usage

###### 2.1.1.3.1 - Selectors

An OmniQuery script which returns data but does not edit data may be treated as a selector for the
returned data.

###### 2.1.1.3.2 - Subscriptions

OmniQuery subscriptions event handlers tied to specific values within a DMDB which trigger events
when said values are altered, ideally with the previous and new values being passed to said event.

OmniQuery subscriptions may be specified with OmniQuery selectors.

###### 2.1.1.3.3 - Entanglement

OmniQuery entanglement is when rules for two values in separate DMDBs are enforced to keep them
aligned, if not identical, when one of them is altered.

OmniQuery entanglements may be specified with OmniQuery selectors, handled by OmniQuery
subscriptions, and declared and unidirectional or bidirectional.

###### 2.1.1.3.4 - Resolvers

An OmniQuery resolver is an API endpoint which transforms an incoming query to the API into a query
to a database according to its content.

###### 2.1.1.3.5 - Streams

An OmniQuery stream is a sustained connection between data in a DMDB and an external system.

###### 2.1.1.3.6 - Agnostic Scripts

Agnostic scripts are scripts for a system which may be written in any language. As such, rather
than interacting with said system through environmental variables and functions, the scripts,
written as function bodies, return an OmniQuery script as a LISP string, which executes upon the
state of said system (said state itself represented as a DMDB), the results of which are then
passed to the same script as a dynamic list encoded in a JSON string upon its next execution.

##### 2.1.1.4 - Meta Models

Meta models are models which contextualize a disparate set of records and databases by serializing
them within, or referencing them from, a hierarchical structure.

###### 2.1.1.4.1 - Dynamic Meta Models

A dynamic list, referred to as a model list, may be used to encode the structure of a meta model,
and metadata may be assigned to a model list by embedding it in a meta dynamic list referred to as
a meta model list.

The model list should only serialize the hierarchical structure and data content of the meta model
to which it maps. A model list is not required to serialize the entirety of the meta model to which
it, though one which does is referred to as a complete model list, and one which does not is
referred to as incomplete.

The property lists assigned to values within model lists may have a value with the key "context",
which contains an OQL query which returns a context that the value corresponding to the property
list in question acts as an alias to, with any descendant of said corresponding value being nested
within said context; and may have a value with the key "properties", said value being a dynamic
list by default, which specifies the system and type properties assigned to the value corresponding
to the property list in question.

###### 2.1.1.5.2 - Dynamic OQL Queries

A dynamic OQL query is submitted as a meta model list where the property lists thereof may have an
additional value with the key "query", containing an OQL query to execute upon the resource to
which the value, corresponding to the property list in question, maps.

When executed, it shall not only execute said OQL queries, but shall also create and update the
resources to which it maps according to the structure and content declaratively specified in its
model list and property list properties. It shall then resolve to and return itself with the data
said OQL queries resolved to embedded in its model list and property list properties.

#### 2.1.2 - Operators

##### 2.1.2.1 - arguments

The arguments atom, if used in the main scope of the script, resolves to a context passed in by the
process executing the script, and if used in the scope of an isolated expression, resolves to the
value passed to said expression when said expression is invoked.

##### 2.1.2.2 - at

###### 2.1.2.2.1 - As Context

The at operator takes a context object as its first argument, with each subsequent argument being a
number or string.

For each subsequent argument, it shall be treated as an identifier for a value in the dynamic list
selected corresponding to the previous argument, with strings being keys and numbers being indices.

It shall return a context object corresponding to the dynamic list selected by the last argument.

###### 2.1.2.2.2 - As Field

If used in an expression applied to other values as part of a selection or transformation process,
the at operator shall operate largely as described above, but with the arguments atom as the first
argument, representing the value to which the expression is applied, and with the operator
returning the raw value selected by its last argument rather than a context.

##### 2.1.2.3 - access

The access operator takes a string as its first argument, and may optionally take a dynamic list as
its second argument.

The string shall specify the address of a database to be accessed, and the dynamic list, if
present, shall specify credentials for accessing said database if necessary.

It shall return a context object representing the accessed database.

##### 2.1.2.4 - append

The append operator takes a context object as its first argument, with each subsequent argument
being a dynamic list.

It shall create a value in the database, and at the location therein, corresponding to the context,
from each dynamic list.

##### 2.1.2.5 - crop

The crop operator takes a context argument as its first argument, and a number as its second. It
may also optionally have a third numerical argument.

It shall return the context modified such that its contents are trimmed to no more than the length
specified by the first numerical argument. However, if it has a third argument, said contents shall
be cropped to a subsection starting at the index specified by the second numerical argument, before
the operation is otherwise applied as specified.

##### 2.1.2.6 - focus

The focus operator takes a context argument as its first argument, with each subsequent argument
being a string.

It shall return the context modified such that all values nested within it only contain values
keyed by the specified strings.

##### 2.1.2.7 - filter

The filter operator takes a context argument as its first argument, with an expression that
evaluates to a boolean as its second argument.

It shall return the context modified such that any value nested within it is removed if the
expression, when applied to it, resolves to false.

##### 2.1.2.8 - merge

The merge operator takes two context objects, which should correspond to tables, as its first two
arguments, the first one being referred to as the left context and the second being referred to as
the right context, and an expression which resolves to a boolean as its third argument.

It returns a new context generated by performing a full outer join on the two contexts with the
expression as the join condition.

###### 2.1.2.8.1 - merge-inner

The merge-inner operator behaves similarly to the merge operator, but performs an inner join
instead of a full outer join.

###### 2.1.2.8.2 - merge-lateral

The merge-lateral operator behaves similarly to the merge operator, but performs a left outer join
instead of a full outer join.

##### 2.1.2.9 - properties

The properties operator takes a context as its only argument, and returns a context containing the
system metadata corresponding to the original context. Such metadata shall, if applicable, include
data regarding the size of the latter context's content.

##### 2.1.2.10 - query

The query operator takes a list containing an OQL query as its only argument, executes the query,
and returns the contents of any context object the query returns as a dynamic list.

It may be used to embed OQL in other LISP dialects.

###### 2.1.2.10.1 - query-meta

The query-meta operator behaves similarly to the query operator, but instead takes a dynamic list
containing a dynamic OQL query as its only argument, executes the query, and returns the resulting
meta model the query resolves to as a dynamic list.

##### 2.1.2.11 - remove

The remove operator takes a context object as its only argument, and removes all values which
correspond to the context from the database which contains them.

##### 2.1.2.12 - set

The set operator takes a context object as its first argument, and an arbitrary expression as its
second argument.

It shall transform all values which correspond to the context to the value generated by passing
them to the expression.

##### 2.1.2.13 - sort

The sort operator takes a context object as its first argument, and a dynamic list consisting of
dynamic values where every such value is a boolean as its second argument.

It shall sort contents of the context and return it, where every key in the dynamic list specifies
the key of a field to sort the contents by, with the order of the values determining sorting
priority. A value of true means ascending order and a value of false means descending order.