From ed59da18ae20da626a6e429e9cc5f83d6de79098 Mon Sep 17 00:00:00 2001 From: Phil Rzewski Date: Tue, 27 Jan 2026 16:08:12 -0800 Subject: [PATCH] Consistent header styles in docs --- book/src/SUMMARY.md | 16 ++--- book/src/database/api.md | 46 ++++++++------- book/src/database/format.md | 22 +++---- book/src/dev/integrations/zeek/logs.md | 6 +- book/src/dev/libraries/go.md | 2 +- book/src/dev/libraries/intro.md | 2 +- book/src/formats/bsup.md | 58 +++++++++---------- book/src/formats/csup.md | 40 ++++++------- book/src/formats/jsup.md | 30 +++++----- book/src/formats/model.md | 22 +++---- book/src/formats/sup.md | 54 ++++++++--------- book/src/super-sql/aggregates/and.md | 11 ++-- book/src/super-sql/aggregates/any.md | 11 ++-- book/src/super-sql/aggregates/avg.md | 11 ++-- book/src/super-sql/aggregates/collect.md | 11 ++-- book/src/super-sql/aggregates/collect_map.md | 11 ++-- book/src/super-sql/aggregates/count.md | 11 ++-- book/src/super-sql/aggregates/dcount.md | 11 ++-- book/src/super-sql/aggregates/fuse.md | 11 ++-- book/src/super-sql/aggregates/intro.md | 2 +- book/src/super-sql/aggregates/max.md | 11 ++-- book/src/super-sql/aggregates/min.md | 11 ++-- book/src/super-sql/aggregates/or.md | 11 ++-- book/src/super-sql/aggregates/sum.md | 11 ++-- book/src/super-sql/aggregates/union.md | 11 ++-- book/src/super-sql/declarations/constants.md | 4 +- book/src/super-sql/declarations/functions.md | 6 +- book/src/super-sql/declarations/intro.md | 2 +- book/src/super-sql/declarations/operators.md | 10 ++-- book/src/super-sql/declarations/pragmas.md | 6 +- book/src/super-sql/declarations/queries.md | 4 +- book/src/super-sql/declarations/types.md | 4 +- book/src/super-sql/expressions/arithmetic.md | 6 +- book/src/super-sql/expressions/cast.md | 14 ++--- book/src/super-sql/expressions/comparisons.md | 4 +- book/src/super-sql/expressions/concat.md | 4 +- book/src/super-sql/expressions/conditional.md | 8 +-- book/src/super-sql/expressions/containment.md | 4 +- book/src/super-sql/expressions/dot.md | 4 +- book/src/super-sql/expressions/exists.md | 4 +- book/src/super-sql/expressions/f-strings.md | 4 +- book/src/super-sql/expressions/functions.md | 8 +-- book/src/super-sql/expressions/index.md | 6 +- book/src/super-sql/expressions/inputs.md | 4 +- book/src/super-sql/expressions/intro.md | 10 ++-- book/src/super-sql/expressions/literals.md | 2 +- book/src/super-sql/expressions/logic.md | 2 +- book/src/super-sql/expressions/slices.md | 6 +- book/src/super-sql/expressions/subqueries.md | 14 ++--- book/src/super-sql/functions/errors/error.md | 10 ++-- .../super-sql/functions/errors/has_error.md | 10 ++-- .../super-sql/functions/errors/is_error.md | 10 ++-- .../src/super-sql/functions/errors/missing.md | 10 ++-- book/src/super-sql/functions/errors/quiet.md | 10 ++-- .../super-sql/functions/generics/coalesce.md | 10 ++-- .../super-sql/functions/generics/compare.md | 10 ++-- book/src/super-sql/functions/generics/has.md | 10 ++-- book/src/super-sql/functions/generics/len.md | 10 ++-- book/src/super-sql/functions/generics/map.md | 10 ++-- .../super-sql/functions/generics/nullif.md | 10 ++-- .../src/super-sql/functions/generics/under.md | 10 ++-- book/src/super-sql/functions/intro.md | 2 +- book/src/super-sql/functions/math/abs.md | 10 ++-- book/src/super-sql/functions/math/ceil.md | 10 ++-- book/src/super-sql/functions/math/floor.md | 10 ++-- book/src/super-sql/functions/math/log.md | 10 ++-- book/src/super-sql/functions/math/pow.md | 10 ++-- book/src/super-sql/functions/math/round.md | 10 ++-- book/src/super-sql/functions/math/sqrt.md | 10 ++-- .../super-sql/functions/network/cidr_match.md | 10 ++-- .../super-sql/functions/network/network_of.md | 10 ++-- .../src/super-sql/functions/parsing/base64.md | 10 ++-- book/src/super-sql/functions/parsing/grok.md | 20 +++---- book/src/super-sql/functions/parsing/hex.md | 10 ++-- .../super-sql/functions/parsing/parse_sup.md | 10 ++-- .../super-sql/functions/parsing/parse_uri.md | 10 ++-- .../src/super-sql/functions/parsing/regexp.md | 10 ++-- .../functions/parsing/regexp_replace.md | 10 ++-- .../src/super-sql/functions/records/fields.md | 10 ++-- .../super-sql/functions/records/flatten.md | 10 ++-- .../functions/records/nest_dotted.md | 10 ++-- .../super-sql/functions/records/unflatten.md | 11 ++-- book/src/super-sql/functions/strings/grep.md | 10 ++-- book/src/super-sql/functions/strings/join.md | 10 ++-- .../functions/strings/levenshtein.md | 10 ++-- book/src/super-sql/functions/strings/lower.md | 10 ++-- .../super-sql/functions/strings/position.md | 10 ++-- .../super-sql/functions/strings/replace.md | 10 ++-- book/src/super-sql/functions/strings/split.md | 10 ++-- .../super-sql/functions/strings/substring.md | 10 ++-- book/src/super-sql/functions/strings/trim.md | 10 ++-- book/src/super-sql/functions/strings/upper.md | 10 ++-- book/src/super-sql/functions/time/bucket.md | 10 ++-- .../src/super-sql/functions/time/date_part.md | 10 ++-- book/src/super-sql/functions/time/now.md | 10 ++-- book/src/super-sql/functions/time/strftime.md | 12 ++-- book/src/super-sql/functions/types/cast.md | 10 ++-- book/src/super-sql/functions/types/is.md | 11 ++-- book/src/super-sql/functions/types/kind.md | 10 ++-- book/src/super-sql/functions/types/nameof.md | 10 ++-- .../src/super-sql/functions/types/typename.md | 10 ++-- book/src/super-sql/functions/types/typeof.md | 10 ++-- book/src/super-sql/operators/aggregate.md | 10 ++-- book/src/super-sql/operators/assert.md | 10 ++-- book/src/super-sql/operators/count.md | 10 ++-- book/src/super-sql/operators/cut.md | 10 ++-- book/src/super-sql/operators/drop.md | 10 ++-- book/src/super-sql/operators/fork.md | 11 ++-- book/src/super-sql/operators/from.md | 2 +- book/src/super-sql/operators/fuse.md | 11 ++-- book/src/super-sql/operators/head.md | 10 ++-- book/src/super-sql/operators/intro.md | 8 +-- book/src/super-sql/operators/join.md | 10 ++-- book/src/super-sql/operators/load.md | 12 ++-- book/src/super-sql/operators/pass.md | 11 ++-- book/src/super-sql/operators/put.md | 12 ++-- book/src/super-sql/operators/rename.md | 11 ++-- book/src/super-sql/operators/search.md | 26 +++++---- book/src/super-sql/operators/shapes.md | 12 ++-- book/src/super-sql/operators/skip.md | 11 ++-- book/src/super-sql/operators/sort.md | 11 ++-- book/src/super-sql/operators/switch.md | 11 ++-- book/src/super-sql/operators/tail.md | 11 ++-- book/src/super-sql/operators/top.md | 11 ++-- book/src/super-sql/operators/uniq.md | 11 ++-- book/src/super-sql/operators/unnest.md | 12 ++-- book/src/super-sql/operators/values.md | 11 ++-- book/src/super-sql/operators/where.md | 12 ++-- book/src/super-sql/queries.md | 16 ++--- book/src/super-sql/type-fusion.md | 6 +- book/src/super-sql/types/array.md | 6 +- book/src/super-sql/types/bool.md | 6 +- book/src/super-sql/types/bytes.md | 4 +- book/src/super-sql/types/enum.md | 4 +- book/src/super-sql/types/error.md | 8 +-- book/src/super-sql/types/intro.md | 2 +- book/src/super-sql/types/map.md | 6 +- book/src/super-sql/types/named.md | 4 +- book/src/super-sql/types/network.md | 4 +- book/src/super-sql/types/null.md | 4 +- book/src/super-sql/types/numbers.md | 14 ++--- book/src/super-sql/types/record.md | 8 +-- book/src/super-sql/types/set.md | 6 +- book/src/super-sql/types/string.md | 8 +-- book/src/super-sql/types/time.md | 2 +- book/src/super-sql/types/type.md | 4 +- book/src/super-sql/types/union.md | 8 +-- 147 files changed, 781 insertions(+), 745 deletions(-) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 4444973aa3..2e79c3fd02 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -91,8 +91,8 @@ - [pass](super-sql/operators/pass.md) - [put](super-sql/operators/put.md) - [rename](super-sql/operators/rename.md) - - [shapes](super-sql/operators/shapes.md) - [search](super-sql/operators/search.md) + - [shapes](super-sql/operators/shapes.md) - [skip](super-sql/operators/skip.md) - [sort](super-sql/operators/sort.md) - [switch](super-sql/operators/switch.md) @@ -115,6 +115,12 @@ - [JOIN](super-sql/sql/join.md) - [Set Operators](super-sql/sql/set-ops.md) - [Functions](super-sql/functions/intro.md) + - [Errors](super-sql/functions/errors/intro.md) + - [error](super-sql/functions/errors/error.md) + - [has_error](super-sql/functions/errors/has_error.md) + - [is_error](super-sql/functions/errors/is_error.md) + - [missing](super-sql/functions/errors/missing.md) + - [quiet](super-sql/functions/errors/quiet.md) - [Generics](super-sql/functions/generics/intro.md) - [coalesce](super-sql/functions/generics/coalesce.md) - [compare](super-sql/functions/generics/compare.md) @@ -123,12 +129,6 @@ - [map](super-sql/functions/generics/map.md) - [nullif](super-sql/functions/generics/nullif.md) - [under](super-sql/functions/generics/under.md) - - [Errors](super-sql/functions/errors/intro.md) - - [error](super-sql/functions/errors/error.md) - - [has_error](super-sql/functions/errors/has_error.md) - - [is_error](super-sql/functions/errors/is_error.md) - - [missing](super-sql/functions/errors/missing.md) - - [quiet](super-sql/functions/errors/quiet.md) - [Math](super-sql/functions/math/intro.md) - [abs](super-sql/functions/math/abs.md) - [ceil](super-sql/functions/math/ceil.md) @@ -174,8 +174,8 @@ - [is](super-sql/functions/types/is.md) - [kind](super-sql/functions/types/kind.md) - [nameof](super-sql/functions/types/nameof.md) - - [typeof](super-sql/functions/types/typeof.md) - [typename](super-sql/functions/types/typename.md) + - [typeof](super-sql/functions/types/typeof.md) - [Aggregate Functions](super-sql/aggregates/intro.md) - [and](super-sql/aggregates/and.md) - [any](super-sql/aggregates/any.md) diff --git a/book/src/database/api.md b/book/src/database/api.md index 40cc4e5c84..00a136ed0a 100644 --- a/book/src/database/api.md +++ b/book/src/database/api.md @@ -1,16 +1,16 @@ -## SuperDB API +# SuperDB API -### _Status_ +## Status >[!NOTE] > This is a brief sketch of the functionality exposed in the > SuperDB API. More detailed documentation of the API will be forthcoming. -### Endpoints +## Endpoints -#### Pools +### Pools -##### Create pool +#### Create pool Create a new lake pool. @@ -69,7 +69,7 @@ curl -X POST \ --- -##### Rename pool +#### Rename pool Change a pool's name. @@ -98,7 +98,7 @@ On success, HTTP 204 is returned with no response payload. --- -##### Delete pool +#### Delete pool Permanently delete a pool. @@ -123,7 +123,7 @@ On success, HTTP 204 is returned with no response payload. --- -##### Vacuum pool +#### Vacuum pool Free storage space by permanently removing underlying data objects that have previously been subject to a delete operation. @@ -156,9 +156,9 @@ curl -X POST \ --- -#### Branches +### Branches -##### Load Data +#### Load Data Add data to a pool and return a reference commit ID. @@ -197,7 +197,7 @@ curl -X POST \ --- -##### Get Branch +#### Get Branch Get information about a branch. @@ -229,7 +229,7 @@ curl -X GET \ --- -##### Delete Branch +#### Delete Branch Delete a branch. @@ -255,7 +255,7 @@ On success, HTTP 204 is returned with no response payload. --- -##### Delete Data +#### Delete Data Create a commit that reflects the deletion of some data in the branch. The data to delete can be specified via a list of object IDs or @@ -316,7 +316,7 @@ curl -X POST \ --- -##### Merge Branches +#### Merge Branches Create a commit with the difference of the child branch added to the selected branch. @@ -350,7 +350,7 @@ curl -X POST \ --- -##### Revert +#### Revert Create a revert commit of the specified commit. @@ -383,7 +383,9 @@ curl -X POST \ --- -### Query +### Queries + +#### Query Execute a Zed query against data in a data lake. @@ -437,7 +439,7 @@ curl -X POST \ {"type":"QueryStats","value":{"start_time":{"sec":1658193276,"ns":964207000},"update_time":{"sec":1658193276,"ns":964592000},"bytes_read":55,"bytes_matched":55,"records_read":3,"records_matched":3}} ``` -##### Query Status +#### Query Status Retrieve any runtime errors from a specific query. This endpoint only responds after the query has exited and is only available for a limited time afterwards. @@ -468,7 +470,7 @@ curl -X GET \ --- -#### Events +### Events Subscribe to an events feed, which returns an event stream in the format of [server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html). @@ -509,12 +511,12 @@ data: {"pool_id": "1sMDXpVwqxm36Rc2vfrmgizc3jz"} --- -### Media Types +## Media Types For both request and response payloads, the service supports a variety of formats. -#### Request Payloads +### Request Payloads When sending request payloads, include the MIME type of the format in the request's Content-Type header. If the Content-Type header is not specified, the @@ -526,7 +528,7 @@ determine the type automatically. The [input formats](../command/super.md#supported-formats) table describes which formats may be successfully auto-detected. -#### Response Payloads +### Response Payloads To receive successful (2xx) responses in a preferred format, include the MIME type of the format in the request's Accept HTTP header. If the Accept header is @@ -537,7 +539,7 @@ different default response format can be specified by invoking the For non-2xx responses, the content type of the response will be `application/json` or `text/plain`. -#### MIME Types +### MIME Types The following table shows the supported MIME types and where they can be used. diff --git a/book/src/database/format.md b/book/src/database/format.md index 03096f58cd..53963495aa 100644 --- a/book/src/database/format.md +++ b/book/src/database/format.md @@ -1,11 +1,11 @@ -## Database Format +# Database Format >[!NOTE] >This document is a rough draft and work in progress. We plan to >soon bring it up to date with the current implementation and maintain it >as we add new capabilities to the system. -### Introduction +## Introduction To support the client-facing SuperDB access implemented by the [`super db` command](../command/db.md), we are developing @@ -33,13 +33,13 @@ via a table virtualization layer built on top of the SuperDB model. All data and metadata in a database conforms to the super-structured data model, which materially simplifies development, test, introspection, and so forth. -### Cloud Object Model +## Cloud Object Model Every data element in a database is either of two fundamental object types: * a single-writer _immutable object_, or * a multi-writer _transaction journal_. -#### Immutable Objects +### Immutable Objects All imported data in a data pool is composed of immutable objects, which are organized around a primary data object. Each data object is composed of one or more immutable objects @@ -63,7 +63,7 @@ such an assumption). > local, small-scale deployments for test/debug workflows. Thus, for simple use cases, > the complexity of running an object-store service may be avoided. -##### Data Objects +#### Data Objects A data object is created by a single writer using a globally unique name with an embedded KSUID. @@ -104,7 +104,7 @@ processing only a subset of data. > and the in-memory CSUP representation supports random access so there is > no need to have a seek index for the vector object. -##### Commit History +#### Commit History A branch's commit history is the definitive record of the evolution of data in that pool in a transactionally consistent fashion. @@ -136,7 +136,7 @@ This log represents the definitive record of a branch's present and historical content, and accessing its complete detail can provide insights about data layout, provenance, history, and so forth. -#### Transaction Journal +### Transaction Journal State that is mutable is built upon a transaction journal of immutable collections of entries. In this way, there are no objects in the @@ -179,7 +179,7 @@ alongside the journal entry. This way, the snapshot at HEAD may be efficiently computed by locating the most recent cached snapshot and scanning forward to HEAD. -##### Journal Concurrency Control +#### Journal Concurrency Control To provide for atomic commits, a writer must be able to atomically update the HEAD of the log. There are three strategies for doing so. @@ -208,7 +208,7 @@ system and such round trips can be tens of milliseconds, another approach is to simply run a lock service as part of a cloud deployment that manages a mutex lock for each pool's journal. -##### Configuration State +#### Configuration State Configuration state describing a lake or pool is also stored in mutable objects. The database uses a commit journal to store configuration like the @@ -217,7 +217,7 @@ Here, a generic interface to a commit journal manages any configuration state simply as a key-value store of snapshots providing time travel over the configuration history. -#### Merge on Read +### Merge on Read To support _sorted scans_, data objects are store in a sorted order defined by the pool's sort key. @@ -245,7 +245,7 @@ can be produced by executing a sorted scan and rewriting the results back to the in a new commit. In addition, the objects comprising the total order do not overlap. This is just the basic LSM algorithm at work. -#### Object Naming +### Object Naming ``` / diff --git a/book/src/dev/integrations/zeek/logs.md b/book/src/dev/integrations/zeek/logs.md index 95b1745c91..4347612742 100644 --- a/book/src/dev/integrations/zeek/logs.md +++ b/book/src/dev/integrations/zeek/logs.md @@ -14,7 +14,7 @@ with [`super`](../../../command/super.md). The following example shows a TSV [`conn.log`](https://docs.zeek.org/en/master/logs/conn.html) being read via `super` and output as [Super (SUP)](../../../formats/sup.md). -#### conn.log +### conn.log ```mdtest-input conn.log #separator \x09 @@ -28,13 +28,13 @@ output as [Super (SUP)](../../../formats/sup.md). 1521911721.255387 C8Tful1TvM3Zf5x8fl 10.164.94.120 39681 10.47.3.155 3389 tcp - 0.004266 97 19 RSTR - - 0 ShADTdtr 10 730 6 342 - ``` -#### Example +### Example ```mdtest-command super -S -c 'head 1' conn.log ``` -#### Output +### Output ```mdtest-output { _path: "conn", diff --git a/book/src/dev/libraries/go.md b/book/src/dev/libraries/go.md index 4e4685b24f..fa712282e7 100644 --- a/book/src/dev/libraries/go.md +++ b/book/src/dev/libraries/go.md @@ -1,4 +1,4 @@ -## Go +# Go SuperDB is developed in Go so support for Go clients is fairly comprehensive. Documentation of exported diff --git a/book/src/dev/libraries/intro.md b/book/src/dev/libraries/intro.md index 92b2ee49b3..f817636492 100644 --- a/book/src/dev/libraries/intro.md +++ b/book/src/dev/libraries/intro.md @@ -1,4 +1,4 @@ -## Libraries +# Libraries SuperDB currently supports a small number of languages with client libraries for manipulating super-structured data and interacting diff --git a/book/src/formats/bsup.md b/book/src/formats/bsup.md index 72d60a65bf..3724d49365 100644 --- a/book/src/formats/bsup.md +++ b/book/src/formats/bsup.md @@ -1,6 +1,6 @@ -## Super Binary (BSUP) Format +# Super Binary (BSUP) Format -### 1. Introduction +## 1. Introduction Super Binary (BSUP) is an efficient, sequence-oriented serialization format for [super-structured data](model.md). @@ -38,7 +38,7 @@ input contexts into an output context and adjusting the type reference of each value in the output sequence. The values need not be traversed or otherwise rewritten to be merged in this fashion. -### 2. The BSUP Format +## 2. The BSUP Format A BSUP stream comprises a sequence of frames where each frame contains one of three types of data: @@ -149,7 +149,7 @@ then interpreted according to the `T` bits of the frame code as a * [values frame](#22-values-frame), or * [control frame](#23-control-frame). -#### 2.1 Types Frame +### 2.1 Types Frame A _types frame_ encodes a sequence of type definitions for complex types and establishes a "type ID" for each such definition. @@ -181,7 +181,7 @@ The typedef codes are defined as follows: Any references to a type ID in the body of a typedef are encoded as a `uvarint`. -##### 2.1.1 Record Typedef +#### 2.1.1 Record Typedef A record typedef creates a new type ID equal to the next stream type ID with the following structure: @@ -217,7 +217,7 @@ string data. The type ID follows the field name and is encoded as a `uvarint`. -##### 2.1.2 Array Typedef +#### 2.1.2 Array Typedef An array type is encoded as simply the type code of the elements of the array encoded as a `uvarint`: @@ -227,7 +227,7 @@ the array encoded as a `uvarint`: ---------------- ``` -##### 2.1.3 Set Typedef +#### 2.1.3 Set Typedef A set type is encoded as the type ID of the elements of the set, encoded as a `uvarint`: @@ -237,7 +237,7 @@ elements of the set, encoded as a `uvarint`: ---------------- ``` -##### 2.1.4 Map Typedef +#### 2.1.4 Map Typedef A map type is encoded as the type code of the key followed by the type code of the value. @@ -248,7 +248,7 @@ followed by the type code of the value. ``` Each `` is encoded as `uvarint`. -##### 2.1.5 Union Typedef +#### 2.1.5 Union Typedef A union typedef creates a new type ID equal to the next stream type ID with the following structure: @@ -266,7 +266,7 @@ The `` and the type IDs are all encoded as `uvarint`. `` cannot be 0. -##### 2.1.6 Enum Typedef +#### 2.1.6 Enum Typedef An enum type is encoded as a `uvarint` representing the number of symbols in the enumeration followed by the names of each symbol. @@ -279,7 +279,7 @@ in the enumeration followed by the names of each symbol. The names have the same UTF-8 format as record field names and are encoded as counted strings following the same convention as record field names. -##### 2.1.7 Error Typedef +#### 2.1.7 Error Typedef An error type is encoded as follows: ``` @@ -290,7 +290,7 @@ An error type is encoded as follows: which defines a new error type for error values that have the underlying type indicated by ``. -##### 2.1.8 Named Type Typedef +#### 2.1.8 Named Type Typedef A named type defines a new type ID that binds a name to a previously existing type ID. @@ -311,7 +311,7 @@ it is an error to define a type name that has the same name as a primitive type, and it is permissible to redefine a previously defined type name with a type that differs from the previous definition. -#### 2.2 Values Frame +### 2.2 Values Frame A _values frame_ is a sequence of values each encoded as the value's type ID, encoded as a `uvarint`, followed by its tag-encoded serialization as described below. @@ -334,7 +334,7 @@ the underlying values. This admits an efficient implementation for traversing the values, inclusive of recursive traversal of complex values, whereby the inner loop need not consult and interpret the type ID of each element. -##### 2.2.1 Tag-Encoding of Values +#### 2.2.1 Tag-Encoding of Values Each value is prefixed with a "tag" that defines: * whether it is the null value, and @@ -348,7 +348,7 @@ empty array, the empty record, etc. The tag itself is encoded as a `uvarint`. -##### 2.2.2 Tag-Encoded Body of Primitive Values +#### 2.2.2 Tag-Encoded Body of Primitive Values Following the tag encoding is the value encoded in N bytes as described above. A typed value with a `value` of length `N` is interpreted as described in the @@ -366,7 +366,7 @@ before encoding, are shifted left one bit, and the sign bit stored as bit 0. For negative numbers, the remaining bits are negated so that the upper bytes tend to be zero-filled for small integers. -##### 2.2.3 Tag-Encoded Body of Complex Values +#### 2.2.3 Tag-Encoded Body of Complex Values The body of a length-N container comprises zero or more tag-encoded values, where the values are encoded as follows: @@ -409,7 +409,7 @@ sequence of bytes encoding each tag-counted key (of the key/value pair) is lexicographically greater than that of the preceding key (of the preceding key/value pair). -#### 2.3 Control Frame +### 2.3 Control Frame A _control frame_ contains an application-defined control message. @@ -450,7 +450,7 @@ the base BSUP specification. If the encoding type is BSUP, the embedded BSUP data starts and ends a single BSUP stream independent of the outer BSUP stream. -#### 2.4 End of Stream +### 2.4 End of Stream A BSUP stream must be terminated by an end-of-stream marker. A new BSUP stream may begin immediately after an end-of-stream marker. @@ -486,7 +486,7 @@ previously defined type, the appropriate typedef control code must be re-emitted (and note that the typedef may now be assigned a different ID). -### 3. Primitive Types +## 3. Primitive Types For each BSUP primitive type, the following table describes: * its type ID, and @@ -528,7 +528,7 @@ are serialized in little-endian format. | `type` | 28 | variable | type value byte sequence [as defined below](#4-type-values) | | `null` | 29 | 0 | No value, always represents an undefined value | -### 4. Type Values +## 4. Type Values As the super data model supports first-class types and because the BSUP design goals require that value serializations cannot change across type contexts, type values @@ -542,7 +542,7 @@ serialized as a single byte. The type value of a complex type is serialized recursively according to the complex type it represents as described below. -#### 4.1 Record Type Value +### 4.1 Record Type Value A record type value has the form: ``` @@ -554,7 +554,7 @@ where `` is the number of fields in the record encoded as a `uvarint`, `` etc. are the field names encoded as in the record typedef, and each `` is a recursive encoding of a type value. -#### 4.2 Array Type Value +### 4.2 Array Type Value An array type value has the form: ``` @@ -564,7 +564,7 @@ An array type value has the form: ``` where `` is a recursive encoding of a type value. -#### 4.3 Set Type Value +### 4.3 Set Type Value A set type value has the form: ``` @@ -574,7 +574,7 @@ A set type value has the form: ``` where `` is a recursive encoding of a type value. -#### 4.4 Map Type Value +### 4.4 Map Type Value A map type value has the form: ``` @@ -584,7 +584,7 @@ A map type value has the form: ``` where `` and `` are recursive encodings of type values. -#### 4.5 Union Type Value +### 4.5 Union Type Value A union type value has the form: ``` @@ -595,7 +595,7 @@ A union type value has the form: where `` is the number of types in the union encoded as a `uvarint` and each `` is a recursive definition of a type value. -#### 4.6 Enum Type Value +### 4.6 Enum Type Value An enum type value has the form: ``` @@ -605,7 +605,7 @@ An enum type value has the form: ``` where `` and each symbol name is encoded as in an enum typedef. -#### 4.7 Error Type Value +### 4.7 Error Type Value An error type value has the form: ``` @@ -615,7 +615,7 @@ An error type value has the form: ``` where `` is the type value of the error. -#### 4.8 Named Type Type Value +### 4.8 Named Type Type Value A named type type value may appear either as a definition or a reference. When a named type is referenced, it must have been previously @@ -644,7 +644,7 @@ An named type reference has the form: It is an error for a named type reference to appear in a type value with a name that has not been previously defined according to the DFS order. -### 5. Compression Types +## 5. Compression Types This section specifies values for the `` byte of a [compressed value message block](#2-the-bsup-format) diff --git a/book/src/formats/csup.md b/book/src/formats/csup.md index be060e2db1..483aa66b95 100644 --- a/book/src/formats/csup.md +++ b/book/src/formats/csup.md @@ -1,4 +1,4 @@ -## Super Column (CSUP) Format +# Super Column (CSUP) Format > _TODO: this is out of date and needs to be updated._ @@ -15,7 +15,7 @@ a schema to be declared when writing data to a file. Instead, it exploits the nature of super-structured data: columns of data self-organize around their type structure. -### CSUP Files +## CSUP Files A CSUP file encodes a bounded, ordered sequence of values. To provide for efficient access to subsets of CSUP-encoded data (e.g., columns), @@ -28,7 +28,7 @@ together as a single CSUP entity. While the format provides much flexibility for how data is laid out, it is left to an implementation to lay out data in intelligent ways for efficient sequential read accesses of related data. -### Column Streams +## Column Streams The CSUP data abstraction is built around a collection of _column streams_. @@ -47,7 +47,7 @@ its relationship to the various column streams. For hierarchical records (i.e., records inside of records, or records inside of arrays inside of records, etc.), the reconstruction process is recursive (as described below). -### The Physical Layout +## The Physical Layout The overall layout of a CSUP file is comprised of the following sections, in this order: @@ -68,7 +68,7 @@ in a single pass. > additional passes or by writing the output to multiple files then > merging them together (or even leaving the CSUP entity as separate files). -#### The Data Section +### The Data Section The data section contains raw data values organized into _segments_, where a segment is a seek offset and byte length relative to the @@ -105,7 +105,7 @@ blobs of BSUP data. > do two passes where you store segments in separate files then merge them at close > according to an optimization plan. -#### The Reassembly Section +### The Reassembly Section The reassembly section provides the information needed to reconstruct column streams from segments, and in turn, to reconstruct the original values @@ -127,7 +127,7 @@ which uses an externally described schema (via [Thrift](https://thrift.apache.org/)) to describe analogous data structures, we simply reuse BSUP here. -##### The Super Types +#### The Super Types This reassembly stream encodes 2*N+1 values, where N is equal to the number of top-level types that are present in the encoded input. @@ -146,7 +146,7 @@ The next N+1 records contain reassembly information for each of the N super type where each record defines the column streams needed to reconstruct the original values. -##### Segment Maps +#### Segment Maps The foundation of column reconstruction is based on _segment maps_. A segment map is a list of the segments from the data area that are @@ -167,7 +167,7 @@ shorthand and refer to the concept as a "segmap". > a set of byte ranges where data is stored and must be read from *rather than* > the data itself. -##### The Super Column +#### The Super Column The first of the N+1 reassembly records defines the "super column", where this column represents the sequence of [super types](#the-super-types) of each original value, i.e., indicating @@ -186,7 +186,7 @@ the super column will compress trivially. The reassembly map appears as the next value in the reassembly section and is of type ``. -##### The Reassembly Records +#### The Reassembly Records Following the root reassembly map are N reassembly maps, one for each unique super type. @@ -222,7 +222,7 @@ Note that when decoding a column, all type information is known from the super type in question so there is no need to encode the type information again in the reassembly record. -##### Record Column +#### Record Column A `` is defined recursively in terms of the column types of its fields, i.e., other types that represent arrays, unions, or primitive types @@ -249,7 +249,7 @@ contains an empty ``). For an empty ``, there is no corresponding data stored in the data section. Since a `` is an array, an empty `` is simply the empty array value `[]`. -##### Array Column +#### Array Column An `` has the form: ``` @@ -263,7 +263,7 @@ of each array value. The `` structure is used for both arrays and sets. -##### Map Column +#### Map Column A `` has the form: ``` @@ -273,7 +273,7 @@ where * `key` encodes the column of map keys and * `value` encodes the column of map values. -##### Union Column +#### Union Column A `` has the form: ``` @@ -290,12 +290,12 @@ the tag of the union type indicating which column the value falls within. The number of times each value of `tags` appears must equal the number of values in each respective column. -##### Primitive Column +#### Primitive Column A `` is a `` that defines a column stream of primitive values. -##### Presence Columns +#### Presence Columns The presence column is logically a sequence of booleans, one for each position in the original column, indicating whether a value is null or present. @@ -308,7 +308,7 @@ then the number of values present, and so forth. These runs are then stored as `int32` values in the presence column (which may be subject to further compression based on segment compression). -#### The Trailer +### The Trailer After the reassembly section is a BSUP stream with a single record defining the "trailer" of the CSUP file. The trailer provides a magic field @@ -326,7 +326,7 @@ The trailer can be efficiently found by scanning backward from the end of the CSUP file to find a valid BSUP stream containing a single record value conforming to the above type. -### Decoding +## Decoding To decode an entire CSUP file into rows, the trailer is read to find the sizes of the sections, then the BSUP stream of the reassembly section is read, @@ -370,9 +370,9 @@ and that value is used to select the corresponding column stream `c0`, `c1`, etc. The value read is then encoded as a BSUP union value using the same tag within the union value. -### Examples +## Examples -#### Hello, world +### Hello, world Start with this [Super (SUP)](sup.md) file `hello.sup`: ``` diff --git a/book/src/formats/jsup.md b/book/src/formats/jsup.md index 8ad330399a..7d58ed2faa 100644 --- a/book/src/formats/jsup.md +++ b/book/src/formats/jsup.md @@ -1,6 +1,6 @@ -## Super JSON (JSUP) Format +# Super JSON (JSUP) Format -### 1. Introduction +## 1. Introduction The [super-structured data model](model.md) is based on richly typed records with a deterministic field order, @@ -71,7 +71,7 @@ in general have typing beyond the basics (i.e., strings, floating point numbers, objects, arrays, and booleans), SUP and its embedded type model is layered on top of regular JSON. -### 2. The Format +## 2. The Format The format for representing SUP data in JSON is called JSUP. Converting SUP, BSUP, or CSUP to JSUP and back results in a complete and @@ -87,7 +87,7 @@ represents a value and has the form: ``` The type and value fields are encoded as defined below. -#### 2.1 Type Encoding +### 2.1 Type Encoding The type encoding for a primitive type is simply its [type name](model.md#1-primitive-types) e.g., "int32" or "string". @@ -129,7 +129,7 @@ A previously defined complex type may be referred to using a reference of the fo } ``` -##### 2.1.1 Record Type +#### 2.1.1 Record Type A record type is a JSON object of the form ``` @@ -149,7 +149,7 @@ where each of the fields has the form and `` is a string defining the field name and `` is a recursively encoded type. -##### 2.1.2 Array Type +#### 2.1.2 Array Type An array type is defined by a JSON object having the form ``` @@ -161,7 +161,7 @@ An array type is defined by a JSON object having the form ``` where `` is a recursively encoded type. -##### 2.1.3 Set Type +#### 2.1.3 Set Type A set type is defined by a JSON object having the form ``` @@ -173,7 +173,7 @@ A set type is defined by a JSON object having the form ``` where `` is a recursively encoded type. -##### 2.1.4 Map Type +#### 2.1.4 Map Type A map type is defined by a JSON object of the form ``` @@ -186,7 +186,7 @@ A map type is defined by a JSON object of the form ``` where each `` is a recursively encoded type. -##### 2.1.5 Union type +#### 2.1.5 Union type A union type is defined by a JSON object having the form ``` @@ -199,7 +199,7 @@ A union type is defined by a JSON object having the form where the list of types comprise the types of the union and and each ``is a recursively encoded type. -##### 2.1.6 Enum Type +#### 2.1.6 Enum Type An enum type is a JSON object of the form ``` @@ -211,7 +211,7 @@ An enum type is a JSON object of the form ``` where the unique `` values define a finite set of symbols. -##### 2.1.7 Error Type +#### 2.1.7 Error Type An error type is a JSON object of the form ``` @@ -223,7 +223,7 @@ An error type is a JSON object of the form ``` where `` is a recursively encoded type. -##### 2.1.8 Named Type +#### 2.1.8 Named Type A named type is encoded as a binding between a name and a type and represents a new type so named. A type definition type has the form @@ -238,7 +238,7 @@ and represents a new type so named. A type definition type has the form where `` is a JSON string representing the newly defined type name and `` is a recursively encoded type. -#### 2.2 Value Encoding +### 2.2 Value Encoding The primitive values comprising an arbitrarily complex data value are encoded as a JSON array of strings mixed with nested JSON arrays whose structure @@ -261,14 +261,14 @@ and an array of union of string, and float64 --- might have a value that looks l [ "hello, world", ["1","2","3","4"], ["1:foo", "0:10" ] ] ``` -### 3. Object Framing +## 3. Object Framing A JSUP file is composed of JSUP objects formatted as [newline delimited JSON (NDJSON)](https://en.wikipedia.org/wiki/JSON_streaming#NDJSON). e.g., the [`super`](../command/super.md) CLI command writes its JSUP output as lines of NDJSON. -### 4. Example +## 4. Example Here is an example that illustrates values of a repeated type, nesting, records, array, and union. Consider the file `input.sup`: diff --git a/book/src/formats/model.md b/book/src/formats/model.md index 6b23db979d..e192cc5efb 100644 --- a/book/src/formats/model.md +++ b/book/src/formats/model.md @@ -1,10 +1,10 @@ -## Super-structured Data Model +# Super-structured Data Model Super-structured data is a collection of one or more typed data values. Each value's type is either a "primitive type", a "complex type", the "type type", a "named type", or the "null type". -### 1. Primitive Types +## 1. Primitive Types Primitive types include signed and unsigned integers, IEEE binary and decimal floating point, string, byte sequence, Boolean, IP address, IP network, @@ -55,7 +55,7 @@ if and only if their corresponding types are uniquely equal. The _null_ type is a primitive type representing only a `null` value. A `null` value can have any type. -### 2. Complex Types +## 2. Complex Types Complex types are composed of primitive types and/or other complex types. The categories of complex types include: @@ -75,7 +75,7 @@ The type system comprises a total order: * The order of complex type categories corresponds to the order above. * For complex types of the same category, the order is defined below. -#### 2.1 Record +### 2.1 Record A record comprises an ordered set of zero or more named values called "fields". The field names must be unique in a given record @@ -101,7 +101,7 @@ The type order of two records is as follows: * the lexicographic order of the field names from left to right, * or if all the field names are the same, the type order of the field types from left to right. -#### 2.2 Array +### 2.2 Array An array is an ordered sequence of zero or more values called "elements" all conforming to the same type. @@ -116,7 +116,7 @@ two array element types. An array of mixed-type values (such a mixed-type JSON array) is representable as an array with elements of type `union`. -#### 2.3 Set +### 2.3 Set A set is an unordered sequence of zero or more values called "elements" all conforming to the same type. @@ -131,7 +131,7 @@ A set type is uniquely defined by its single element type. The type order of two sets is defined as the type order of the two set element types. -#### 2.4 Map +### 2.4 Map A map represents a list of zero or more key-value pairs, where the keys have a common type and the values have a common type. @@ -146,7 +146,7 @@ The type order of two map types is as follows: * the type order of their key types, * or if they are the same, then the order of their value types. -#### 2.5 Union +### 2.5 Union A union represents a value that may be any one of a specific enumeration of two or more unique data types that comprise its "union type". @@ -164,7 +164,7 @@ The type order of two union types is as follows: * Two union types with the same number of types are ordered according to the type order of the constituent types in left to right order. -#### 2.6 Enum +### 2.6 Enum An enum represents a symbol from a finite set of one or more unique symbols referenced by name. An enum name may be any UTF-8 string. @@ -181,13 +181,13 @@ the type order of the constituent types in left to right order. The order among enum values correponds to the order of the symbols in the enum type. Order among enum values from different types is undefined. -#### 2.7 Error +### 2.7 Error An error represents any value designated as an error. The type order of an error is the type order of the type of its contained value. -### 3. Named Type +## 3. Named Type A _named type_ is a name for a specific data type. Any value can have a named type and the named type is a distinct type diff --git a/book/src/formats/sup.md b/book/src/formats/sup.md index 61294be23a..b6e0f3cc70 100644 --- a/book/src/formats/sup.md +++ b/book/src/formats/sup.md @@ -1,6 +1,6 @@ -## Super (SUP) Format +# Super (SUP) Format -### 1. Introduction +## 1. Introduction Super (SUP) is the human-readable, text-based serialization format for [super-structured data](model.md). @@ -13,7 +13,7 @@ to establish a concrete type for every value expressed in source text. SUP is also a superset of JSON in that all JSON documents are valid SUP values. -### 2. The SUP Format +## 2. The SUP Format A SUP text is a sequence of UTF-8 characters organized either as a bounded input or an unbounded stream. @@ -27,7 +27,7 @@ All subsequent references to characters and strings in this section refer to the Unicode code points that result when the stream is decoded. If an input text includes data that is not valid UTF-8, then the text is invalid. -#### 2.1 Names +### 2.1 Names SUP _names_ encode record fields, enum symbols, and named types. A name is either an _identifier_ or a [quoted string](#231-strings). @@ -37,7 +37,7 @@ An _identifier_ is case-sensitive and can contain Unicode letters, `$`, `_`, and digits `[0-9]`, but may not start with a digit. An identifier cannot be `true`, `false`, or `null`. -#### 2.2 Type Decorators +### 2.2 Type Decorators A value may be explicitly typed by tagging it with a type decorator. The syntax for a decorator is a double-colon appended type: @@ -83,7 +83,7 @@ Note that the `=` sigil here disambiguates between the case that a new type is defined, which may override a previous definition of a different type with the same name, from the case that an existing named type is merely decorating the value. -#### 2.3 Primitive Values +### 2.3 Primitive Values The type names and format for [primitive values](model.md#1-primitive-types) is as follows: @@ -174,7 +174,7 @@ A `time` value corresponds to 64-bit Unix epoch nanoseconds and thus not all possible RFC 3339 date/time strings are valid. In addition, nanosecond epoch times overflow on April 11, 2262. -##### 2.3.1 Strings +#### 2.3.1 Strings Double-quoted `string` syntax is the same as that of JSON as described in [RFC 8259](https://tools.ietf.org/html/rfc8259#section-7). Notably, @@ -205,7 +205,7 @@ that encounters such invalid sequences in a `string` type is undefined. These escaping rules apply also to quoted field names in record values and record types as well as enum symbols. -#### 2.4 Complex Values +### 2.4 Complex Values Complex values are built from primitive values and/or other complex values and conform to the super data model's complex types: @@ -220,7 +220,7 @@ and conform to the super data model's complex types: Complex values have an implied type when their constituent values all have implied types. -##### 2.4.1 Record Value +#### 2.4.1 Record Value A record value has the form: ``` @@ -231,7 +231,7 @@ any optionally-decorated value inclusive of other records. Each name/value pair is called a _field_. There may be zero or more fields. -##### 2.4.2 Array Value +#### 2.4.2 Array Value An array value has the form: ``` @@ -243,7 +243,7 @@ the array elements is a union of the types present. An array value may be empty. An empty array value without a type decorator is presumed to be an empty array of type `null`. -##### 2.4.3 Set Value +#### 2.4.3 Set Value A set value has the form: ``` @@ -257,7 +257,7 @@ the set elements is a union of the types present. A set value may be empty. An empty set value without a type decorator is presumed to be an empty set of type `null`. -##### 2.4.4 Map Value +#### 2.4.4 Map Value A map value has the form: ``` @@ -272,13 +272,13 @@ that follows it. An empty map value without a type decorator is presumed to be an empty map of type `|{null: null}|`. -##### 2.4.5 Union Value +#### 2.4.5 Union Value A union value is a value that conforms to one of the types within a union type. If the value appears in a context in which the type is unknown or ambiguous, then the value must be decorated as [described above](#22-type-decorators). -##### 2.4.6 Enum Value +#### 2.4.6 Enum Value An enum type represents a symbol from a finite set of symbols referenced by name. @@ -301,7 +301,7 @@ A sequence of enum values might look like this: "HEADS"::flip ``` -##### 2.4.7 Error Value +#### 2.4.7 Error Value An error value has the form: ``` @@ -309,12 +309,12 @@ error() ``` where `` is any value. -#### 2.5 Types +### 2.5 Types A primitive type is simply the name of the primitive type, i.e., `string`, `uint16`, etc. Complex types are defined as follows. -##### 2.5.1 Record Type +#### 2.5.1 Record Type A _record type_ has the form: ``` @@ -326,21 +326,21 @@ where `` is a [SUP name](#21-names) and The order of the record fields is significant, e.g., type `{a:int32,b:int32}` is distinct from type `{b:int32,a:int32}`. -##### 2.5.2 Array Type +#### 2.5.2 Array Type An _array type_ has the form: ``` [ ] ``` -##### 2.5.3 Set Type +#### 2.5.3 Set Type A _set type_ has the form: ``` |[ ]| ``` -##### 2.5.4 Map Type +#### 2.5.4 Map Type A _map type_ has the form: ``` @@ -349,7 +349,7 @@ A _map type_ has the form: where `` is the type of the keys and `` is the type of the values. -##### 2.5.5 Union Type +#### 2.5.5 Union Type A _union type_ has the form: ``` @@ -357,7 +357,7 @@ A _union type_ has the form: ``` where there are at least two types in the list. -##### 2.5.6 Enum Type +#### 2.5.6 Enum Type An _enum type_ has the form: ``` @@ -367,7 +367,7 @@ where `` is a [SUP name](#21-names). Each enum name must be unique and the order is significant, e.g., enum type `enum(HEADS,TAILS)` is not equal to type `enum(TAILS,HEADS)`. -##### 2.5.7 Error Type +#### 2.5.7 Error Type An _error type_ has the form: ``` @@ -375,7 +375,7 @@ error( ) ``` where `` is the type of the underlying values wrapped as an error. -##### 2.5.8 Named Type +#### 2.5.8 Named Type A named type has the form: ``` @@ -401,13 +401,13 @@ resolve to the most recent definition according to * sequence order across values, or * left-to-right depth-first order within a complex value. -#### 2.6 Null Value +### 2.6 Null Value The null value is represented by the string `null`. A value of any type can be null. -### 3. Examples +## 3. Examples The simplest SUP value is a single value, perhaps a string like this: ``` @@ -474,7 +474,7 @@ note that the `value` field takes on different types and even a complex record type on the last line. In this case, there is a different top-level record type implied by each of the three variations of type of the `value` field. -### 4. Grammar +## 4. Grammar Here is a left-recursive pseudo-grammar of SUP. Note that not all acceptable inputs are semantically valid as type mismatches may arise. diff --git a/book/src/super-sql/aggregates/and.md b/book/src/super-sql/aggregates/and.md index 5a0ee27872..eeb7561aeb 100644 --- a/book/src/super-sql/aggregates/and.md +++ b/book/src/super-sql/aggregates/and.md @@ -1,17 +1,18 @@ -### Aggregate Function +# and -  **and** — logical AND of input values +logical AND of input values + +## Synopsis -### Synopsis ``` and(bool) -> bool ``` -### Description +## Description The _and_ aggregate function computes the logical AND over all of its input. -### Examples +## Examples Anded value of simple sequence: ```mdtest-spq diff --git a/book/src/super-sql/aggregates/any.md b/book/src/super-sql/aggregates/any.md index a38d0044d8..1f5c4da7c2 100644 --- a/book/src/super-sql/aggregates/any.md +++ b/book/src/super-sql/aggregates/any.md @@ -1,18 +1,19 @@ -### Aggregate Function +# any -  **any** — select an arbitrary input value +select an arbitrary input value + +## Synopsis -### Synopsis ``` any(any) -> any ``` -### Description +## Description The _any_ aggregate function returns an arbitrary element from its input. The semantics of how the item is selected is not defined. -### Examples +## Examples Any picks the first one in this scenario but this behavior is undefined: ```mdtest-spq diff --git a/book/src/super-sql/aggregates/avg.md b/book/src/super-sql/aggregates/avg.md index ee4930367d..0bf81a3355 100644 --- a/book/src/super-sql/aggregates/avg.md +++ b/book/src/super-sql/aggregates/avg.md @@ -1,18 +1,19 @@ -### Aggregate Function +# avg -  **avg** — average (arithmetic mean) value +average (arithmetic mean) value + +## Synopsis -### Synopsis ``` avg(number) -> number ``` -### Description +## Description The _avg_ aggregate function computes the average (arithmetic mean) value of its input. -### Examples +## Examples Average value of simple sequence: ```mdtest-spq diff --git a/book/src/super-sql/aggregates/collect.md b/book/src/super-sql/aggregates/collect.md index 4bcae2cbb3..61e338cd70 100644 --- a/book/src/super-sql/aggregates/collect.md +++ b/book/src/super-sql/aggregates/collect.md @@ -1,19 +1,20 @@ -### Aggregate Function +# collect -  **collect** — aggregate values into array +aggregate values into array + +## Synopsis -### Synopsis ``` collect(any) -> [any] ``` -### Description +## Description The _collect_ aggregate function organizes its input into an array. If the input values vary in type, the return type will be an array of union of the types encountered. -### Examples +## Examples Simple sequence collected into an array: ```mdtest-spq diff --git a/book/src/super-sql/aggregates/collect_map.md b/book/src/super-sql/aggregates/collect_map.md index 4a7aea52d3..535c3b811e 100644 --- a/book/src/super-sql/aggregates/collect_map.md +++ b/book/src/super-sql/aggregates/collect_map.md @@ -1,20 +1,21 @@ -### Aggregate Function +# collect_map -  **collect_map** — aggregate map values into a single map +aggregate map values into a single map + +## Synopsis -### Synopsis ``` collect_map(|{any:any}|) -> |{any:any}| ``` -### Description +## Description The _collect_map_ aggregate function combines map inputs into a single map output. If _collect_map_ receives multiple values for the same key, the last value received is retained. If the input keys or values vary in type, the return type will be a map of union of those types. -### Examples +## Examples Combine a sequence of records into a map: ```mdtest-spq diff --git a/book/src/super-sql/aggregates/count.md b/book/src/super-sql/aggregates/count.md index c786b9fb25..e2e7386d62 100644 --- a/book/src/super-sql/aggregates/count.md +++ b/book/src/super-sql/aggregates/count.md @@ -1,20 +1,21 @@ -### Aggregate Function +# count -  **count** — count all input values +count all input values >[!TIP] > For a running count as values arrive, see the [count](../operators/count.md) operator. -### Synopsis +## Synopsis + ``` count() -> int64 ``` -### Description +## Description The _count_ aggregate function computes the number of values in its input. -### Examples +## Examples Count of values in a simple sequence: ```mdtest-spq diff --git a/book/src/super-sql/aggregates/dcount.md b/book/src/super-sql/aggregates/dcount.md index f69ca88c24..ece3137123 100644 --- a/book/src/super-sql/aggregates/dcount.md +++ b/book/src/super-sql/aggregates/dcount.md @@ -1,18 +1,19 @@ -### Aggregate Function +# dcount -  **dcount** — count distinct input values +count distinct input values + +## Synopsis -### Synopsis ``` dcount(any) -> int64 ``` -### Description +## Description The _dcount_ aggregate function uses hyperloglog to estimate distinct values of the input in a memory efficient manner. -### Examples +## Examples Count of values in a simple sequence: ```mdtest-spq diff --git a/book/src/super-sql/aggregates/fuse.md b/book/src/super-sql/aggregates/fuse.md index 080d44212e..f5f55c4ce6 100644 --- a/book/src/super-sql/aggregates/fuse.md +++ b/book/src/super-sql/aggregates/fuse.md @@ -1,13 +1,14 @@ -### Aggregate Function +# fuse -  **fuse** — compute a fused type of input values +compute a fused type of input values + +## Synopsis -### Synopsis ``` fuse(any) -> type ``` -### Description +## Description The _fuse_ aggregate function applies [type fusion](../type-fusion.md) to its input and returns the fused type. @@ -16,7 +17,7 @@ It is useful with grouped aggregation for data exploration and discovery when searching for shaping rules to cluster a large number of varied input types to a smaller number of fused types each from a set of interrelated types. -### Examples +## Examples Fuse two records: ```mdtest-spq diff --git a/book/src/super-sql/aggregates/intro.md b/book/src/super-sql/aggregates/intro.md index 3fe8533714..ebe8b0e1d3 100644 --- a/book/src/super-sql/aggregates/intro.md +++ b/book/src/super-sql/aggregates/intro.md @@ -1,4 +1,4 @@ -## Aggregate Functions +# Aggregate Functions Aggregate functions compute aggregated results from zero or more input values and have the form diff --git a/book/src/super-sql/aggregates/max.md b/book/src/super-sql/aggregates/max.md index 5fe9bec2ab..df3ba77c05 100644 --- a/book/src/super-sql/aggregates/max.md +++ b/book/src/super-sql/aggregates/max.md @@ -1,13 +1,14 @@ -### Aggregate Function +# max -  **max** — maximum value of input values +maximum value of input values + +## Synopsis -### Synopsis ``` max(number|string) -> number|string ``` -### Description +## Description The _max_ aggregate function computes the maximum value of its input. @@ -16,7 +17,7 @@ order. This is equivalent to [C/POSIX collation](https://www.postgresql.org/docs/current/collation.html#COLLATION-MANAGING-STANDARD) as found in other SQL databases such as Postgres. -### Examples +## Examples Maximum value of simple numeric sequence: ```mdtest-spq diff --git a/book/src/super-sql/aggregates/min.md b/book/src/super-sql/aggregates/min.md index 55fa31a53b..24202bfa14 100644 --- a/book/src/super-sql/aggregates/min.md +++ b/book/src/super-sql/aggregates/min.md @@ -1,13 +1,14 @@ -### Aggregate Function +# min -  **min** — minimum value of input values +minimum value of input values + +## Synopsis -### Synopsis ``` min(number|string) -> number|string ``` -### Description +## Description The _min_ aggregate function computes the minimum value of its input. @@ -16,7 +17,7 @@ order. This is equivalent to [C/POSIX collation](https://www.postgresql.org/docs/current/collation.html#COLLATION-MANAGING-STANDARD) as found in other SQL databases such as Postgres. -### Examples +## Examples Minimum value of simple numeric sequence: ```mdtest-spq diff --git a/book/src/super-sql/aggregates/or.md b/book/src/super-sql/aggregates/or.md index a4cd752d36..3c32d05c4e 100644 --- a/book/src/super-sql/aggregates/or.md +++ b/book/src/super-sql/aggregates/or.md @@ -1,17 +1,18 @@ -### Aggregate Function +# or -  **or** — logical OR of input values +logical OR of input values + +## Synopsis -### Synopsis ``` or(bool) -> bool ``` -### Description +## Description The _or_ aggregate function computes the logical OR over all of its input. -### Examples +## Examples Ored value of simple sequence: ```mdtest-spq diff --git a/book/src/super-sql/aggregates/sum.md b/book/src/super-sql/aggregates/sum.md index 52db141742..95089f009d 100644 --- a/book/src/super-sql/aggregates/sum.md +++ b/book/src/super-sql/aggregates/sum.md @@ -1,17 +1,18 @@ -### Aggregate Function +# sum -  **sum** — sum of input values +sum of input values + +## Synopsis -### Synopsis ``` sum(number) -> number ``` -### Description +## Description The _sum_ aggregate function computes the mathematical sum of its input. -### Examples +## Examples Sum of simple sequence: ```mdtest-spq diff --git a/book/src/super-sql/aggregates/union.md b/book/src/super-sql/aggregates/union.md index 648a52e22a..621f3142e9 100644 --- a/book/src/super-sql/aggregates/union.md +++ b/book/src/super-sql/aggregates/union.md @@ -1,20 +1,21 @@ -### Aggregate Function +# union -  **union** — set union of input values +set union of input values + +## Synopsis -### Synopsis ``` union(any) -> |[any]| ``` -### Description +## Description The _union_ aggregate function computes a set union of its input values. If the values are of uniform type, then the output is a set of that type. If the values are of mixed type, the the output is a set of union of the types encountered. -### Examples +## Examples Create a set of values from a simple sequence: ```mdtest-spq diff --git a/book/src/super-sql/declarations/constants.md b/book/src/super-sql/declarations/constants.md index 510395e37f..4f7c51ec93 100644 --- a/book/src/super-sql/declarations/constants.md +++ b/book/src/super-sql/declarations/constants.md @@ -1,4 +1,4 @@ -## Constants +# Constants Constants are declared with the syntax ``` @@ -15,7 +15,7 @@ Constant declarations must appear in the declaration section of a A constant can be any expression, inclusive of subqueries and function calls, as long as the expression evaluates to a compile-time constant. -### Examples +## Examples --- diff --git a/book/src/super-sql/declarations/functions.md b/book/src/super-sql/declarations/functions.md index 249a38d316..5c04a5cac8 100644 --- a/book/src/super-sql/declarations/functions.md +++ b/book/src/super-sql/declarations/functions.md @@ -1,4 +1,4 @@ -## Functions +# Functions New functions are declared with the syntax ``` @@ -43,7 +43,7 @@ the function returns an [error](../types/error.md) value indicating so. Recursi run for an extended period of time without exceeding the stack depth will simply be allowed to run indefinitely and stall the query result. -### Subquery Functions +## Subquery Functions Since the body of a function is any expression and an expression may be a subquery, function bodies can be defined as [subqueries](../expressions/subqueries.md). @@ -97,7 +97,7 @@ values apply([1,2,3], 1) [2,3,4] ``` -### Examples +## Examples --- diff --git a/book/src/super-sql/declarations/intro.md b/book/src/super-sql/declarations/intro.md index b40b94d876..e80d487d47 100644 --- a/book/src/super-sql/declarations/intro.md +++ b/book/src/super-sql/declarations/intro.md @@ -1,4 +1,4 @@ -## Declarations +# Declarations Declarations bind a name in the form of an [identifier](../queries.md#identifiers) to various entities and may appear at the beginning of any [scope](../queries.md#scope) diff --git a/book/src/super-sql/declarations/operators.md b/book/src/super-sql/declarations/operators.md index fae9564569..d7fee1abb4 100644 --- a/book/src/super-sql/declarations/operators.md +++ b/book/src/super-sql/declarations/operators.md @@ -1,4 +1,4 @@ -## Operators +# Operators New operators are declared with the syntax ``` @@ -15,7 +15,7 @@ where Operator declarations must appear in the declaration section of a [scope](../queries.md#scope). -### Call +## Call A declared operator is invoked by its name using the [call](../operators/intro.md#call) keyword. @@ -30,14 +30,14 @@ defines how the input is processed. An operator may also source its own data by beginning the query body with a [from](../operators/from.md) operator or [SQL statement](../sql/intro.md). -### Nested Calls +## Nested Calls Operators do not support recursion. They cannot call themselves nor can they form a mutually recursive dependency loop. However, operators can call other operators whose declaration is in scope as long as no dependency loop is formed. -### Closure-like Arguments +## Closure-like Arguments In contrast to function calls, where the arguments are evaluated at the call site and values are passed to the function, operator arguments are instead passed to the @@ -54,7 +54,7 @@ The [jq](https://github.com/jqlang/jq/wiki/jq-Language-Description#the-jq-langua describes its expression semantics as closures as well, though unlike jq, the operator expressions here are not generators and do not implement backtracking. -### Examples +## Examples --- diff --git a/book/src/super-sql/declarations/pragmas.md b/book/src/super-sql/declarations/pragmas.md index 3c19c951af..6bbfffe063 100644 --- a/book/src/super-sql/declarations/pragmas.md +++ b/book/src/super-sql/declarations/pragmas.md @@ -1,4 +1,4 @@ -## Pragmas +# Pragmas Pragmas control various language features and appear in a declaration block so their effect is lexically scoped. They have the form @@ -14,7 +14,7 @@ If `` is omitted, it defaults to `true`. Pragmas must appear in the declaration section of a [scope](../queries.md#scope). -### List of Pragmas +## List of Pragmas Currently, there are two supported pragmas. @@ -26,7 +26,7 @@ Currently, there are two supported pragmas. * `false` to follow Google SQL semantics of resolving identifiers first from column aliases then from the input table * `true` to follow PostgreSQL semantics of resolving identifiers first from the input table then from the column aliases -### Example +## Example --- diff --git a/book/src/super-sql/declarations/queries.md b/book/src/super-sql/declarations/queries.md index b95e1a6bb9..f35058ff2e 100644 --- a/book/src/super-sql/declarations/queries.md +++ b/book/src/super-sql/declarations/queries.md @@ -1,4 +1,4 @@ -## Queries +# Queries A query may be bound to an identifier as a named query with the syntax ``` @@ -32,7 +32,7 @@ then embedding that scalar result in an [expression](../expressions/intro.md). appears syntactically as a subquery in this case, the result is efficient because the compiler will materialize the result and reuse it on each invocation. -### Examples +## Examples --- diff --git a/book/src/super-sql/declarations/types.md b/book/src/super-sql/declarations/types.md index 8f729cc762..96e9947e39 100644 --- a/book/src/super-sql/declarations/types.md +++ b/book/src/super-sql/declarations/types.md @@ -1,4 +1,4 @@ -## Types +# Types Named types are declared with the syntax ``` @@ -28,7 +28,7 @@ This does not affect the binding of the type used in other expressions in the qu Types can also be bound to identifiers without creating a named type using a [constant](constants.md) declaration binding the name to a [type value](../types/type.md). -### Examples +## Examples --- diff --git a/book/src/super-sql/expressions/arithmetic.md b/book/src/super-sql/expressions/arithmetic.md index c73d856546..5b13c7cb55 100644 --- a/book/src/super-sql/expressions/arithmetic.md +++ b/book/src/super-sql/expressions/arithmetic.md @@ -1,10 +1,10 @@ -## Arithmetic +# Arithmetic Arithmetic operations (`*`, `/`, `%`, `+`, `-`) follow customary syntax and semantics and are left-associative with multiplication and division having precedence over addition and subtraction. `%` is the modulo operator. -### Unary Sign +## Unary Sign Any number may be signed with a unary operator having the form: ``` @@ -16,7 +16,7 @@ and ``` where `` is any [expression](intro.md) that results in a [number](../types/numbers.md) type. -### Example +## Example --- diff --git a/book/src/super-sql/expressions/cast.md b/book/src/super-sql/expressions/cast.md index d1e9f92abe..213e2c286a 100644 --- a/book/src/super-sql/expressions/cast.md +++ b/book/src/super-sql/expressions/cast.md @@ -1,4 +1,4 @@ -## Casts +# Casts Casting is the process of converting a value from its current data type to another type using an explicit expression having the form @@ -28,7 +28,7 @@ the target type. The target type cannot contain an error type. The [error](../functions/errors/error.md) function should instead be used to create error values. -### Primitive Values +## Primitive Values Some primitive values can be cast to other primitive types, but not all possibilities are permitted and instead result in structured errors. @@ -70,7 +70,7 @@ A null value of type [null](../types/null.md) may be cast to any type. > A future version of this documentation will provide detailed documentation for > acceptable date/time strings. -### Complex Values +## Complex Values When a complex value has multiple levels of nesting, casting is applied recursively into the value hierarchy. @@ -123,7 +123,7 @@ The casting rules for complex values are as follows: serialized in the [SUP](../../formats/sup.md) format, or * a [union](#union-types) or [named type](#named-types). -### Union Types +## Union Types When casting a value to a union type, the member type of the union is selected to find a _best fit_ of the available types. If no fit exists, a structured @@ -137,12 +137,12 @@ Otherwise, the best fit is determined from the input type as follows: > A future version of this documentation will provide detailed documentation for > the best-fit selection algorithm. -### Named Types +## Named Types When casting to a named type, the cast is carried out using its underlying type then the named type is reattached to the result. -### Errors +## Errors Casting a value to an incompatible type results in a structured error of the form: ``` @@ -166,7 +166,7 @@ That is, the value for `a` was successfully cast from string `"1`" to integer `1 the value for `b` could not be cast to an IP address so a structured error is instead embedded as the value for `b`. -### Examples +## Examples --- diff --git a/book/src/super-sql/expressions/comparisons.md b/book/src/super-sql/expressions/comparisons.md index aebeeaf7dd..3117a0603a 100644 --- a/book/src/super-sql/expressions/comparisons.md +++ b/book/src/super-sql/expressions/comparisons.md @@ -1,4 +1,4 @@ -## Comparisons +# Comparisons Comparison expressions follow customary syntax and semantics and result in a truth value of type [bool](../types/bool.md) or an [error](../types/error.md). @@ -74,7 +74,7 @@ different types, consider the [compare](../functions/generics/compare.md) functi If either operand to a comparison is `error("missing")`, then the result is `error("missing")`. -### Examples +## Examples --- diff --git a/book/src/super-sql/expressions/concat.md b/book/src/super-sql/expressions/concat.md index f53f9ac97d..60e090f946 100644 --- a/book/src/super-sql/expressions/concat.md +++ b/book/src/super-sql/expressions/concat.md @@ -1,4 +1,4 @@ -## Concatenation +# Concatenation [Strings](../types/string.md) may be concatenated using the concatenation operator having the form ``` @@ -9,7 +9,7 @@ where `` is any [expression](intro.md) that results in a string value. It is an error to concatenate non-string values. Values may be converted to string using a [cast](cast.md) to type string. -### Examples +## Examples --- diff --git a/book/src/super-sql/expressions/conditional.md b/book/src/super-sql/expressions/conditional.md index 04109eb848..c900236ed9 100644 --- a/book/src/super-sql/expressions/conditional.md +++ b/book/src/super-sql/expressions/conditional.md @@ -1,4 +1,4 @@ -## Conditionals +# Conditionals Conditional expressions compute a result from two or more possibilities determined by [Boolean](../types/bool.md) predicates. @@ -6,7 +6,7 @@ determined by [Boolean](../types/bool.md) predicates. Conditionals can be written using SQL-style [CASE syntax](#case-expressions) or C-style [ternary expressions](#ternary-conditional). -### Case Expressions +## Case Expressions SQL-style `CASE` expressions have two forms. @@ -48,7 +48,7 @@ The error is reported at compile time if possible, but when input is dynamic and the type cannot be statically determined, a [structured error](../types/error.md) is generated at run time as the result of the conditional expression. -### Ternary Conditional +## Ternary Conditional The [ternary](https://en.wikipedia.org/wiki/Ternary_conditional_operator) form follows the C language and has syntax ``` @@ -65,7 +65,7 @@ is reported at compile time if possible, but when input is dynamic and the type cannot be statically determined, a [structured error](../types/error.md) is generated at run time as the result of the conditional expression. -### Examples +## Examples --- diff --git a/book/src/super-sql/expressions/containment.md b/book/src/super-sql/expressions/containment.md index 0ac5c66007..a00f8256b7 100644 --- a/book/src/super-sql/expressions/containment.md +++ b/book/src/super-sql/expressions/containment.md @@ -1,4 +1,4 @@ -## Containment +# Containment A containment expression expression tests for the existence of a value in another value and has the form @@ -28,7 +28,7 @@ When the `` is a non-array [subquery](subqueries.md), it is coerced to a [array subquery](subqueries.md#array-subqueries) and the `in` expression is evaluated on the array result of the subquery. -### Examples +## Examples --- diff --git a/book/src/super-sql/expressions/dot.md b/book/src/super-sql/expressions/dot.md index fc6dfc0816..821289198d 100644 --- a/book/src/super-sql/expressions/dot.md +++ b/book/src/super-sql/expressions/dot.md @@ -1,4 +1,4 @@ -## Dot +# Dot Records and maps with string keys are dereferenced with the dot operator `.` as is customary in other languages. The syntax is @@ -44,7 +44,7 @@ may be used with a quoted string to represent any valid field name. Such field names can be accessed using [this](../intro.md#pipe-scoping) with an index-style reference, e.g., `this["field with spaces"]`. -### Examples +## Examples --- diff --git a/book/src/super-sql/expressions/exists.md b/book/src/super-sql/expressions/exists.md index 939bc64cb3..a19daf1321 100644 --- a/book/src/super-sql/expressions/exists.md +++ b/book/src/super-sql/expressions/exists.md @@ -1,4 +1,4 @@ -## Exists +# Exists The `exists` operator tests whether a subquery has a non-empty result and has the form @@ -12,7 +12,7 @@ It is a syntactic shortcut for len([]) != 0 ``` -### Examples +## Examples --- diff --git a/book/src/super-sql/expressions/f-strings.md b/book/src/super-sql/expressions/f-strings.md index 7d4639eb78..ca3293ea03 100644 --- a/book/src/super-sql/expressions/f-strings.md +++ b/book/src/super-sql/expressions/f-strings.md @@ -1,4 +1,4 @@ -## F-Strings +# F-Strings A formatted string (or f-string) is a string [literal](literals.md) prefixed with `f` that includes replacement [expressions](intro.md) delimited by curly braces: @@ -21,7 +21,7 @@ first error encountered in left-to-right order. To represent a literal `{` character inside an f-string, it must be escaped with a backslash as `\{`. This escape sequence is valid only in f-strings. -### Examples +## Examples --- _Some simple arithmetic_ diff --git a/book/src/super-sql/expressions/functions.md b/book/src/super-sql/expressions/functions.md index bf7b0dae0c..e8c1e85bdb 100644 --- a/book/src/super-sql/expressions/functions.md +++ b/book/src/super-sql/expressions/functions.md @@ -1,4 +1,4 @@ -## Function Calls +# Function Calls Functions compute a result from zero or more input arguments that are passed by value as positional arguments. @@ -25,7 +25,7 @@ Functions are not first-class values and cannot be assigned to super-structured as there are no function values in the super-structured [data model](../../formats/model.md). Instead, functions may only be called or passed as a reference to another function. -### Lambda Expressions +## Lambda Expressions A lambda expression is an [anonymous function](https://en.wikipedia.org/wiki/Anonymous_function) having the form ``` @@ -55,7 +55,7 @@ f(lambda x:x+1, 2) calls the function `f` with the lambda as its first argument and the value `2` as its second argument. -### Function References +## Function References The syntax for referencing a function by name is ``` @@ -76,7 +76,7 @@ For example, ``` is a reference to the built-in function [upper](../functions/strings/upper.md). -### Examples +## Examples --- diff --git a/book/src/super-sql/expressions/index.md b/book/src/super-sql/expressions/index.md index bfd7ef3722..ccfc8937f8 100644 --- a/book/src/super-sql/expressions/index.md +++ b/book/src/super-sql/expressions/index.md @@ -1,4 +1,4 @@ -## Index +# Index The index operation is denoted with square brackets and can be applied to any indexable data type and has the form: @@ -45,7 +45,7 @@ representing the byte value at that offset in the bytes sequence. >[!NOTE] > Indexing of strings and bytes is not yet implemented. -### Index Base +## Index Base Indexing in SuperSQL is 0-based meaning the first element is at index `0` and the last element is at index `n-1` for an entity of size `n`. @@ -58,7 +58,7 @@ to specify either 1-based indexing or mixed indexing. In mixed indexing, >[!NOTE] > Mixed indexing is not yet implemented. -### Examples +## Examples --- diff --git a/book/src/super-sql/expressions/inputs.md b/book/src/super-sql/expressions/inputs.md index f80a70f2e8..b9ff39423e 100644 --- a/book/src/super-sql/expressions/inputs.md +++ b/book/src/super-sql/expressions/inputs.md @@ -1,4 +1,4 @@ -## Inputs +# Inputs Input data is processed by queries through [expressions](intro.md) that contain input-data references. @@ -34,7 +34,7 @@ Otherwise, column references to non-record data in dynamic inputs generally cause runtime [errors](../types/error.md) like `error("missing")`. -### Examples +## Examples --- diff --git a/book/src/super-sql/expressions/intro.md b/book/src/super-sql/expressions/intro.md index 6e3e7493aa..8469270bf0 100644 --- a/book/src/super-sql/expressions/intro.md +++ b/book/src/super-sql/expressions/intro.md @@ -1,4 +1,4 @@ -## Expressions +# Expressions Expressions are the means to carry out calculations and utilize familiar query-language elements like literal values, function calls, subqueries, @@ -27,7 +27,7 @@ their semantics diverge in some key ways: * double-quoted string [literals](literals.md) may be used in pipe expressions but are interpreted as [identifiers](../queries.md#identifiers) in SQL expressions. -### Expression Syntax +## Expression Syntax Expressions are composed from operands and operators over operands. @@ -53,7 +53,7 @@ Operators include * [logic](logic.md) to combine predicates using Boolean logic, and * [slices](slices.md) to extract subsequences from arrays, sets, strings, and bytes. -### Identifier Resolution +## Identifier Resolution An identifier that appears as an operand in an expression is resolved to the entity that it represents using lexical [scoping](../queries.md#scope). @@ -91,7 +91,7 @@ For other instances of identifiers, the identifier is presumed to be an [input reference](inputs.md) and is resolved as such. -### Precedence +## Precedence When multiple operators appear in an unparenthesized sequence, ambiguity may arise by the order of evaluation as expressions are @@ -126,7 +126,7 @@ Some operators like [case expressions](conditional.md#case-expressions) do not have any such ambiguity as keywords delineate their sub-expressions and thus do not have any inherent precedence. -### Coercion +## Coercion >[!NOTE] > A forthcoming version of this documentation will describe the coercion diff --git a/book/src/super-sql/expressions/literals.md b/book/src/super-sql/expressions/literals.md index 45449303e8..e12912d199 100644 --- a/book/src/super-sql/expressions/literals.md +++ b/book/src/super-sql/expressions/literals.md @@ -1,4 +1,4 @@ -## Literals +# Literals Literal values represent specific instances of a [type](../types/intro.md) embedded directly into an [expression](intro.md) like the integer `1`, the record `{x:1.5,y:-4.0}`, diff --git a/book/src/super-sql/expressions/logic.md b/book/src/super-sql/expressions/logic.md index df272c24d8..78bb9316a2 100644 --- a/book/src/super-sql/expressions/logic.md +++ b/book/src/super-sql/expressions/logic.md @@ -1,4 +1,4 @@ -## Logic +# Logic The keywords `and`, `or`, `not`, and `!` perform logic on operands of type [bool](../types/bool.md). The binary operators `and` and `or` operate on Boolean values and result in diff --git a/book/src/super-sql/expressions/slices.md b/book/src/super-sql/expressions/slices.md index 55e21e46a4..b21a5d636f 100644 --- a/book/src/super-sql/expressions/slices.md +++ b/book/src/super-sql/expressions/slices.md @@ -1,4 +1,4 @@ -## Slices +# Slices A slice expression is a variation of an [index](index.md) expression that returns a range of values instead of a single value and can be applied @@ -33,13 +33,13 @@ consisting of unicode code points comprising the given range. If the `` expression is type `bytes`, then the result is a bytes sequence consisting of bytes comprising the given range. -### Index Base +## Index Base The index base for slice expressions is determined identically to the [index base for indexing](index.md#index-base). By default, slice indexes are zero based. -### Examples +## Examples --- diff --git a/book/src/super-sql/expressions/subqueries.md b/book/src/super-sql/expressions/subqueries.md index 799c09eba9..0bf67ba608 100644 --- a/book/src/super-sql/expressions/subqueries.md +++ b/book/src/super-sql/expressions/subqueries.md @@ -1,4 +1,4 @@ -## Subqueries +# Subqueries A subquery is a [query](../queries.md) embedded in an [expression](intro.md). @@ -24,7 +24,7 @@ For the [in](containment.md) operator, any subquery on the right-hand side is always treated as an [array subquery](#array-subqueries), thus providing compatibility with SQL syntax. -### Array Subqueries +## Array Subqueries When multiple values are expected, an array subquery can be used to group the multi-valued result into a single-valued array. @@ -48,7 +48,7 @@ e.g., the array subquery above could also be rewritten as values {a:(values 1,2,3 | values this+1 | collect(this))} ``` -### Independent Subqueries +## Independent Subqueries A subquery that depends on its input as described above is called a _dependent subquery_. @@ -71,7 +71,7 @@ Then, for each input value `3` and `4`, the result is emitted, e.g., {that:4,count:3} ``` -### Correlated Subqueries +## Correlated Subqueries When a subquery appears within a [SQL operator](../sql/intro.md), [relational scope](../intro.md#relational-scoping) is active and references to table aliases and columns @@ -93,7 +93,7 @@ where `` generates the correlated subquery values, then they can be accessed as if the `outer` field is the outer scope and the `inner` field is the subquery scope. -### Named Subqueries +## Named Subqueries When a previously declared [named query](../declarations/queries.md) is referenced in an expression, it is automatically evaluated as a subquery, @@ -112,7 +112,7 @@ values [q] ``` outputs the value `[1,2,3]`. -### Recursive Subqueries +## Recursive Subqueries When subqueries are combined with recursive invocation of the [function](../declarations/functions.md) they appear in, some powerful patterns can be constructed. @@ -150,7 +150,7 @@ fn addOne(node): case typeof(node) when then node+1 else node end then each leaf value of the nested value of type `int64` would be incremented while the other leaves would be left alone. See the example below. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/errors/error.md b/book/src/super-sql/functions/errors/error.md index 49c2a68c47..88ec5298b7 100644 --- a/book/src/super-sql/functions/errors/error.md +++ b/book/src/super-sql/functions/errors/error.md @@ -1,20 +1,20 @@ -### Function +# error -  **error** — wrap a value as an error +wrap a value as an error -### Synopsis +## Synopsis ``` error(val: any) -> error ``` -### Description +## Description The `error` function returns an error version of any value. It wraps the value `val` to turn it into an error type providing a means to create structured and stacked errors. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/errors/has_error.md b/book/src/super-sql/functions/errors/has_error.md index ed78570fc9..efbb455270 100644 --- a/book/src/super-sql/functions/errors/has_error.md +++ b/book/src/super-sql/functions/errors/has_error.md @@ -1,21 +1,21 @@ -### Function +# has_error -  **has_error** — test if a value is or contains an error +test if a value is or contains an error -### Synopsis +## Synopsis ``` has_error(val: any) -> bool ``` -### Description +## Description The `has_error` function returns true if its argument is or contains an error. `has_error` is different from [`is_error`](is_error.md) in that `has_error` recursively searches a value to determine if there is any error in a nested value. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/errors/is_error.md b/book/src/super-sql/functions/errors/is_error.md index 4bb4d1d94c..201cf32583 100644 --- a/book/src/super-sql/functions/errors/is_error.md +++ b/book/src/super-sql/functions/errors/is_error.md @@ -1,19 +1,19 @@ -### Function +# is_error -  **is_error** — test if a value is an error +test if a value is an error -### Synopsis +## Synopsis ``` is_error(val: any) -> bool ``` -### Description +## Description The `is_error` function returns true if its argument's type is an error. `is_error(v)` is shorthand for `kind(v)=="error"`, -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/errors/missing.md b/book/src/super-sql/functions/errors/missing.md index bb470ff8df..70367dd209 100644 --- a/book/src/super-sql/functions/errors/missing.md +++ b/book/src/super-sql/functions/errors/missing.md @@ -1,14 +1,14 @@ -### Function +# missing -  **missing** — test for the "missing" error +test for the "missing" error -### Synopsis +## Synopsis ``` missing(val: any) -> bool ``` -### Description +## Description The `missing` function returns true if its argument is `error("missing")` and false otherwise. @@ -26,7 +26,7 @@ switch default ( ... ) ``` -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/errors/quiet.md b/book/src/super-sql/functions/errors/quiet.md index e34222147e..74f489654c 100644 --- a/book/src/super-sql/functions/errors/quiet.md +++ b/book/src/super-sql/functions/errors/quiet.md @@ -1,14 +1,14 @@ -### Function +# quiet -  **quiet** — quiet "missing" errors +quiet "missing" errors -### Synopsis +## Synopsis ``` quiet(val: any) -> any ``` -### Description +## Description The `quiet` function returns its argument `val` unless `val` is `error("missing")`, in which case it returns `error("quiet")`. @@ -16,7 +16,7 @@ Various operators and functions treat quiet errors differently than missing errors, in particular, dropping them instead of propagating them. Quiet errors are ignored by operators `aggregate`, `cut`, and `values`. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/generics/coalesce.md b/book/src/super-sql/functions/generics/coalesce.md index 56d456c72e..e1b0f631aa 100644 --- a/book/src/super-sql/functions/generics/coalesce.md +++ b/book/src/super-sql/functions/generics/coalesce.md @@ -1,19 +1,19 @@ -### Function +# coalesce -  **coalesce** — return first value that is not null or an error +return first value that is not null or an error -### Synopsis +## Synopsis ``` coalesce(val: any [, ... val: any]) -> any ``` -### Description +## Description The `coalesce` function returns the first of its arguments that is not null or an error. It returns null if all its arguments are null or an error. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/generics/compare.md b/book/src/super-sql/functions/generics/compare.md index f3040e7d9a..372e3405ba 100644 --- a/book/src/super-sql/functions/generics/compare.md +++ b/book/src/super-sql/functions/generics/compare.md @@ -1,14 +1,14 @@ -### Function +# compare -  **compare** — compare values even when types vary +compare values even when types vary -### Synopsis +## Synopsis ``` compare(a: any, b: any [, nullsMax: bool]) -> int64 ``` -### Description +## Description The `compare` function returns an integer comparing two values. The result will be 0 if a is equal to b, +1 if a is greater than b, and -1 if a is less than b. @@ -26,7 +26,7 @@ as found in other SQL databases such as Postgres. `nullsMax` is an optional value (true by default) that determines whether `null` is treated as the minimum or maximum value. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/generics/has.md b/book/src/super-sql/functions/generics/has.md index ec9fe1cc73..129505c903 100644 --- a/book/src/super-sql/functions/generics/has.md +++ b/book/src/super-sql/functions/generics/has.md @@ -1,14 +1,14 @@ -### Function +# has -  **has** — test existence of values +test existence of values -### Synopsis +## Synopsis ``` has(val: any [, ... val: any]) -> bool ``` -### Description +## Description The `has` function returns false if any of its arguments are `error("missing")` and otherwise returns true. @@ -27,7 +27,7 @@ switch default ( ... ) ``` -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/generics/len.md b/book/src/super-sql/functions/generics/len.md index 5b7c34b611..992b493c70 100644 --- a/book/src/super-sql/functions/generics/len.md +++ b/book/src/super-sql/functions/generics/len.md @@ -1,14 +1,14 @@ -### Function +# len -  **len** — the type-dependent length of a value +the type-dependent length of a value -### Synopsis +## Synopsis ``` len(val: array|bytes|ip|map|net|null|record|set|string|type) -> int64 ``` -### Description +## Description The _len_ function returns the length of its argument `val`. The semantics of this length depend on the value's [type](../../types/intro.md). @@ -42,7 +42,7 @@ underlying type definition of `val` as indicated below. |`set` |`len` of the defined element type | |`union` |Count of defined member types | -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/generics/map.md b/book/src/super-sql/functions/generics/map.md index 6c6ce84a9c..28cf74edc3 100644 --- a/book/src/super-sql/functions/generics/map.md +++ b/book/src/super-sql/functions/generics/map.md @@ -1,14 +1,14 @@ -### Function +# map -  **map** — apply a function to each element of an array or set +apply a function to each element of an array or set -### Synopsis +## Synopsis ``` map(v: array|set, f: function) -> array|set|error ``` -### Description +## Description The `map` function applies a single-argument function `f`, in the form of an existing function or a lambda expression, @@ -29,7 +29,7 @@ lambda x: ``` where `` is any expression depending only on the lambda argument. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/generics/nullif.md b/book/src/super-sql/functions/generics/nullif.md index 223abb4473..051b1db41c 100644 --- a/book/src/super-sql/functions/generics/nullif.md +++ b/book/src/super-sql/functions/generics/nullif.md @@ -1,19 +1,19 @@ -### Function +# nullif -  **nullif** — returns a null value if values are equal +returns a null value if values are equal -### Synopsis +## Synopsis ``` nullif(val1: any, val2: any) -> any ``` -### Description +## Description The `nullif` function returns a `null` value if its first argument `val1` is equal to its second argument `val2`, otherwise it returns `val1`. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/generics/under.md b/book/src/super-sql/functions/generics/under.md index a110f32988..9a4b36b9a6 100644 --- a/book/src/super-sql/functions/generics/under.md +++ b/book/src/super-sql/functions/generics/under.md @@ -1,14 +1,14 @@ -### Function +# under -  **under** — the underlying value +the underlying value -### Synopsis +## Synopsis ``` under(val: any) -> any ``` -### Description +## Description The _under_ function returns the value underlying the argument `val`: * for [unions](../../types/union.md), it returns the value as its elemental type of the union, @@ -17,7 +17,7 @@ The _under_ function returns the value underlying the argument `val`: * for [type values](../../types/type.md), it removes a named type if one exists; otherwise, * it returns `val` unmodified. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/intro.md b/book/src/super-sql/functions/intro.md index 13d8cdfd71..3dc111a599 100644 --- a/book/src/super-sql/functions/intro.md +++ b/book/src/super-sql/functions/intro.md @@ -1,4 +1,4 @@ -## Functions +# Functions An invocation of a built-in function may appear in any [expression](../expressions/intro.md). diff --git a/book/src/super-sql/functions/math/abs.md b/book/src/super-sql/functions/math/abs.md index 033d7e5eeb..a78b4fec69 100644 --- a/book/src/super-sql/functions/math/abs.md +++ b/book/src/super-sql/functions/math/abs.md @@ -1,19 +1,19 @@ -### Function +# abs -  **abs** — absolute value of a number +absolute value of a number -### Synopsis +## Synopsis ``` abs(n: number) -> number ``` -### Description +## Description The `abs` function returns the absolute value of its argument `n`, which must be a numeric type. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/math/ceil.md b/book/src/super-sql/functions/math/ceil.md index ab40a7d260..92de7a86b0 100644 --- a/book/src/super-sql/functions/math/ceil.md +++ b/book/src/super-sql/functions/math/ceil.md @@ -1,19 +1,19 @@ -### Function +# ceil -  **ceil** — ceiling of a number +ceiling of a number -### Synopsis +## Synopsis ``` ceil(n: number) -> number ``` -### Description +## Description The `ceil` function returns the smallest integer greater than or equal to its argument `n`, which must be a numeric type. The return type retains the type of the argument. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/math/floor.md b/book/src/super-sql/functions/math/floor.md index 60c3d87a1a..172c74a7b7 100644 --- a/book/src/super-sql/functions/math/floor.md +++ b/book/src/super-sql/functions/math/floor.md @@ -1,19 +1,19 @@ -### Function +# floor -  **floor** — floor of a number +floor of a number -### Synopsis +## Synopsis ``` floor(n: number) -> number ``` -### Description +## Description The `floor` function returns the greatest integer less than or equal to its argument `n`, which must be a numeric type. The return type retains the type of the argument. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/math/log.md b/book/src/super-sql/functions/math/log.md index 07c682bb1c..0e483f1880 100644 --- a/book/src/super-sql/functions/math/log.md +++ b/book/src/super-sql/functions/math/log.md @@ -1,20 +1,20 @@ -### Function +# log -  **log** — natural logarithm +natural logarithm -### Synopsis +## Synopsis ``` log(val: number) -> float64 ``` -### Description +## Description The `log` function returns the natural logarithm of its argument `val`, which takes a [numeric](../../types/numbers.md) type. The return value is a float64 or an error. Negative values result in an error. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/math/pow.md b/book/src/super-sql/functions/math/pow.md index b4cb953ece..e123c91c8b 100644 --- a/book/src/super-sql/functions/math/pow.md +++ b/book/src/super-sql/functions/math/pow.md @@ -1,19 +1,19 @@ -### Function +# pow -  **pow** — exponential function of any base +exponential function of any base -### Synopsis +## Synopsis ``` pow(x: number, y: number) -> float64 ``` -### Description +## Description The `pow` function returns the value `x` raised to the power of `y`. The return value is a float64 or an error. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/math/round.md b/book/src/super-sql/functions/math/round.md index 4e8ab30055..7cfb050ffd 100644 --- a/book/src/super-sql/functions/math/round.md +++ b/book/src/super-sql/functions/math/round.md @@ -1,19 +1,19 @@ -### Function +# round -  **round** — round a number +round a number -### Synopsis +## Synopsis ``` round(val: number) -> number ``` -### Description +## Description The `round` function returns the number `val` rounded to the nearest integer value. which must be a numeric type. The return type retains the type of the argument. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/math/sqrt.md b/book/src/super-sql/functions/math/sqrt.md index 88a16e96bc..99aba6a344 100644 --- a/book/src/super-sql/functions/math/sqrt.md +++ b/book/src/super-sql/functions/math/sqrt.md @@ -1,19 +1,19 @@ -### Function +# sqrt -  **sqrt** — square root of a number +square root of a number -### Synopsis +## Synopsis ``` sqrt(val: number) -> float64 ``` -### Description +## Description The `sqrt` function returns the square root of its argument `val`, which must be numeric. The return value is a float64. Negative values result in `NaN`. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/network/cidr_match.md b/book/src/super-sql/functions/network/cidr_match.md index cf68250062..5dfbb1cb95 100644 --- a/book/src/super-sql/functions/network/cidr_match.md +++ b/book/src/super-sql/functions/network/cidr_match.md @@ -1,21 +1,21 @@ -### Function +# cidr_match -  **cidr_match** — test if IP is in a network +test if IP is in a network -### Synopsis +## Synopsis ``` cidr_match(network: net, val: any) -> bool ``` -### Description +## Description The `cidr_match` function returns true if `val` contains an IP address that falls within the network given by `network`. When `val` is a complex type, the function traverses its nested structure to find any `ip` values. If `network` is not type `net`, then an error is returned. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/network/network_of.md b/book/src/super-sql/functions/network/network_of.md index 68971b41b2..a769d8bed2 100644 --- a/book/src/super-sql/functions/network/network_of.md +++ b/book/src/super-sql/functions/network/network_of.md @@ -1,14 +1,14 @@ -### Function +# network_of -  **network_of** — the network of an IP +the network of an IP -### Synopsis +## Synopsis ``` network_of(val: ip [, mask: ip|int|uint]) -> net ``` -### Description +## Description The `network_of` function returns the network of the IP address given by `val` as determined by the optional `mask`. If `mask` is an integer rather @@ -16,7 +16,7 @@ than an IP address, it is presumed to be a network prefix of the indicated lengt If `mask` is omitted, then a class A (8 bit), B (16 bit), or C (24 bit) network is inferred from `val`, which in this case, must be an IPv4 address. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/parsing/base64.md b/book/src/super-sql/functions/parsing/base64.md index 62c68a88be..7dbfdec847 100644 --- a/book/src/super-sql/functions/parsing/base64.md +++ b/book/src/super-sql/functions/parsing/base64.md @@ -1,21 +1,21 @@ -### Function +# base64 -  **base64** — encode/decode Base64 strings +encode/decode Base64 strings -### Synopsis +## Synopsis ``` base64(b: bytes) -> string base64(s: string) -> bytes ``` -### Description +## Description The `base64` function encodes a bytes value `b` as a [Base64](https://en.wikipedia.org/wiki/Base64) string, or decodes a Base64 string `s` into a bytes value. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/parsing/grok.md b/book/src/super-sql/functions/parsing/grok.md index f7c636bf9a..fa956edcd1 100644 --- a/book/src/super-sql/functions/parsing/grok.md +++ b/book/src/super-sql/functions/parsing/grok.md @@ -1,15 +1,15 @@ -### Function +# grok -  **grok** — parse a string using Grok patterns +parse a string using Grok patterns -### Synopsis +## Synopsis ``` grok(p: string, s: string) -> record grok(p: string, s: string, definitions: string) -> record ``` -### Description +## Description The `grok` function parses a string `s` using patterns in string `p` and returns a record containing parsed fields. @@ -26,13 +26,13 @@ When provided with three arguments, `definitions` is a string of named patterns in the format `PATTERN_NAME PATTERN` each separated by newlines (`\n`). The named patterns can then be referenced in argument `p`. -#### Included Patterns +### Included Patterns The `grok` function by default includes a set of built-in named patterns that can be referenced in any pattern. The included named patterns can be seen [here](https://raw.githubusercontent.com/brimdata/super/main/pkg/grok/base.go). -#### Comparison to Other Implementations +### Comparison to Other Implementations Although Grok functionality appears in many open source tools, it lacks a formal specification. As a result, example parsing configurations found via @@ -93,7 +93,7 @@ the use of the `grok` function, review the tips below. # expected output {timestamp:"Jan 1 06:25:43",logsource:"mailserver14",program:"postfix/cleanup",pid:"21403",queue_id:"BEF25A72965",syslog_message:"message-id=<20130101142543.5828399CCAF@mailserver14.example.com>"} ``` -

