Skip to content

Commit

Permalink
Use reference links in md.
Browse files Browse the repository at this point in the history
  • Loading branch information
@janderland
janderland committed Nov 18, 2024
1 parent 353ac0e commit 2404666
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 43 deletions.
39 changes: 19 additions & 20 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,9 @@ <h1>FQL</h1>
Encoding</a></li>
<li><a href="#holes-schemas" id="toc-holes-schemas">Holes &amp;
Schemas</a></li>
<li><a href="#options" id="toc-options">Options</a></li>
<li><a href="#space-comments" id="toc-space-comments">Space &amp;
Comments</a></li>
<li><a href="#options" id="toc-options">Options</a></li>
<li><a href="#basic-queries" id="toc-basic-queries">Basic
Queries</a>
<ul>
Expand All @@ -63,10 +63,10 @@ <h1>FQL</h1>
<li><a href="#roadmap" id="toc-roadmap">Roadmap</a></li>
</ul>
<h1 id="overview">Overview</h1>
<p>FQL is specified as a <a
href="https://github.com/janderland/fql/blob/main/syntax.ebnf">context-free
grammar</a>. The queries look like key-values encoded using the
directory &amp; tuple layers.</p>
<p>FQL is specified as a context-free <a
href="https://github.com/janderland/fql/blob/main/syntax.ebnf">grammar</a>.
The queries look like key-values encoded using the directory &amp;
tuple layers.</p>
<pre class="language-fql query"><code>/my/directory(&quot;my&quot;,&quot;tuple&quot;)=4000</code></pre>
<p>FQL queries may define a single key-value to be written, as shown
above, or may define a set of key-values to be read, as shown
Expand Down Expand Up @@ -176,10 +176,10 @@ <h1 id="data-elements">Data Elements</h1>
between <code>-1.18e4932</code> and <code>1.18e4932</code>, and may
use scientific notation. The type may also be instantiated as the
tokens <code>-inf</code>, <code>inf</code>, <code>-nan</code>, or
<code>nan</code>. The element is represented as an 80-bit <a
href="https://en.wikipedia.org/wiki/Extended_precision#x86_extended_precision_format">extended
double floating-point</a> and will snap to the nearest representable
number.</p>
<code>nan</code>. The element is represented as an 80-bit extended
double <a
href="https://en.wikipedia.org/wiki/Extended_precision#x86_extended_precision_format">floating-point</a>
and will snap to the nearest representable number.</p>
<pre class="language-fql query"><code>/float(-inf,nan)=1.234e4732</code></pre>
<p>The <code>str</code> type is the only element type allowed in
directory paths. If a directory string only contains alphanumericals,
Expand Down Expand Up @@ -297,8 +297,6 @@ <h1 id="holes-schemas">Holes &amp; Schemas</h1>
<p>❓ Currently, the <code>...</code> token is only allowed as the
last element of a tuple. This will be revisited in the future.</p>
</blockquote>
<h1 id="options">Options</h1>
<p>TODO: Write this section.</p>
<h1 id="space-comments">Space &amp; Comments</h1>
<p>Whitespace and newlines are allowed within a tuple, between its
elements.</p>
Expand All @@ -315,6 +313,8 @@ <h1 id="space-comments">Space &amp; Comments</h1>
&lt;int&gt;, % account ID
&lt;str&gt;, % account name
)=&lt;int&gt; % balance in USD</code></pre>
<h1 id="options">Options</h1>
<p>TODO: Write this section.</p>
<h1 id="basic-queries">Basic Queries</h1>
<p>FQL queries can mutate a single key-value, read one or more
key-values, or list directories. Throughout this section, snippets of
Expand Down Expand Up @@ -558,10 +558,8 @@ <h2 id="filtering">Filtering</h2>
return results, nil
})</code></pre>
<h1 id="advanced-queries">Advanced Queries</h1>
<p>Besides basic <a
href="https://en.wikipedia.org/wiki/Create,_read,_update_and_delete">CRUD</a>
operations, FQL is capable of performing indirection and aggregation
queries.</p>
<p>Besides basic CRUD operations, FQL is capable of performing
indirection and aggregation queries.</p>
<h2 id="indirection">Indirection</h2>
<blockquote>
<p>🚧 Indirection is still being implemented.</p>
Expand Down Expand Up @@ -605,10 +603,11 @@ <h2 id="aggregation">Aggregation</h2>
</blockquote>
<p>Aggregation queries read multiple key-values and combine them into
a single output key-value.</p>
<p>Foundation DB performs best when key-values are kept small. When <a
href="https://apple.github.io/foundationdb/blob.html">storing large
blobs</a>, the blobs are usually split into 10 kB chunks and stored as
values. The respective keys contain the byte offset of the chunks.</p>
<p>Foundation DB performs best when key-values are kept small. When
storing large <a
href="https://apple.github.io/foundationdb/blob.html">blobs</a>, the
blobs are usually split into 10 kB chunks and stored as values. The
respective keys contain the byte offset of the chunks.</p>
<pre class="language-fql query"><code>/blob(
&quot;audio.wav&quot;, % The identifier of the blob.
&lt;offset:int&gt;, % The byte offset within the blob.
Expand Down Expand Up @@ -665,7 +664,7 @@ <h1 id="using-fql">Using FQL</h1>
exploring the data, similar to <code>psql</code> for Postgres. This
libraries powering this application are exposed as a Go API, allowing
FQL to be used as a Foundation DB <a
href="https://apple.github.io/foundationdb/layer-concept.html">layer</a>.</p>
href="https://apple.github.io/foundationdb/layer-concept.html">layer</a>;</p>
<h2 id="command-line">Command Line</h2>
<div class="language-bash">
<h3 id="headless">Headless</h3>
Expand Down
48 changes: 25 additions & 23 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,12 @@ include-before: |

# Overview

FQL is specified as a [context-free
grammar](https://github.com/janderland/fql/blob/main/syntax.ebnf).
The queries look like key-values encoded using the directory
FQL is specified as a context-free [grammar][]. The
queries look like key-values encoded using the directory
& tuple layers.

[grammar]: https://github.com/janderland/fql/blob/main/syntax.ebnf

```language-fql {.query}
/my/directory("my","tuple")=4000
```
Expand Down Expand Up @@ -123,8 +124,9 @@ a directory path.
# Data Elements

An FQL query contains instances of data elements. These
mirror the types of elements found in the [tuple
layer](https://github.com/apple/foundationdb/blob/main/design/tuple.md).
mirror the types of elements found in the [tuple layer][].

[tuple layer]: https://github.com/apple/foundationdb/blob/main/design/tuple.md

<div>

Expand Down Expand Up @@ -153,9 +155,10 @@ The `num` type may be instantiated as any real number
between `-1.18e4932` and `1.18e4932`, and may use scientific
notation. The type may also be instantiated as the tokens
`-inf`, `inf`, `-nan`, or `nan`. The element is represented
as an 80-bit [extended double
floating-point](https://en.wikipedia.org/wiki/Extended_precision#x86_extended_precision_format)
and will snap to the nearest representable number.
as an 80-bit extended double [floating-point][] and will
snap to the nearest representable number.

[floating-point]: https://en.wikipedia.org/wiki/Extended_precision#x86_extended_precision_format

```language-fql {.query}
/float(-inf,nan)=1.234e4732
Expand Down Expand Up @@ -303,10 +306,6 @@ any type.
> ❓ Currently, the `...` token is only allowed as the last
> element of a tuple. This will be revisited in the future.

# Options

TODO: Write this section.

# Space & Comments

Whitespace and newlines are allowed within a tuple, between
Expand All @@ -332,6 +331,10 @@ line. They can be used to describe a tuple's elements.
)=<int> % balance in USD
```

# Options

TODO: Write this section.

# Basic Queries

FQL queries can mutate a single key-value, read one or more
Expand Down Expand Up @@ -642,10 +645,8 @@ db.ReadTransact(func(tr fdb.ReadTransaction) (interface{}, error) {

# Advanced Queries

Besides basic
[CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete)
operations, FQL is capable of performing indirection and
aggregation queries.
Besides basic CRUD operations, FQL is capable of performing
indirection and aggregation queries.

## Indirection

Expand Down Expand Up @@ -716,11 +717,11 @@ Aggregation queries read multiple key-values and combine
them into a single output key-value.

Foundation DB performs best when key-values are kept small.
When [storing large
blobs](https://apple.github.io/foundationdb/blob.html), the
blobs are usually split into 10 kB chunks and stored as
values. The respective keys contain the byte offset of the
chunks.
When storing large [blobs][], the blobs are usually split
into 10 kB chunks and stored as values. The respective keys
contain the byte offset of the chunks.

[blobs]: https://apple.github.io/foundationdb/blob.html

```language-fql {.query}
/blob(
Expand Down Expand Up @@ -774,8 +775,9 @@ The FQL project provides an application for executing
queries and exploring the data, similar to `psql` for
Postgres. This libraries powering this application are
exposed as a Go API, allowing FQL to be used as a Foundation
DB
[layer](https://apple.github.io/foundationdb/layer-concept.html).
DB [layer][];

[layer]: https://apple.github.io/foundationdb/layer-concept.html

## Command Line

Expand Down

0 comments on commit 2404666

Please sign in to comment.