From 9b404d739ebfc7fb038b06c64d718c7d67fd503e Mon Sep 17 00:00:00 2001 From: Jon Anderson Date: Mon, 28 Oct 2024 00:30:53 -0700 Subject: [PATCH] More writing (#215) * Added more stuff. * Image styling. Directory queries. * Make all Go code have same background color. * Fix lone tuple rendering. * Added a lot of features to the highlighting. --- docs/css/style.css | 14 +++++- docs/index.html | 75 +++++++++++++++++++++++++---- docs/index.md | 83 ++++++++++++++++++++++++++++++--- docs/js/fql.js | 114 +++++++++++++++++++++++++++++++++++++++------ 4 files changed, 256 insertions(+), 30 deletions(-) diff --git a/docs/css/style.css b/docs/css/style.css index 3e42b745..f44ceac2 100644 --- a/docs/css/style.css +++ b/docs/css/style.css @@ -77,6 +77,13 @@ a:hover { color: var(--colorA); } +/* Images */ + +img { + border-radius: 0.5rem; + width: 100%; +} + /* Callouts */ blockquote { @@ -134,6 +141,12 @@ pre.query, pre.lang-go { } } +pre.result, pre.lang-go { + code { + background-color: var(--color0); + } +} + pre.result, pre.equiv-go { z-index: 0; @@ -144,7 +157,6 @@ pre.result, pre.equiv-go { code { margin-top: -3rem; - background-color: var(--color0); padding: 2.5rem 1rem 0.5rem 1rem; } } diff --git a/docs/index.html b/docs/index.html index ffdddf06..de66af34 100644 --- a/docs/index.html +++ b/docs/index.html @@ -43,6 +43,7 @@

FQL

  • Advanced @@ -53,15 +54,14 @@

    FQL

  • Using FQL
    • -
  • Project - Roadmap
    • +
  • Roadmap

    • Overview

    FQL is specified as a Mutations return nil, nil })

    Reads

    -

    TODO: Make sure all reads use ReadTransact().

    Queries containing a variable or the ... token read one or more key-values. The query defines a schema which the returned key-values must conform to.

    @@ -336,7 +335,7 @@

    Reads

    queries.

    /my/dir(99.8,7dfb10d1-2493-4fb5-928e-889fdc6a7136)=<int|str>
    - 
    db.Transact(func(tr fdb.Transaction) (interface{}, error) {
+  
    db.ReadTransact(func(tr fdb.ReadTransaction) (interface{}, error) {
   dir, err := directory.Open(tr, []string{"my", "dir"}, nil)
   if err != nil {
     if errors.Is(err, directory.ErrDirNotExists) {
@@ -367,7 +366,7 @@ 
    Reads
    
   
    If the value is specified as an empty variable, then the raw bytes
   are returned.
    
   
    /some/data(10139)=<>
    
-  
    db.Transact(func(tr fdb.Transaction) (interface{}, error) {
+  
    db.ReadTransact(func(tr fdb.ReadTransaction) (interface{}, error) {
   dir, err := directory.Open(tr, []string{"some", "data"}, nil)
   if err != nil {
     if errors.Is(err, directory.ErrDirNotExists) {
@@ -411,6 +410,37 @@ 
    Reads
    
   }
   return results, nil
 })
    
+  
    Directories
    
+  
    The directory layer may be queried in isolation by using a lone
+  directory as a query. These queries can only perform reads. If the
+  directory path contains no variables, the query will read that single
+  directory.
    
+  
    /root/<>/items
    
+  
     root, err := directory.Open(tr, []string{"root"}, nil)
+  if err != nil {
+    if errors.Is(err, directory.ErrDirNotExists) {
+      return nil, nil
+    }
+    return nil, err
+  }
+
+  oneDeep, err := root.List(tr, nil)
+  if err != nil {
+    return nil, err
+  }
+
+  var results [][]string
+  for _, dir1 := range oneDeep {
+    twoDeep, err := root.List(tr, []string{dir1, "items"})
+    if err != nil {
+      return nil, err
+    }
+
+    for _, dir2 := range twoDeep {
+      results = append(results, []string{"root", dir1, dir2})
+    }
+  }
+  return results, nil
    
   
    Filtering
    
   
    Read queries define a schema to which key-values may or may-not
   conform. In the Go snippets above, non-conformant key-values were
@@ -575,7 +605,7 @@ 
    Using FQL
    
   
    FQL can be used for exploring a Foundation DB cluster in a CLI
   environment or programmatically as a Foundation DB layer.
    
-  
    CLI
    
+  
    Command Line
    
   
    Headless
    
   
    FQL provides a CLI for performing queries from the command line. To
   execute a query in “headless” mode (without fullscreen), you can use
@@ -663,7 +693,36 @@ 
    API (Layer)
    
     panic(err)
   }
 }
    
-  
    Project Roadmap
    
+  
    Roadmap
    
+  
    By summer of 2025, I’d like to have the following items
+  completed:
    
+  
      
+  
    • Indirection & aggregation queries implemented as described
+  in this document.
      • 
+  
    • Design and document the syntax for doing the following
+  features.
      
+  
        
+  
      • Separating queries into multiple transactions.
        • 
+  
      • Set options at both the query & transaction level. Options
+  control things like range-read direction & limits, endianness of
+  values, and whether write queries are allowed.
        • 
+  
      • Meta language for aliasing queries or parts of queries. This
+  language would provide type-safe templating with the goal of reducing
+  repetition in a query file.
        • 
+  
      • 
+  
    
+  
    Looking beyond summer 2025, I’d like to focus on the TUI
+  environment:
    
+  
      
+  
    • Autocompletion and syntax highlighting.
      • 
+  
    • Query on the results of a previously run query. This would
+  allow the user to cache subspaces of data in local memory and refine
+  their search with subsequent queries.
      • 
+  
    • Mechanisms for controlling the output format. These would
+  control what is done with the key-values. They could be used to print
+  only the first element of the key’s tuple or to store all the
+  resulting key-values in a flat buffer.
      • 
+