+
4. The Grok implementation for Logstash uses the [Oniguruma](https://github.com/kkos/oniguruma) regular expressions library @@ -118,7 +118,7 @@ the use of the `grok` function, review the tips below. > issue describing your use case or come talk to us on > [community Slack](https://www.brimdata.io/join-slack/). -#### Debugging +### Debugging Much like creating complex regular expressions, building sophisticated Grok configurations can be frustrating because single-character mistakes can make @@ -137,12 +137,12 @@ If you devise a working Grok config in such a tool be sure to incrementally test it with SuperSQL's `grok`. Be mindful of necessary adjustments such as those described [above](#comparison-to-other-implementations) and in the [examples](#examples). -#### Need Help? +### Need Help? If you have difficulty with your Grok configurations, please come talk to us on the [community Slack](https://www.brimdata.io/join-slack/). -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/parsing/hex.md b/book/src/super-sql/functions/parsing/hex.md index 09ee5bd11a..dd2addb65f 100644 --- a/book/src/super-sql/functions/parsing/hex.md +++ b/book/src/super-sql/functions/parsing/hex.md @@ -1,20 +1,20 @@ -### Function +# hex -  **hex** — encode/decode hexadecimal strings +encode/decode hexadecimal strings -### Synopsis +## Synopsis ``` hex(b: bytes) -> string hex(s: string) -> bytes ``` -### Description +## Description The `hex` function encodes a bytes value `b` as a hexadecimal string or decodes a hexadecimal string `s` into a bytes value. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/parsing/parse_sup.md b/book/src/super-sql/functions/parsing/parse_sup.md index a265dd2877..440b7272d3 100644 --- a/book/src/super-sql/functions/parsing/parse_sup.md +++ b/book/src/super-sql/functions/parsing/parse_sup.md @@ -1,20 +1,20 @@ -### Function +# parse_sup -  **parse_sup** — parse SUP or JSON text into a value +parse SUP or JSON text into a value -### Synopsis +## Synopsis ``` parse_sup(s: string) -> any ``` -### Description +## Description The `parse_sup` function parses the `s` argument that must be in the form of [SUP](../../../formats/sup.md) or JSON into a value of any type. This is analogous to JavaScript's `JSON.parse()` function. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/parsing/parse_uri.md b/book/src/super-sql/functions/parsing/parse_uri.md index aa0ccf5547..a84f54cc21 100644 --- a/book/src/super-sql/functions/parsing/parse_uri.md +++ b/book/src/super-sql/functions/parsing/parse_uri.md @@ -1,14 +1,14 @@ -### Function +# parse_uri -  **parse_uri** — parse a string URI into a structured record +parse a string URI into a structured record -### Synopsis +## Synopsis ``` parse_uri(uri: string) -> record ``` -### Description +## Description The `parse_uri` function parses the `uri` argument that must have the form of a [Universal Resource Identifier](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) @@ -28,7 +28,7 @@ with the following type signature: } ``` -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/parsing/regexp.md b/book/src/super-sql/functions/parsing/regexp.md index a55ad03a3a..260b3f6cba 100644 --- a/book/src/super-sql/functions/parsing/regexp.md +++ b/book/src/super-sql/functions/parsing/regexp.md @@ -1,14 +1,14 @@ -### Function +# regexp -  **regexp** — perform a regular expression search on a string +perform a regular expression search on a string -### Synopsis +## Synopsis ``` regexp(re: string, s: string) -> any ``` -### Description +## Description The `regexp` function returns an array of strings holding the text of the left most match of the regular expression `re`, which is @@ -16,7 +16,7 @@ a [regular expression](../../queries.md#regular-expression), and the matches of each parenthesized subexpression (also known as capturing groups) if there are any. A null value indicates no match. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/parsing/regexp_replace.md b/book/src/super-sql/functions/parsing/regexp_replace.md index be8b7d05b1..3e3e0bf578 100644 --- a/book/src/super-sql/functions/parsing/regexp_replace.md +++ b/book/src/super-sql/functions/parsing/regexp_replace.md @@ -1,14 +1,14 @@ -### Function +# regexp_replace -  **regexp_replace** — replace regular expression matches in a string +replace regular expression matches in a string -### Synopsis +## Synopsis ``` regexp_replace(s: string, re: string, new: string) -> string ``` -### Description +## Description The `regexp_replace` function substitutes all characters matching the [regular expression](../../queries.md#regular-expression) `re` in string `s` with @@ -27,7 +27,7 @@ In the `$name` form, `name` is taken to be as long as possible: `$1x` is equival To insert a literal `$` in the output, use `$$` in the template. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/records/fields.md b/book/src/super-sql/functions/records/fields.md index 9506cffb6b..495cd08fe9 100644 --- a/book/src/super-sql/functions/records/fields.md +++ b/book/src/super-sql/functions/records/fields.md @@ -1,14 +1,14 @@ -### Function +# fields -  **fields** — return the flattened path names of a record +return the flattened path names of a record -### Synopsis +## Synopsis ``` fields(r: record) -> [[string]] ``` -### Description +## Description The `fields` function returns an array of string arrays of all the field names in record `r`. A field's path name is represented by an array of strings since the dot @@ -17,7 +17,7 @@ can appear in a field name. `error("missing")` is returned if `r` is not a record. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/records/flatten.md b/book/src/super-sql/functions/records/flatten.md index f0a90eec91..7c6c542a2f 100644 --- a/book/src/super-sql/functions/records/flatten.md +++ b/book/src/super-sql/functions/records/flatten.md @@ -1,14 +1,14 @@ -### Function +# flatten -  **flatten** — transform a record into a flattened array +transform a record into a flattened array -### Synopsis +## Synopsis ``` flatten(val: record) -> [{key:[string],value:}] ``` -### Description +## Description The `flatten` function returns an array of records `[{key:[string],value:}]` where `key` is a string array of the path of each record field of `val` and @@ -21,7 +21,7 @@ inner type is a union of the record types present. > where the array-of-strings value of key becomes a more general data structure representing > all possible value types that comprise a path. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/records/nest_dotted.md b/book/src/super-sql/functions/records/nest_dotted.md index e8a2df8238..1051652762 100644 --- a/book/src/super-sql/functions/records/nest_dotted.md +++ b/book/src/super-sql/functions/records/nest_dotted.md @@ -1,19 +1,19 @@ -### Function +# nest_dotted -  **nest_dotted** — transform fields in a record with dotted names to nested records +transform fields in a record with dotted names to nested records -### Synopsis +## Synopsis ``` nest_dotted(val: record) -> record ``` -### Description +## Description The `nest_dotted` function returns a copy of `val` with all dotted field names converted into nested records. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/records/unflatten.md b/book/src/super-sql/functions/records/unflatten.md index c1e9be8667..0b19978855 100644 --- a/book/src/super-sql/functions/records/unflatten.md +++ b/book/src/super-sql/functions/records/unflatten.md @@ -1,21 +1,20 @@ -### Function +# unflatten -  **unflatten** — transform an array of key/value records into a -record +transform an array of key/value records into a record -### Synopsis +## Synopsis ``` unflatten(val: [{key:string|[string],value:any}]) -> record ``` -### Description +## Description The `unflatten` function converts the key/value records in array `val` into a single record. _unflatten_ is the inverse of _flatten_, i.e., `unflatten(flatten(r))` will produce a record identical to `r`. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/strings/grep.md b/book/src/super-sql/functions/strings/grep.md index 1eb7feb7ad..9d2980aed0 100644 --- a/book/src/super-sql/functions/strings/grep.md +++ b/book/src/super-sql/functions/strings/grep.md @@ -1,14 +1,14 @@ -### Function +# grep -  **grep** — search strings inside of values +search strings inside of values -### Synopsis +## Synopsis ``` grep(re: string e: any) -> bool ``` -### Description +## Description The `grep` function searches all of the strings in its input value `e` using the `re` argument, which is a @@ -26,7 +26,7 @@ if a complex type, * for arrays and sets, each element is traversed or descended if a complex type, and * for maps, each key and value is traversed or descended if a complex type. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/strings/join.md b/book/src/super-sql/functions/strings/join.md index 8ff8d2547a..e2d33c9e3f 100644 --- a/book/src/super-sql/functions/strings/join.md +++ b/book/src/super-sql/functions/strings/join.md @@ -1,19 +1,19 @@ -### Function +# join -  **join** — concatenate array of strings with a separator +concatenate array of strings with a separator -### Synopsis +## Synopsis ``` join(val: [string], sep: string) -> string ``` -### Description +## Description The `join` function concatenates the elements of string array `val` to create a single string. The string `sep` is placed between each value in the resulting string. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/strings/levenshtein.md b/book/src/super-sql/functions/strings/levenshtein.md index 83f583ad55..e0ee627d5d 100644 --- a/book/src/super-sql/functions/strings/levenshtein.md +++ b/book/src/super-sql/functions/strings/levenshtein.md @@ -1,20 +1,20 @@ -### Function +# levenshtein -  **levenshtein** — Levenshtein distance +Levenshtein distance -### Synopsis +## Synopsis ``` levenshtein(a: string, b: string) -> int64 ``` -### Description +## Description The `levenshtein` function computes the [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) between strings `a` and `b`. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/strings/lower.md b/book/src/super-sql/functions/strings/lower.md index da8a7c97fd..46c124ec57 100644 --- a/book/src/super-sql/functions/strings/lower.md +++ b/book/src/super-sql/functions/strings/lower.md @@ -1,19 +1,19 @@ -### Function +# lower -  **lower** — convert a string to lower case +convert a string to lower case -### Synopsis +## Synopsis ``` lower(s: string) -> string ``` -### Description +## Description The `lower` function converts all upper case Unicode characters in `s` to lower case and returns the result. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/strings/position.md b/book/src/super-sql/functions/strings/position.md index bc1fe8c30b..ff1261dddc 100644 --- a/book/src/super-sql/functions/strings/position.md +++ b/book/src/super-sql/functions/strings/position.md @@ -1,20 +1,20 @@ -### Function +# position -  **position** — find position of a substring +find position of a substring -### Synopsis +## Synopsis ``` position(s: string, sub: string) -> int64 position(sub: string IN s:string) -> int64 ``` -### Description +## Description The `position` function returns the 1-based index where string `sub` first occurs in string `s`. If `sub` is not a sub-string of `s` then 0 is returned. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/strings/replace.md b/book/src/super-sql/functions/strings/replace.md index d8e822683a..5773bf6f53 100644 --- a/book/src/super-sql/functions/strings/replace.md +++ b/book/src/super-sql/functions/strings/replace.md @@ -1,19 +1,19 @@ -### Function +# replace -  **replace** — replace one string for another +replace one string for another -### Synopsis +## Synopsis ``` replace(s: string, old: string, new: string) -> string ``` -### Description +## Description The `replace` function substitutes all instances of the string `old` that occur in string `s` with the string `new`. -### Example +## Example --- diff --git a/book/src/super-sql/functions/strings/split.md b/book/src/super-sql/functions/strings/split.md index 02ad8833d0..645608547c 100644 --- a/book/src/super-sql/functions/strings/split.md +++ b/book/src/super-sql/functions/strings/split.md @@ -1,20 +1,20 @@ -### Function +# split -  **split** — slice a string into an array of strings +slice a string into an array of strings -### Synopsis +## Synopsis ``` split(s: string, sep: string) -> [string] ``` -### Description +## Description The `split` function slices string `s` into all substrings separated by the string `sep` appearing in `s` and returns an array of the substrings spanning those separators. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/strings/substring.md b/book/src/super-sql/functions/strings/substring.md index 7be6321f91..fcdbe1211e 100644 --- a/book/src/super-sql/functions/strings/substring.md +++ b/book/src/super-sql/functions/strings/substring.md @@ -1,14 +1,14 @@ -### Function +# substring -  **substring** — slice strings with SQL substring function +slice strings with SQL substring function -### Synopsis +## Synopsis ``` substring(s: string [ FROM start: number ] [ FOR len: number ]) -> string ``` -### Description +## Description The `substring` function returns a slice of a string using the anachronistic SQL syntax which includes the `FROM` and `FOR` keywords @@ -24,7 +24,7 @@ a [pragma](../../declarations/pragmas.md) as with > [Slice expressions](../../expressions/slices.md) should be used instead > and are best practice. -### Examples +## Examples --- _Simple substring call from in a SQL operator_ diff --git a/book/src/super-sql/functions/strings/trim.md b/book/src/super-sql/functions/strings/trim.md index 4b81b862db..a58bdeb05e 100644 --- a/book/src/super-sql/functions/strings/trim.md +++ b/book/src/super-sql/functions/strings/trim.md @@ -1,19 +1,19 @@ -### Function +# trim -  **trim** — strip leading and trailing whitespace +strip leading and trailing whitespace -### Synopsis +## Synopsis ``` trim(s: string) -> string ``` -### Description +## Description The `trim` function strips all leading and trailing whitespace from string argument `s` and returns the result. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/strings/upper.md b/book/src/super-sql/functions/strings/upper.md index 39b107e89b..a447b09219 100644 --- a/book/src/super-sql/functions/strings/upper.md +++ b/book/src/super-sql/functions/strings/upper.md @@ -1,19 +1,19 @@ -### Function +# upper -  **upper** — convert a string to upper case +convert a string to upper case -### Synopsis +## Synopsis ``` upper(s: string) -> string ``` -### Description +## Description The `upper` function converts all lower case Unicode characters in `s` to upper case and returns the result. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/time/bucket.md b/book/src/super-sql/functions/time/bucket.md index 2210d0ffbd..02385b82fe 100644 --- a/book/src/super-sql/functions/time/bucket.md +++ b/book/src/super-sql/functions/time/bucket.md @@ -1,22 +1,22 @@ -### Function +# bucket -  **bucket** — quantize a time or duration value into buckets of equal time spans +quantize a time or duration value into buckets of equal time spans -### Synopsis +## Synopsis ``` bucket(val: time, span: duration|number) -> time bucket(val: duration, span: duration|number) -> duration ``` -### Description +## Description The `bucket` function quantizes a time or duration `val` (or value that can be coerced to time) into buckets that are equally spaced as specified by `span` where the bucket boundary aligns with 0. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/time/date_part.md b/book/src/super-sql/functions/time/date_part.md index 78e90746f6..4597f9b6c0 100644 --- a/book/src/super-sql/functions/time/date_part.md +++ b/book/src/super-sql/functions/time/date_part.md @@ -1,14 +1,14 @@ -### Function +# date_part -  **date_part** — return a specified part of a time value +return a specified part of a time value -### Synopsis +## Synopsis ``` date_part(part: string, ts: time) -> int64 ``` -### Description +## Description The `date_part` function accepts a [`string`](../../types/string.md) argument `part` and a [`time`](../../types/time.md) value `ts` and returns an [`int64`](../../types/numbers.md) representing the part of the date requested. @@ -27,7 +27,7 @@ Valid values for `part` are: |`"second"` |The seconds field (0-59) | |`"year"` |The year field | -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/time/now.md b/book/src/super-sql/functions/time/now.md index 8dc7753b14..31f9b8c59e 100644 --- a/book/src/super-sql/functions/time/now.md +++ b/book/src/super-sql/functions/time/now.md @@ -1,14 +1,14 @@ -### Function +# now -  **now** — the current time +the current time -### Synopsis +## Synopsis ``` now() -> time ``` -### Description +## Description The `now` function takes no arguments and returns the current UTC time as a value of type `time`. @@ -21,7 +21,7 @@ switch ( ) ``` -### Examples +## Examples _Running this command_ ``` diff --git a/book/src/super-sql/functions/time/strftime.md b/book/src/super-sql/functions/time/strftime.md index 8cbaae7621..2429da9477 100644 --- a/book/src/super-sql/functions/time/strftime.md +++ b/book/src/super-sql/functions/time/strftime.md @@ -1,13 +1,15 @@ -### Function +# strftime -  **strftime** — format time values +format time values + +## Synopsis -### Synopsis ``` strftime(format: string, t: time) -> string ``` -### Description +## Description + The `strftime` function returns a string representation of time `t` as specified by the provided string `format`. `format` is a string containing format directives that dictate how the time string is @@ -55,7 +57,7 @@ These directives are supported: | %z | +hhmm or -hhmm numeric timezone (that is, the hour and minute offset from UTC) | +0000 | | %% | A literal '%' character | % | -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/types/cast.md b/book/src/super-sql/functions/types/cast.md index 68bace6503..0d4f451dc4 100644 --- a/book/src/super-sql/functions/types/cast.md +++ b/book/src/super-sql/functions/types/cast.md @@ -1,15 +1,15 @@ -### Function +# cast -  **cast** — convert a value to a different type +convert a value to a different type -### Synopsis +## Synopsis ``` cast(val: any, target: type) -> any cast(val: any, name: string) -> any ``` -### Description +## Description The `cast` function implements a [cast](../../expressions/cast.md) where the target of the cast is a [type value](../../types/type.md) instead of a type. @@ -27,7 +27,7 @@ If errors are encountered, then some or all of the resulting value will be embedded with structured errors and the result does not have the target type. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/types/is.md b/book/src/super-sql/functions/types/is.md index e3bbac9887..9d0e794c62 100644 --- a/book/src/super-sql/functions/types/is.md +++ b/book/src/super-sql/functions/types/is.md @@ -1,18 +1,19 @@ -### Function +# is -  **is** — test a value's type +test a value's type + +## Synopsis -### Synopsis ``` is(val: any, t: type) -> bool ``` -### Description +## Description The `is` function returns true if the argument `val` is of type `t`. The _is_ function is shorthand for `typeof(val)==t`. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/types/kind.md b/book/src/super-sql/functions/types/kind.md index 6259b39da9..5e7df39310 100644 --- a/book/src/super-sql/functions/types/kind.md +++ b/book/src/super-sql/functions/types/kind.md @@ -1,20 +1,20 @@ -### Function +# kind -  **kind** — return a value's type category +return a value's type category -### Synopsis +## Synopsis ``` kind(val: any) -> string ``` -### Description +## Description The `kind` function returns the category of the type of `v` as a string, e.g., "record", "set", "primitive", etc. If `v` is a type value, then the type category of the referenced type is returned. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/types/nameof.md b/book/src/super-sql/functions/types/nameof.md index 1e1c59ff6f..41c51fb601 100644 --- a/book/src/super-sql/functions/types/nameof.md +++ b/book/src/super-sql/functions/types/nameof.md @@ -1,19 +1,19 @@ -### Function +# nameof -  **nameof** — the name of a named type +the name of a named type -### Synopsis +## Synopsis ``` nameof(val: any) -> string ``` -### Description +## Description The `nameof` function returns the type name of `val` as a string if `val` is a named type. Otherwise, it returns `error("missing")`. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/types/typename.md b/book/src/super-sql/functions/types/typename.md index 559912c132..148b486af0 100644 --- a/book/src/super-sql/functions/types/typename.md +++ b/book/src/super-sql/functions/types/typename.md @@ -1,20 +1,20 @@ -### Function +# typename -  **typename** — look up and return a named type +look up and return a named type -### Synopsis +## Synopsis ``` typename(name: string) -> type ``` -### Description +## Description The `typename` function returns the [type](../../types/intro.md) of the [named type](../../types/named.md) given by `name` if it exists. Otherwise, `error("missing")` is returned. -### Examples +## Examples --- diff --git a/book/src/super-sql/functions/types/typeof.md b/book/src/super-sql/functions/types/typeof.md index 8254e4bfc3..e5c2c242b4 100644 --- a/book/src/super-sql/functions/types/typeof.md +++ b/book/src/super-sql/functions/types/typeof.md @@ -1,20 +1,20 @@ -### Function +# typeof -  **typeof** — the type of a value +the type of a value -### Synopsis +## Synopsis ``` typeof(val: any) -> type ``` -### Description +## Description The `typeof` function returns the [type](../../types/intro.md) of its argument `val`. Types are first class so the returned type is also a value. The type of a type is type [`type`](../../types/type.md). -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/aggregate.md b/book/src/super-sql/operators/aggregate.md index d04e88388f..ec8ac7276a 100644 --- a/book/src/super-sql/operators/aggregate.md +++ b/book/src/super-sql/operators/aggregate.md @@ -1,8 +1,8 @@ -### Operator +# aggregate -[🎲](../intro.md#data-order)  **aggregate** — execute aggregate functions with optional grouping expressions +[🎲](../intro.md#data-order)  execute aggregate functions with optional grouping expressions -### Synopsis +## Synopsis ``` [aggregate] [, ... ] [ by [, ... ] ] @@ -20,7 +20,7 @@ having the form: [ := ] ``` -### Description +## Description The `aggregate` operator applies [aggregate functions](../aggregates/intro.md) to @@ -69,7 +69,7 @@ and the results merged into final results using an external merge sort. >[!NOTE] > Spilling is not yet implemented for the vectorized runtime. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/assert.md b/book/src/super-sql/operators/assert.md index a0fa0d919d..93fe1e72aa 100644 --- a/book/src/super-sql/operators/assert.md +++ b/book/src/super-sql/operators/assert.md @@ -1,19 +1,19 @@ -### Operator +# assert -[✅](../intro.md#data-order)  **assert** — test a predicate and produce errors on failure +[✅](../intro.md#data-order)  test a predicate and produce errors on failure -### Synopsis +## Synopsis ``` assert ``` -### Description +## Description The `assert` operator evaluates the Boolean expression `` for each input value, producing its input value if `` evaluates to true or a structured error if it does not. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/count.md b/book/src/super-sql/operators/count.md index 471ff8fdcf..5209250336 100644 --- a/book/src/super-sql/operators/count.md +++ b/book/src/super-sql/operators/count.md @@ -1,16 +1,16 @@ -### Operator +# count -[✅](../intro.md#data-order)  **count** — emit records containing a running count of input values +[✅](../intro.md#data-order)  emit records containing a running count of input values >[!TIP] > For a final count of all input values, see the [count](../aggregates/count.md) aggregate function. -### Synopsis +## Synopsis ``` count [ ] ``` -### Description +## Description The `count` operator produces records that include a running count of its input values. @@ -23,7 +23,7 @@ If the optional `` is absent, the output record is created with a [derived field name](../types/record.md#derived-field-names) resulting in the equivalent of `count {that:this,count}`. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/cut.md b/book/src/super-sql/operators/cut.md index fec80eb213..b995077ce6 100644 --- a/book/src/super-sql/operators/cut.md +++ b/book/src/super-sql/operators/cut.md @@ -1,8 +1,8 @@ -### Operator +# cut -[✅](../intro.md#data-order)  **cut** — extract subsets of record fields into new records +[✅](../intro.md#data-order)  extract subsets of record fields into new records -### Synopsis +## Synopsis ``` cut [, ...] @@ -13,7 +13,7 @@ having the form: [ := ] ``` -### Description +## Description The `cut` operator extracts values from each input record in the form of one or more [field assignments](intro.md#field-assignment), @@ -46,7 +46,7 @@ Note that when the field references are all top level, values {: [, :...]} ``` -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/drop.md b/book/src/super-sql/operators/drop.md index 0abb8d2889..1fbc574f5b 100644 --- a/book/src/super-sql/operators/drop.md +++ b/book/src/super-sql/operators/drop.md @@ -1,20 +1,20 @@ -### Operator +# drop -[✅](../intro.md#data-order)  **drop** — drop fields from record values +[✅](../intro.md#data-order)  drop fields from record values -### Synopsis +## Synopsis ``` drop [, ...] ``` -### Description +## Description The `drop` operator removes one or more fields from records in the input sequence and copies the modified records to its output. If a field to be dropped is not present, then no effect for the field occurs. In particular, non-record values are copied unmodified. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/fork.md b/book/src/super-sql/operators/fork.md index d8ffec4396..1dddb1f259 100644 --- a/book/src/super-sql/operators/fork.md +++ b/book/src/super-sql/operators/fork.md @@ -1,8 +1,8 @@ -### Operator +# fork -[🎲](../intro.md#data-order)  **fork** — copy values to parallel pipeline branches +[🎲](../intro.md#data-order)  copy values to parallel pipeline branches -### Synopsis +## Synopsis ``` fork @@ -10,7 +10,8 @@ fork ( ) ... ``` -### Description + +## Description The `fork` operator copies each input value to multiple, parallel branches of the pipeline. @@ -20,7 +21,7 @@ If the downstream operator expects a single input, then the output branches are combined without preserving order. Order may be reestablished by applying a [`sort`](sort.md) at the merge point. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/from.md b/book/src/super-sql/operators/from.md index b7c019753a..e57bfbab30 100644 --- a/book/src/super-sql/operators/from.md +++ b/book/src/super-sql/operators/from.md @@ -1,6 +1,6 @@ # from -[✅](../intro.md#data-order)[🎲](../intro.md#data-order) source data from databases, files, or URLs +[✅](../intro.md#data-order)[🎲](../intro.md#data-order)  source data from databases, files, or URLs ## Synopsis diff --git a/book/src/super-sql/operators/fuse.md b/book/src/super-sql/operators/fuse.md index 0256cb9919..f21cb738b8 100644 --- a/book/src/super-sql/operators/fuse.md +++ b/book/src/super-sql/operators/fuse.md @@ -1,13 +1,14 @@ -### Operator +# fuse -[✅](../intro.md#data-order)  **fuse** — coerce all input values into a fused type +[✅](../intro.md#data-order)  coerce all input values into a fused type -### Synopsis +## Synopsis ``` fuse ``` -### Description + +## Description The `fuse` operator computes a [fused type](../type-fusion.md) over all of its input then casts all values in the input to the fused type. @@ -23,7 +24,7 @@ Because all values of the input must be read to compute the fused type, >[!NOTE] > Spilling is not yet implemented for the vectorized runtime. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/head.md b/book/src/super-sql/operators/head.md index a3c36ea812..323bffabdf 100644 --- a/book/src/super-sql/operators/head.md +++ b/book/src/super-sql/operators/head.md @@ -1,14 +1,14 @@ -### Operator +# head -[✅](../intro.md#data-order)  **head** — copy leading values of input sequence +[✅](../intro.md#data-order)  copy leading values of input sequence -### Synopsis +## Synopsis ``` head [ ] limit [ ] ``` -### Description +## Description The `head` operator copies the first N values from its input to its output and ends the sequence thereafter. N is given by ``, a compile-time @@ -18,7 +18,7 @@ is not provided, the value of N defaults to `1`. For compatibility with other pipe SQL dialects, `limit` is an alias for the `head` operator. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/intro.md b/book/src/super-sql/operators/intro.md index a36a052835..6fc0613076 100644 --- a/book/src/super-sql/operators/intro.md +++ b/book/src/super-sql/operators/intro.md @@ -1,4 +1,4 @@ -## Operators +# Operators The components of a SuperSQL [pipeline](../intro.md#pipe-queries) are called pipe operators. Each operator is identified by its name @@ -37,7 +37,7 @@ While the output order of parallel branches is [undefined](../intro.md#data-orde order may be reestablished by applying a [`sort`](sort.md) at the merge point of the `switch` or `fork`. -### Field Assignment +## Field Assignment Several pipe operators manipulate records by modifying fields or by creating new records from component expressions. @@ -85,7 +85,7 @@ aggregate count:=count() by upper:=upper(key) put lower:=lower(s), c:=a.b.c, `x+1`:=x+1 ``` -### Call +## Call In addition to the built-in operators, [new operators can be declared](../declarations/operators.md) @@ -104,7 +104,7 @@ of parameters appearing in the operator declaration. The `call` keyword is optional when the operator name does not syntactically conflict with other operator syntax. -### Shortcuts +## Shortcuts When interactively composing queries (e.g., within [SuperDB Desktop](https://zui.brimdata.io)), it is often convenient to use syntactic shortcuts to quickly craft queries for diff --git a/book/src/super-sql/operators/join.md b/book/src/super-sql/operators/join.md index c4805608e5..e586ef83bd 100644 --- a/book/src/super-sql/operators/join.md +++ b/book/src/super-sql/operators/join.md @@ -1,8 +1,8 @@ -### Operator +# join -[🎲](../intro.md#data-order)  **join** — combine data from two inputs using a join predicate +[🎲](../intro.md#data-order)  combine data from two inputs using a join predicate -### Synopsis +## Synopsis ``` @@ -21,7 +21,7 @@ | cross join [as { , }] ``` -### Description +## Description The `join` operator combines values from two inputs according to the Boolean-valued `` into two-field records, one field for each side of the join. @@ -73,7 +73,7 @@ like any other record without complex scoping logic. If relational scoping is desired, a SQL [`JOIN`](../sql/join.md) clause can be used instead. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/load.md b/book/src/super-sql/operators/load.md index b4518a1602..dacbaae61a 100644 --- a/book/src/super-sql/operators/load.md +++ b/book/src/super-sql/operators/load.md @@ -1,8 +1,8 @@ -### Operator +# load -[✅](../intro.md#data-order)  **load** — add and commit data to a pool +[✅](../intro.md#data-order)  add and commit data to a pool -### Synopsis +## Synopsis ``` load [@] [ ( [author ] [message ] [meta ] ) ] @@ -13,7 +13,7 @@ load [@] [ ( [author ] [message ] [meta ] ) >[database](../../command/db.md) and is not available when running >[`super`](../../command/super.md) detached from a database. -### Description +## Description The `load` operator populates the specified `` with the values it receives as input. Much like how [`super db load`](../../command/db-load.md) @@ -26,7 +26,7 @@ to an existing branch of that name, otherwise the `main` branch is assumed. The `author`, `message`, and `meta` strings may also be provided to further describe the committed data, similar to the same `super db load` options. -### Input Data +## Input Data Examples below assume the existence of a database created and populated by the following commands: @@ -53,7 +53,7 @@ coinflips@main coinflips@onlytails ``` -### Examples +## Examples _Modify some values, load them into the `main` branch of our empty `bigflips` pool, and see what was loaded_ ```mdtest-command diff --git a/book/src/super-sql/operators/pass.md b/book/src/super-sql/operators/pass.md index b6062c6013..12e5d440fc 100644 --- a/book/src/super-sql/operators/pass.md +++ b/book/src/super-sql/operators/pass.md @@ -1,19 +1,20 @@ -### Operator +# pass -[✅](../intro.md#data-order)  **pass** — copy input values to output +[✅](../intro.md#data-order)  copy input values to output -### Synopsis +## Synopsis ``` pass ``` -### Description + +## Description The `pass` operator outputs a copy of each input value. It is typically used with operators that handle multiple branches of the pipeline such as [`fork`](fork.md) and [`join`](join.md). -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/put.md b/book/src/super-sql/operators/put.md index 8bff6f0c4a..b8c44e805e 100644 --- a/book/src/super-sql/operators/put.md +++ b/book/src/super-sql/operators/put.md @@ -1,8 +1,9 @@ -### Operator +# put -[✅](../intro.md#data-order)  **put** — add or modify fields of records +[✅](../intro.md#data-order)  add or modify fields of records + +## Synopsis -### Synopsis ``` [put] [, ...] ``` @@ -11,7 +12,8 @@ having the form: ``` [ := ] ``` -### Description + +## Description The `put` operator modifies its input with one or more [field assignments](intro.md#field-assignment). @@ -51,7 +53,7 @@ using a spread operator of the form: values {...this, : [, :...]} ``` -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/rename.md b/book/src/super-sql/operators/rename.md index 21ac7439ba..f2d9fdac74 100644 --- a/book/src/super-sql/operators/rename.md +++ b/book/src/super-sql/operators/rename.md @@ -1,13 +1,14 @@ -### Operator +# rename -[✅](../intro.md#data-order)  **rename** — change the name of record fields +[✅](../intro.md#data-order)  change the name of record fields + +## Synopsis -### Synopsis ``` rename := [, := ...] ``` -### Description +## Description The `rename` operator changes the names of one or more fields in the input records from the right-hand side name to the left-hand side name @@ -27,7 +28,7 @@ If a rename operation conflicts with an existing field name, then the offending record is wrapped in a structured error along with an error message and the error is emitted. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/search.md b/book/src/super-sql/operators/search.md index 1fa4efb05f..9b2e57d592 100644 --- a/book/src/super-sql/operators/search.md +++ b/book/src/super-sql/operators/search.md @@ -1,13 +1,15 @@ -### Operator +# search -[✅](../intro.md#data-order)  **search** — select values based on a search expression +[✅](../intro.md#data-order)  select values based on a search expression + +## Synopsis -### Synopsis ``` search ? ``` -### Description + +## Description The `search` operator provides a traditional keyword experience to SuperSQL along the lines of web search, email search, or log search. @@ -17,7 +19,7 @@ to each input value and emitting all values that match. The `search` keyword can be abbreviated as `?`. -#### Search Expressions +### Search Expressions The search expression syntax is unique to the search operator and provides a hybrid syntax between keyword search and boolean expressions. @@ -30,7 +32,7 @@ a search term is one of: * any [literal](#literal) of a primitive type, or * any [expression predicate](#expression-predicate). -##### Regular Expression +#### Regular Expression A search term may be a [regular expression](../queries.md#regular-expression). @@ -46,7 +48,7 @@ searches for the string `"foo"` or `"bar"` inside of any string entity while ``` searches for the string `"foo|bar"`. -##### Glob +#### Glob A search term may be a [glob](../queries.md#glob). @@ -73,7 +75,7 @@ a*b==c ``` is a Boolean comparison between the product `a*b` and `c`. -##### Keyword +#### Keyword Keywords and string literals are equivalent search terms so it is often easier to quote a string search term instead of using escapes in a keyword. @@ -113,7 +115,7 @@ For example, the simplest SuperSQL query is perhaps a single keyword search, e.g As above, this query searches the implied input for values that contain the string "foo". -##### Literal +#### Literal Search terms representing non-string values search for both an exact match for the given value as well as a string search for the term exactly @@ -155,7 +157,7 @@ the [in](../expressions/containment.md) operator, e.g., {s:"foo"} in this ``` -##### Expression Predicate +#### Expression Predicate Any Boolean-valued [function](../functions/intro.md) like [`is`](../functions/types/is.md), @@ -174,7 +176,7 @@ is a valid search expression but ``` is not. -##### Boolean Logic +#### Boolean Logic Search terms may be combined into boolean expressions using logical operators `and`, `or`, `not`, and `!`. `and` may be elided; i.e., concatenation of @@ -202,7 +204,7 @@ means grep("foo", this) and (grep("bar", this) or grep("baz", this)) ``` -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/shapes.md b/book/src/super-sql/operators/shapes.md index a2fbd86c98..542439714a 100644 --- a/book/src/super-sql/operators/shapes.md +++ b/book/src/super-sql/operators/shapes.md @@ -1,12 +1,14 @@ -### Operator +# shapes -[🎲](../intro.md#data-order)  **shapes** — aggregate sample values by type +[🎲](../intro.md#data-order)  aggregate sample values by type + +## Synopsis -### Synopsis ``` shapes [ ] ``` -### Description + +## Description The `shapes` operator aggregates the values computed by `` by type and produces an arbitrary sample value for each unique type @@ -21,7 +23,7 @@ where is not null If `` is not present, then `this` is presumed. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/skip.md b/book/src/super-sql/operators/skip.md index 0c43daf5b2..db0cb9fff9 100644 --- a/book/src/super-sql/operators/skip.md +++ b/book/src/super-sql/operators/skip.md @@ -1,19 +1,20 @@ -### Operator +# skip -[✅](../intro.md#data-order)  **skip** — skip leading values of input sequence +[✅](../intro.md#data-order)  skip leading values of input sequence -### Synopsis +## Synopsis ``` skip ``` -### Description + +## Description The `skip` operator skips the first N values from its input. N is given by ``, a compile-time constant expression that evaluates to a positive integer. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/sort.md b/book/src/super-sql/operators/sort.md index 8031ef3e71..9f7b435da4 100644 --- a/book/src/super-sql/operators/sort.md +++ b/book/src/super-sql/operators/sort.md @@ -1,14 +1,15 @@ -### Operator +# sort -[🔀](../intro.md#data-order)  **sort** — sort values +[🔀](../intro.md#data-order)  sort values -### Synopsis +## Synopsis ``` sort [-r] [ [asc|desc] [nulls {first|last}] [, [asc|desc] [nulls {first|last}] ...]] order by [-r] [ [asc|desc] [nulls {first|last}] [, [asc|desc] [nulls {first|last}] ...]] ``` -### Description + +## Description The `sort` operator sorts its input by reading all values until the end of input, sorting the values according to the provided sort expression(s), and emitting @@ -63,7 +64,7 @@ Note that a total order is defined over the space of all values even between values of different types so sort order is always well-defined even when comparing heterogeneously typed values. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/switch.md b/book/src/super-sql/operators/switch.md index b278ae3928..705da9e960 100644 --- a/book/src/super-sql/operators/switch.md +++ b/book/src/super-sql/operators/switch.md @@ -1,8 +1,8 @@ -### Operator +# switch -[🎲](../intro.md#data-order)  **switch** — route values based on cases +[🎲](../intro.md#data-order)  route values based on cases -### Synopsis +## Synopsis ``` switch @@ -17,7 +17,8 @@ switch ... [ default ( ) ] ``` -### Description + +## Description The `switch` operator routes input values to parallel pipe branches based on case matching. @@ -43,7 +44,7 @@ If the downstream operator expects a single input, then the output branches are combined without preserving order. Order may be reestablished by applying a [`sort`](sort.md) at the merge point. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/tail.md b/book/src/super-sql/operators/tail.md index 19cde4235c..6616cbeea3 100644 --- a/book/src/super-sql/operators/tail.md +++ b/book/src/super-sql/operators/tail.md @@ -1,20 +1,21 @@ -### Operator +# tail -[✅](../intro.md#data-order)  **tail** — copy trailing values of input sequence +[✅](../intro.md#data-order)  copy trailing values of input sequence -### Synopsis +## Synopsis ``` tail [ ] ``` -### Description + +## Description The `tail` operator copies the last N values from its input to its output and ends the sequence thereafter. N is given by ``, a compile-time constant expression that evaluates to a positive integer. If `` is not provided, the value of N defaults to `1`. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/top.md b/book/src/super-sql/operators/top.md index 286c5bc27e..4b2cf6fdb6 100644 --- a/book/src/super-sql/operators/top.md +++ b/book/src/super-sql/operators/top.md @@ -1,13 +1,14 @@ -### Operator +# top -[🔀](../intro.md#data-order)  **top** — output the first N sorted values of input sequence +[🔀](../intro.md#data-order)  output the first N sorted values of input sequence -### Synopsis +## Synopsis ``` top [-r] [ [ [asc|desc] [nulls {first|last}] [, [asc|desc] [nulls {first|last}] ...]]] ``` -### Description + +## Description The `top` operator returns the first N values from a sequence sorted according to the provided sort expressions. N is given by ``, a compile-time @@ -22,7 +23,7 @@ selected using the same heuristic as [`sort`](sort.md). intensive because only the first N values are stored in memory (i.e., subsequent values are discarded). -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/uniq.md b/book/src/super-sql/operators/uniq.md index 1abceb4149..a121c3816b 100644 --- a/book/src/super-sql/operators/uniq.md +++ b/book/src/super-sql/operators/uniq.md @@ -1,13 +1,14 @@ -### Operator +# uniq -[✅](../intro.md#data-order)  **uniq** — deduplicate adjacent values +[✅](../intro.md#data-order)  deduplicate adjacent values -### Synopsis +## Synopsis ``` uniq [-c] ``` -### Description + +## Description Inspired by the traditional Unix shell command of the same name, the `uniq` operator copies its input to its output but removes duplicate values @@ -21,7 +22,7 @@ type signature `{value:any,count:int64}`, where the `value` field contains the unique value and the `count` field indicates the number of consecutive duplicates that occurred in the input for that output value. -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/unnest.md b/book/src/super-sql/operators/unnest.md index 740793c915..c9fe213fa2 100644 --- a/book/src/super-sql/operators/unnest.md +++ b/book/src/super-sql/operators/unnest.md @@ -1,14 +1,14 @@ -### Operator +# unnest -[✅](../intro.md#data-order)  **unnest** — expand nested array as values optionally into a subquery +[✅](../intro.md#data-order)  expand nested array as values optionally into a subquery -### Synopsis +## Synopsis ``` unnest [ into ( ) ] ``` -### Description +## Description The `unnest` operator transforms the given expression `` into a new ordered sequence of derived values. @@ -66,7 +66,7 @@ For example, if `this` is a record, it can be unnested with `unnest flatten(this >[!NOTE] > Support for map types in `flatten` is not yet implemented. -### Errors +## Errors If a value encountered by `unnest` does not have either of the forms defined above, then an error results as follows: @@ -84,7 +84,7 @@ or error({message:"unnest: encountered record without an array/set type for second field",on:}) ``` -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/values.md b/book/src/super-sql/operators/values.md index 5cb4e7b2ab..bc6f635a1f 100644 --- a/book/src/super-sql/operators/values.md +++ b/book/src/super-sql/operators/values.md @@ -1,13 +1,14 @@ -### Operator +# values -[✅](../intro.md#data-order)  **values** — emit values from expressions +[✅](../intro.md#data-order)  emit values from expressions -### Synopsis +## Synopsis ``` [values] [, ...] ``` -### Description + +## Description The `values` operator produces output values by evaluating one or more comma-separated @@ -66,7 +67,7 @@ values {x:2,y:1},{x:4,y:2},{x:6,y:3} | values x+y, x-y ``` -### Examples +## Examples --- diff --git a/book/src/super-sql/operators/where.md b/book/src/super-sql/operators/where.md index e0fe2325a0..bcd48367d3 100644 --- a/book/src/super-sql/operators/where.md +++ b/book/src/super-sql/operators/where.md @@ -1,12 +1,14 @@ -### Operator +# where -[✅](../intro.md#data-order)  **where** — select values based on a Boolean expression +[✅](../intro.md#data-order)  select values based on a Boolean expression + +## Synopsis -### Synopsis ``` [where] ``` -### Description + +## Description The `where` operator filters its input by applying a Boolean [expression](../expressions/intro.md) `` @@ -19,7 +21,7 @@ When SuperSQL queries are run interactively, it is highly convenient to be able the "where" keyword, but when `where` filters appear in query source files, it is good practice to include the optional keyword. -### Examples +## Examples --- diff --git a/book/src/super-sql/queries.md b/book/src/super-sql/queries.md index 320327bce6..d13e8b00f9 100644 --- a/book/src/super-sql/queries.md +++ b/book/src/super-sql/queries.md @@ -1,4 +1,4 @@ -## Queries +# Queries The syntactical structure of a query consists of * an optional concatenation of [declarations](declarations/intro.md), @@ -19,7 +19,7 @@ While operators consume a sequence of values, the expressions embedded within an operator are typically evaluated once for each value processed by the operator. -### Scope +## Scope A scope is formed by enclosing a set of [declarations](declarations/intro.md) along with an operator sequence in the parentheses having the structure: @@ -79,7 +79,7 @@ no such field "PI" at line 5, column 15: ~~ ``` -### Identifiers +## Identifiers Identifiers are names that arise in many syntactical structures and may be any sequence of UTF-8 characters. When not quoted, @@ -102,7 +102,7 @@ in a SQL expression, simply use double quotes, i.e., `"this"`. An unquoted identifier cannot be `true`, `false`, `null`, `NaN`, or `Inf`. -### Patterns +## Patterns For ease of use, several operators utilize a syntax for string entities outside of expression syntax where quotation marks for such entities @@ -125,7 +125,7 @@ regular expressions in expressions as in where len(regexp(r'\w+(foo|bar)', this)) > 0 ``` -#### Regular Expression +### Regular Expression Regular expressions follow the syntax and semantics of the [RE2 regular expression library](https://github.com/google/re2), @@ -155,7 +155,7 @@ prefixed and suffixed with a `/`, e.g., ``` matches the string `"foo"` or `"bar"`. -#### Glob +### Glob Globs provide a convenient short-hand for regular expressions and follow the familiar pattern of "file globbing" supported by Unix shells. @@ -172,7 +172,7 @@ _ . : / % # @ ~ * ``` A glob cannot begin with a digit. -#### Text Entity +### Text Entity A text entity represents a string where quotes can be omitted for certain common use cases regarding URLs and file paths. @@ -189,7 +189,7 @@ Specifically, a text entity is one of: If a URL does not meet the constraints of the simple URL rule, e.g., containing a `:` or `&`, then it must be quoted. -### Comments +## Comments Single-line comments are SQL style begin with two dashes `--` and end at the subsequent newline. diff --git a/book/src/super-sql/type-fusion.md b/book/src/super-sql/type-fusion.md index 8bffb545cd..098033dbbd 100644 --- a/book/src/super-sql/type-fusion.md +++ b/book/src/super-sql/type-fusion.md @@ -1,4 +1,4 @@ - ## Type Fusion +# Type Fusion [_Type fusion_](https://openproceedings.org/2017/conf/edbt/paper-62.pdf) is a process by which a set of input types is merged together @@ -59,7 +59,7 @@ Unfortunately, when data leaves a super-structured format using type fusion to accomplish this, the original data must be altered to fit into the rigid structure of these output formats. -### The Mechanism +## The Mechanism The foundation of type fusion is to merge record types by their field names while other types are generally merged with sum types. @@ -95,7 +95,7 @@ are fused as {a:[int64|string],b:|[string]|} ``` -### Detailed Algorithm +## Detailed Algorithm Type fusion may be formally defined as a function over types: ``` diff --git a/book/src/super-sql/types/array.md b/book/src/super-sql/types/array.md index 59d790c03a..a2f6905f8c 100644 --- a/book/src/super-sql/types/array.md +++ b/book/src/super-sql/types/array.md @@ -1,4 +1,4 @@ -### Arrays +# Arrays Arrays conform to the [array type](../../formats/model.md#22-array) @@ -34,7 +34,7 @@ constructing instances using [_array expressions_](#array-expressions) or other SuperSQL functions that produce arrays. -#### Array Expressions +## Array Expressions Array values are constructed from an _array expression_ that is comprised of zero or more comma-separated elements contained in brackets: @@ -62,7 +62,7 @@ When the expressions result in values of non-uniform type, then the types of the array elements become a sum type of the types present, tied together with the corresponding [union type](union.md). -#### Examples +## Examples --- ```mdtest-spq # spq diff --git a/book/src/super-sql/types/bool.md b/book/src/super-sql/types/bool.md index ffb429052b..85de150ea0 100644 --- a/book/src/super-sql/types/bool.md +++ b/book/src/super-sql/types/bool.md @@ -1,11 +1,11 @@ -### Booleans +# Booleans The `bool` type represents a type that has the values `true`, `false`, or `null`. For backward compatibility with SQL, `BOOLEAN` is a syntactic alias for type `bool`. -#### Examples +## Examples --- @@ -62,4 +62,4 @@ aggregate andA:=and(a), andB:=and(b), orA:=or(a), orB:=or(b) {a:false,b:true} # expected output {andA:false,andB:false,orA:false,orB:true} -``` \ No newline at end of file +``` diff --git a/book/src/super-sql/types/bytes.md b/book/src/super-sql/types/bytes.md index 0b0b24e5ce..592c53e009 100644 --- a/book/src/super-sql/types/bytes.md +++ b/book/src/super-sql/types/bytes.md @@ -1,4 +1,4 @@ -### Bytes +# Bytes The `bytes` type represents an arbitrary sequence of 8-bit bytes. @@ -9,7 +9,7 @@ An empty bytes value is simply `0x` followed by no digits. For backward compatibility with SQL, `BYTEA` is a syntactic alias for type `bytes`. -#### Examples +## Examples --- ```mdtest-spq # spq diff --git a/book/src/super-sql/types/enum.md b/book/src/super-sql/types/enum.md index 13adc67d67..208148a9f9 100644 --- a/book/src/super-sql/types/enum.md +++ b/book/src/super-sql/types/enum.md @@ -1,4 +1,4 @@ -### Enums +# Enums The `enum` type represents a set of symbols, e.g., to represent categories by name. @@ -26,7 +26,7 @@ Enum serialization in the SUP format is fairly verbose as the set of symbols must be enumerated anywhere the type appears. In the binary formats of BSUP and CSUP, the enum symbols are encoded efficiently just once. -#### Examples +## Examples --- ```mdtest-spq {data-layout="stacked"} diff --git a/book/src/super-sql/types/error.md b/book/src/super-sql/types/error.md index 61ec4d00d5..77dc87bf09 100644 --- a/book/src/super-sql/types/error.md +++ b/book/src/super-sql/types/error.md @@ -1,4 +1,4 @@ -### Errors +# Errors Errors in SuperSQL are _first class_ and conform with the [error type](../../formats/model.md#27-error) in the @@ -49,7 +49,7 @@ produces [1,2,3] ``` -#### Structured Errors +## Structured Errors First-class errors are particularly useful for creating structured errors. When a SuperSQL query encounters a problematic condition, @@ -92,7 +92,7 @@ but having a first-class data type to manage them all while allowing them to peacefully coexist with valid production data is a novel and useful approach that SuperSQL enables. -### Missing and Quiet +## Missing and Quiet SuperDB's heterogeneous data model allows for queries that operate over different types of data whose structure and type @@ -156,7 +156,7 @@ values error("quiet") ``` produces no output. -#### Examples +## Examples --- diff --git a/book/src/super-sql/types/intro.md b/book/src/super-sql/types/intro.md index 80d3dc099c..6824a69956 100644 --- a/book/src/super-sql/types/intro.md +++ b/book/src/super-sql/types/intro.md @@ -1,4 +1,4 @@ -## Types +# Types SuperSQL has a comprehensive types system that adheres to the [super-structured data model](../../formats/model.md) diff --git a/book/src/super-sql/types/map.md b/book/src/super-sql/types/map.md index 27e5a27aac..ea50540402 100644 --- a/book/src/super-sql/types/map.md +++ b/book/src/super-sql/types/map.md @@ -1,4 +1,4 @@ -### Maps +# Maps Maps conform to the [map type](../../formats/model.md#24-map) @@ -34,7 +34,7 @@ database data, Parquet values, etc) or by constructing instances using [_map expressions_](#map-expressions) or other SuperSQL functions that produce maps. -#### Map Expressions +## Map Expressions Map values are constructed from a _map expression_ that is comprised of zero or more comma-separated key-value pairs contained in pipe braces: @@ -51,7 +51,7 @@ When the expressions result in values of non-uniform type of either the keys or the values, then their types become a sum type of the types present, tied together with the corresponding [union type](union.md). -#### Examples +## Examples --- ```mdtest-spq # spq diff --git a/book/src/super-sql/types/named.md b/book/src/super-sql/types/named.md index dc7f41ad02..f430e5eee5 100644 --- a/book/src/super-sql/types/named.md +++ b/book/src/super-sql/types/named.md @@ -1,4 +1,4 @@ -### Named Types +# Named Types A named type provides a means to bind a symbolic name to a type and conforms to the @@ -50,7 +50,7 @@ undefined except for the definitions within a single nested value, in which case, the most recent binding in depth-first order is used to resolve a reference to a type name. -#### Examples +## Examples --- diff --git a/book/src/super-sql/types/network.md b/book/src/super-sql/types/network.md index 6b8c62bc97..50dd48a106 100644 --- a/book/src/super-sql/types/network.md +++ b/book/src/super-sql/types/network.md @@ -1,4 +1,4 @@ -### Networks/IPs +# Networks/IPs The `ip` type represents an internet address and supports both IPv4 and IPv6 variations. The `net` type represents an `ip` value @@ -34,7 +34,7 @@ Note that unlike other SQL dialects that require IP addresses and networks to be inside quotation marks, SuperSQL treats these data types as first-class elements that need not be quoted. -#### Examples +## Examples --- ```mdtest-spq # spq diff --git a/book/src/super-sql/types/null.md b/book/src/super-sql/types/null.md index 11585f1818..070cc7601b 100644 --- a/book/src/super-sql/types/null.md +++ b/book/src/super-sql/types/null.md @@ -1,4 +1,4 @@ -### Nulls +# Nulls The null type represents a type that has just one value: the special value `null`. @@ -29,7 +29,7 @@ value, which by definition, is always false, i.e., two unknown values cannot be known to be equal. Instead the [`IS NULL`](../expressions/comparisons.md) operator or [coalesce](../functions/generics/coalesce.md) function should be used. -#### Examples +## Examples --- _The null value_ diff --git a/book/src/super-sql/types/numbers.md b/book/src/super-sql/types/numbers.md index f1af902bf4..723f17bac0 100644 --- a/book/src/super-sql/types/numbers.md +++ b/book/src/super-sql/types/numbers.md @@ -1,4 +1,4 @@ -### Numbers +# Numbers Numbers in SuperSQL follow the customary semantics and syntax of SQL and other programming languages and include: @@ -7,7 +7,7 @@ of SQL and other programming languages and include: * [floating point](#floating-point), and * [decimal](#decimal). -#### Signed Integers +## Signed Integers A 64-bit signed integer literal of type `int64` is formed from an optional minus character (`-`) followed by a sequence of one or more decimal digits @@ -30,7 +30,7 @@ are defined as follows: * `INTEGER` maps to `int32` * `SMALLINT` maps to `int16` -#### Unsigned Integers +## Unsigned Integers A sequence of one or more decimal digits that has a value greater than `2^63 - 1` and less than `2^64` exclusively forms an unsigned 64-bit integer literal. @@ -45,7 +45,7 @@ These unsigned types include: >[!NOTE] > The `uint128` type is not yet implemented in SuperDB. -#### Floating Point +## Floating Point A sequence of one or more decimal digits followed by a decimal point (`.`) followed optionally by one or more decimal digits forms @@ -70,12 +70,12 @@ are defined as follows: >[!NOTE] > The `FLOAT(n)` SQL types are not yet implemented by SuperSQL. -#### Decimal +## Decimal >[!NOTE] > The `decimal` type is not yet implemented in SuperSQL. -#### Coercion +## Coercion Mixed-type numeric values used in expressions are promoted via an implicit cast to the type that is best compatible with an operation or expected input type. @@ -98,7 +98,7 @@ the input values to `sum()` are coerced to `int64` and the result is > Further details of coercion rules are forthcoming in a future > version of this documentation. -#### Examples +## Examples --- diff --git a/book/src/super-sql/types/record.md b/book/src/super-sql/types/record.md index 7d1dca4142..fc00b1fcac 100644 --- a/book/src/super-sql/types/record.md +++ b/book/src/super-sql/types/record.md @@ -1,4 +1,4 @@ -### Records +# Records Records conform to the [record type](../../formats/model.md#21-record) in the @@ -31,7 +31,7 @@ constructing instances using [record expressions](#record-expressions) or other SuperSQL functions that produce records. -#### Record Expressions +## Record Expressions Record values are constructed from a _record expression_ that is comprised of zero or more comma-separated elements contained in braces: @@ -56,7 +56,7 @@ The fields of a record expression are evaluated left to right and when field names collide the rightmost instance of the name determines that field's value. -#### Derived Field Names +## Derived Field Names When an expression is present without a field name, the field name is derived from the expression text as follows: @@ -65,7 +65,7 @@ the field name is derived from the expression text as follows: * for `this`, the name is `that`; * otherwise, the name is the expression text formatted in a canonical form. -#### Examples +## Examples --- diff --git a/book/src/super-sql/types/set.md b/book/src/super-sql/types/set.md index 4346d17a02..c5ef3dd746 100644 --- a/book/src/super-sql/types/set.md +++ b/book/src/super-sql/types/set.md @@ -1,4 +1,4 @@ -### Sets +# Sets Sets conform to the [set type](../../formats/model.md#23-set) @@ -34,7 +34,7 @@ constructing instances using [_set expressions_](#set-expressions) or other SuperSQL functions that produce sets. -#### Set Expressions +## Set Expressions Set values are constructed from a _set expression_ that is comprised of zero or more comma-separated elements contained in pipe brackets: @@ -62,7 +62,7 @@ When the expressions result in values of non-uniform type, then the types of the set elements become a sum type of the types present, tied together with the corresponding [union type](union.md). -#### Examples +## Examples --- ```mdtest-spq # spq diff --git a/book/src/super-sql/types/string.md b/book/src/super-sql/types/string.md index acb55c954a..b3710ba69c 100644 --- a/book/src/super-sql/types/string.md +++ b/book/src/super-sql/types/string.md @@ -1,4 +1,4 @@ -### Strings +# Strings The `string` type represents any valid [UTF-8 string](https://en.wikipedia.org/wiki/UTF-8). @@ -37,7 +37,7 @@ In single-quote strings, the single-quote character must be escaped and in double-quote strings, the double-quote character must be escaped. -#### Raw String +## Raw String Raw strings or _r-strings_ are expressed as the character `r` followed by a single- or double-quoted @@ -52,7 +52,7 @@ r"foo bar" ``` -#### Formatted Strings +## Formatted Strings Formatted strings or [_f-strings_](../expressions/f-strings.md) are expressed @@ -60,7 +60,7 @@ as the character `f` followed by a single- or double-quoted string and may contain embedded expressions denoted within curly braces `{` `}`. -#### Examples +## Examples --- _Various strings_ diff --git a/book/src/super-sql/types/time.md b/book/src/super-sql/types/time.md index 46c5f32955..3a6a680608 100644 --- a/book/src/super-sql/types/time.md +++ b/book/src/super-sql/types/time.md @@ -1,4 +1,4 @@ -### Date/Times +# Date/Times >[!WARNING] > These data types are going to change in a forthcoming release of SuperSQL. diff --git a/book/src/super-sql/types/type.md b/book/src/super-sql/types/type.md index 65c6545147..bffc8cd0a1 100644 --- a/book/src/super-sql/types/type.md +++ b/book/src/super-sql/types/type.md @@ -1,4 +1,4 @@ -### Type Values +# Type Values Types in SuperSQL are _first class_ and conform with the [`type`](../../formats/model.md#1-primitive-types) type in the @@ -50,7 +50,7 @@ exploratory data and then count the shapes of each type of data as follows: search ... | count() by typeof(this) ``` -#### Examples +## Examples --- _Various type examples using f-string and typeof_ diff --git a/book/src/super-sql/types/union.md b/book/src/super-sql/types/union.md index cca68df693..9e3ab90115 100644 --- a/book/src/super-sql/types/union.md +++ b/book/src/super-sql/types/union.md @@ -1,4 +1,4 @@ -### Unions +# Unions The union type provides the foundation for [sum types](https://en.wikipedia.org/wiki/Tagged_union) in SuperSQL. @@ -44,7 +44,7 @@ values typeof([1,"foo"]) ``` results in `<[int64|string]>`. -#### Union Value Semantics +## Union Value Semantics Internally, every union value includes a tag indicating which of its member types the value belongs to along with that actual value. @@ -94,7 +94,7 @@ values typeof(under(1::(int64|string))) ``` results in ``. -#### Union Dispatch +## Union Dispatch Languages with sum types often include a construct to dispatch the union to a case for each of its possible types. @@ -144,7 +144,7 @@ values end ``` -#### Examples +## Examples --- _Cast primitive values to a union type_ ```mdtest-spq