28064dcd04a03bdb812b26615eaee097bc694f49 — Robbie Straw 7 years ago c2b6edf
add readme for aqua-query
1 files changed, 75 insertions(+), 0 deletions(-)

A aqua-query/README.mdown
A aqua-query/README.mdown => aqua-query/README.mdown +75 -0
@@ 0,0 1,75 @@
##  `aqua-query` 
### a simple frontend for querying the aqua database.

**DISCLAIMER** This software generates SQL queries with no regards for
sanitizing input. As such it should not (yet) be exposed to untrusted
clients. Use at your own risk.

It will totally bork your aqua database if you have tags that happen to
look like SQL injection attacks. ;-P

### Description

This is a simple frontend that supports the following input:

- Operators
  - `+`: resolves to the intersection of the left & right tags.
  - `-`: resolves to the set difference of the left & right tags.
  - `*`: resolves to the union of the left & right tags.


    grouping ::= (expr, ...)
    expr ::= <tag name>
         ||= <grouping>
         ||= <expr> <OP> <expr>

Consider the following example:

    ((dank + memes) * reaction images) - gif

This would return the following:

- all entries with BOTH `<dank>` and `<memes>` tags
- OR any entry with the `reaction images` tag.
- BUT any `gif`s will be removed from the results

### Precedence

Queries are parsed *however* they obey the precedence rules specified by
aqua's underlying database, PostgreSQL. As such union & difference operations
have the same precedence, but intersections bind more tightly.

This means that a query such as:

    a * b + c - d

Is actually processed as:

    a * (b + c) - d


    (a * b) + (c - d)

If you wish to resolve such ambiguities when mixing intersections with
other queries you must manually apply groupings.

### Input

This library can be called from rust, alternatively functions suitable
for use with C strings (`char *`) are provided. As such this can be linked
from other programs and used to parse queries.


### Output

The output is a query which will select (distinct) entry record IDs from
the `entries_tags` mapping table. These IDs can be used as a subquery or
join to fetch the entries themselves.

_At present tag input is UNESCAPED meaning if it contains single quotes
or other special characters the database query engine will process them
literally. Use this query generator at your own risk._