From 4875117e12e08e3b558f72a611950d71c02edbac Mon Sep 17 00:00:00 2001 From: Dave MacLeod <56599343+Dhghomon@users.noreply.github.com> Date: Wed, 28 Aug 2024 22:49:28 +0900 Subject: [PATCH] DOC-243 & DOC-217 : Add range and literals (#782) Co-authored-by: Obinna Ekwuno --- .../surrealql/datamodel/arrays.mdx | 18 ++ .../surrealql/datamodel/closures.mdx | 2 +- .../surrealql/datamodel/datetimes.mdx | 2 +- .../surrealql/datamodel/formatters.mdx | 2 +- .../surrealql/datamodel/futures.mdx | 2 +- .../surrealql/datamodel/geometries.mdx | 2 +- .../surrealql/datamodel/ids.mdx | 2 +- .../surrealql/datamodel/index.mdx | 81 ++++++--- .../surrealql/datamodel/literals.mdx | 154 ++++++++++++++++++ .../surrealql/datamodel/none_and_null.mdx | 2 +- .../surrealql/datamodel/numbers.mdx | 2 +- .../surrealql/datamodel/objects.mdx | 2 +- .../surrealql/datamodel/ranges.mdx | 67 ++++++++ .../surrealql/datamodel/records.mdx | 2 +- .../surrealql/datamodel/sets.mdx | 48 ++++++ .../surrealql/datamodel/strings.mdx | 2 +- .../surrealql/datamodel/uuid.mdx | 2 +- .../surrealql/datamodel/values.mdx | 2 +- .../surrealql/statements/define/field.mdx | 42 +++++ .../surrealql/statements/for.mdx | 16 ++ 20 files changed, 412 insertions(+), 40 deletions(-) create mode 100644 doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/literals.mdx create mode 100644 doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/ranges.mdx create mode 100644 doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/sets.mdx diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/arrays.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/arrays.mdx index 5b187caf4..8e440e249 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/arrays.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/arrays.mdx @@ -17,4 +17,22 @@ CREATE person SET results = [ { score: 69, date: "2018-09-17T08:00:00Z", name: "Advanced Computer Science 101" }, { score: 73, date: "2019-04-20T08:00:00Z", name: "Distributed Databases" }, ]; +``` + +A maximum number of items can be specified for an array. + +```surql +DEFINE FIELD employees ON TABLE team TYPE array, 5>; +CREATE team SET employees = [ + employee:one, + employee:two, + employee:three, + employee:four, + employee:five, + employee:doesnt_belong +]; +``` + +```bash title="Response" +'Expected a array, 5> but the array had 6 items' ``` \ No newline at end of file diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/closures.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/closures.mdx index db5a5edb3..391a048e7 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/closures.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/closures.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 sidebar_label: Closures title: Closures | SurrealQL description: Anonymous functions in SurrealDB allow you to define small, reusable pieces of logic that can be used throughout your queries. diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/datetimes.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/datetimes.mdx index da94ca27c..e5723fe63 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/datetimes.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/datetimes.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 14 +sidebar_position: 6 sidebar_label: Datetimes title: Datetimes | SurrealQL description: SurrealDB has native support for datetimes with nanosecond precision. SurrealDB is able to parse datetimes from strings. diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/formatters.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/formatters.mdx index eeee2156d..1e0635d58 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/formatters.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/formatters.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 7 sidebar_label: Formatters title: Formatters | SurrealQL description: Formatting functions in SurrealQL accept certain text formats for date/time formatting. diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/futures.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/futures.mdx index 21caa82f0..e7e158832 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/futures.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/futures.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 8 sidebar_label: Futures title: Futures | SurrealQL description: Futures are values which are only computed when the data is selected and returned to the client. diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/geometries.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/geometries.mdx index 4da66d5f4..608758883 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/geometries.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/geometries.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 9 sidebar_label: Geometries title: Geometries | SurrealQL description: SurrealDB makes working with GeoJSON easy, with support for Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and Collection values. diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/ids.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/ids.mdx index 123862fc4..a131b44f1 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/ids.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/ids.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 15 sidebar_label: Record IDs title: Record IDs | SurrealQL description: In SurrealDB, document record IDs store both the table name, and the record ID. diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/index.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/index.mdx index e2673dc13..3c0ac629f 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/index.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/index.mdx @@ -40,21 +40,6 @@ SurrealQL allows you to describe data with specific data types. These data types - - - set - - - A set of items. - The set type also allows you to define which types can be stored in the set and the max length. - Items are automatically deduplicated. -
    -
  • set
    • -
  • set<string>
    • -
  • set<string, 10>
    • -
- - bool @@ -107,6 +92,24 @@ SurrealQL allows you to describe data with specific data types. These data types Store a value in a 64 bit float. + + + geometry + + + RFC 7946 compliant data type for storing geometry in the GeoJson format. +
    +
  • geometry<feature>
    • +
  • geometry<point>
    • +
  • geometry<LineString>
    • +
  • geometry<polygon>
    • +
  • geometry<multipoint>
    • +
  • geometry<multiline>
    • +
  • geometry<multipolygon>
    • +
  • geometry<collection>
    • +
+ + int @@ -133,6 +136,19 @@ SurrealQL allows you to describe data with specific data types. These data types Store formatted objects containing values of any supported type with no limit to object depth or nesting. + + + literal + + + A value that may have multiple representations or formats, similar to an enum or a union type. Can be composed of strings, numbers, objects, arrays, or durations. +
    +
  • "a" | "b"
    • +
  • [number, "abc"]
    • +
  • 123 | 456 | string | 1y1m1d
    • +
+ + option @@ -146,10 +162,16 @@ SurrealQL allows you to describe data with specific data types. These data types - string + range - Describes a text-like value. + A range of possible values. Lower and upper bounds can be set, in the absence of which the range becomes open-ended. A range of integers can be used in a FOR loop. +
    +
  • 0..10
    • +
  • 0..=10
    • +
  • ..10
    • +
  • 'a'..'z'
    • +
@@ -167,22 +189,27 @@ SurrealQL allows you to describe data with specific data types. These data types - geometry + set - RFC 7946 compliant data type for storing geometry in the GeoJson format. + A set of items. + The set type also allows you to define which types can be stored in the set and the max length. + Items are automatically deduplicated.
    -
  • geometry<feature>
    • -
  • geometry<point>
    • -
  • geometry<LineString>
    • -
  • geometry<polygon>
    • -
  • geometry<multipoint>
    • -
  • geometry<multiline>
    • -
  • geometry<multipolygon>
    • -
  • geometry<collection>
    • +
  • set
    • +
  • set<string>
    • +
  • set<string, 10>
+ + + string + + + Describes a text-like value. + + diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/literals.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/literals.mdx new file mode 100644 index 000000000..5cd2bdf93 --- /dev/null +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/literals.mdx @@ -0,0 +1,154 @@ +--- +sidebar_position: 10 +sidebar_label: Literals +title: Literals | SurrealQL +description: A value that may have multiple representations or formats. + +--- + +import Since from '@site/src/components/Since' + +# Literals + + + +A literal is a value that may have multiple representations or formats, similar to an enum or a union type. A literal can be composed of strings, numbers, objects, arrays, or durations. + +## Examples + +A literal can be as simple as a declaration that a parameter must be a certain value. + +```surql +LET $nine: 9 = 9; +LET $nine: 9 = 10; +``` + +```bash title="Response" +-------- Query -------- + +NONE + +-------- Query -------- + +'Found 10 for param $nine, but expected a 9' +``` + +Using `|` allows a literal to be a number of possible options. + +```surql +LET $nine: 9 | "9" | "nine" = "Nein"; +``` + +```bash title="Response" +"Found 'Nein' for param $nine, but expected a 9 | '9' | 'nine'" +``` + +A literal can contain possible types in addition to possible values. + +```surql +LET $flexible_param: datetime | uuid | "N/A" = "N/A"; +LET $flexible_param: datetime | uuid | "N/A" = "2024-09-01"; +``` + +Literals that include the option to be an array or an object can contain rich data. + +```surql +LET $status: "Ok" | { err: string } = { err: "Forgot to plug it in" }; +``` + +## Literals in database schema + +Literals can be defined inside a database schema by using a [DEFINE FIELD](/docs/surrealdb/surrealql/statements/define/field) statement. + +```surql +DEFINE FIELD error_info ON TABLE info TYPE + { error: "Continue" } | + { error: "RetryWithId", id: string } | + { error: "Deprecated", message: string }; + +CREATE info SET + error_info = { error: "Deprecated", message: "You shouldn't use this anymore" }; +-- Doesn't conform to definition, will not work +CREATE info SET + error_info = "You shouldn't use this anymore"; +``` + +```bash title="Response" +-------- Query -------- + +[ + { + error_info: { + error: 'Deprecated', + message: "You shouldn't use this anymore" + }, + id: info:pkckjrri8q1pg12unyuo + } +] + +-------- Query -------- + +"Found \"You shouldn't use this anymore\" for field `error_info`, with record `info:dq375w4lv02aj2dj7122`, but expected a { error: 'Continue' } | { error: 'RetryWithId', id: string } | { error: 'Deprecated', message: string }" +``` + +## Matching on literals + +While SurrealQL does not have a `match` or `switch` operator, `IF LET` statements can be used to match on a literal, particularly if each possible type is an object. The following shows a similar example to the above except that each object begins with a field containing the name of the type of error. + +```surql +DEFINE FIELD error_info ON TABLE info TYPE + { Continue: { message: "" }} | + { Retry: { error: "Retrying", after: duration }} | + { Deprecated: { message: string }}; +``` + +Next, we will [define a function](/docs/surrealdb/surrealql/statements/define/function) to handle this field and return a certain type of message depending on the error. Note the following: + +* The `LET` statement in the first line is simply to shorten the path to the information contained inside `error_info` +* `IF LET` statement works here because [IF](/docs/surrealdb/surrealql/statements/throw) involves a check for [truthiness](/docs/surrealdb/surrealql/datamodel/values#values-and-truthiness), returning `true` as long as it finds a value that is not none, empty, or zero. + +```surql +DEFINE FUNCTION fn::handle_error($data: record) -> string { + LET $err = $data.error_info; + RETURN IF $err.Continue { + "Continue" + } + ELSE IF $err.Retry { + sleep($err.Retry.after); + "Now retrying again" + } + ELSE IF $err.Deprecated { + $err.Deprecated.message + } +}; +``` + +With the function set up, the `info` records can be inserted and run one at a time through the function. + +```surql +INSERT INTO info [ + { error_info: { Continue: { message: "" } }}, + { error_info: { Retry: { error: "Retrying", after: 1s } }}, + { error_info: { Deprecated: { message: "Thought I said you shouldn't use this anymore" } }} +]; + +LET $info = SELECT * FROM info; +fn::handle_error($info[0].id); +fn::handle_error($info[1].id); +fn::handle_error($info[2].id); +``` + +```bash title="Output" +-------- Query -------- + +'Continue' + +-------- Query -------- + +-- After waiting 1 second +'Now retrying again' + +-------- Query -------- + +"Thought I said you shouldn't use this anymore" +``` \ No newline at end of file diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/none_and_null.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/none_and_null.mdx index ff4d7af52..f85e161ce 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/none_and_null.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/none_and_null.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 11 sidebar_label: None and Null title: None and Null | SurrealQL description: SurrealDB uses two types called None and Null to represent two different ways in which data may not exist. diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/numbers.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/numbers.mdx index 1cbba71e7..cd66910a5 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/numbers.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/numbers.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 12 sidebar_label: Numbers title: Numbers | SurrealQL description: In SurrealDB, numbers can be one of three types - 64-bit integers, 64-bit floating point numbers, or 128-bit decimal numbers. diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/objects.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/objects.mdx index 406e7538d..561b1df7a 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/objects.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/objects.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 11 +sidebar_position: 13 sidebar_label: Objects title: Objects | SurrealQL description: SurrealDB records can store objects, with no limit to the depth of any nested objects or values within. diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/ranges.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/ranges.mdx new file mode 100644 index 000000000..e0573bdc5 --- /dev/null +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/ranges.mdx @@ -0,0 +1,67 @@ +--- +sidebar_position: 14 +sidebar_label: Ranges +title: Ranges | SurrealQL +description: A range of possible values. + +--- + +import Since from '@site/src/components/Since' + +# Ranges + + + +A range is composed of `..` and possible delimiters to set the maximum and minimum possible values. The default syntax includes the lower limit and excludes the upper limit. A `=` can be used to make the upper limit inclusive, and `>` can be used to make the lower limit exclusive. + +```surql +-- From 0 up to 9 +0..10; +-- From 0 up to 10 +0..=10 +-- From 1 to 9 +0>..10; +-- From 1 to 10 +0>..=10 +``` + +A range becomes open ended if a delimiter is not specified. + +```surql +-- Anything from 0 and up +0.. +-- Anything from 1 and up +0>.. +-- Anything up to 99 +..100 +-- Anything up to 100 +..=100 +-- An infinite range +.. +``` + +A range can be constructed from any type of value. This is most useful when comparing one value to another. + +```surql +-- All true +'g' IN 'a'..'z'; +d"2024-01-01" IN d"2020-01-01"..=d"2025-01-01"; +['London', d"2022-02-02", 5.7] IN ['London', d"2020-01-01"]..=['London', d"2024-12-31"]; + +-- All false +"ㅋㅋㅋ" IN "a".."z"; +d"2028-01-01" IN d"2020-01-01"..=d"2025-01-01"; +['Philadelphia', d"2022-02-02", 5.7] IN ['London', d"2020-01-01"]..=['London', d"2024-12-31"]; +``` + +## Ranges in FOR loops + +Ranges of integers have the added convenience of being able to be used in a [FOR loop](/docs/surrealdb/surrealql/statements/for). + +```surql +FOR $year IN 0..=2024 { + CREATE historical_events SET + for_year = $year, + events = "To be added"; +} +``` \ No newline at end of file diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/records.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/records.mdx index b4ba8eaf0..d6bf410ba 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/records.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/records.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 16 sidebar_label: Record links title: Record links | SurrealQL description: One of the most powerful features of SurrealDB is the ability to traverse from record-to-record without the need for traditional SQL JOINs. Each record ID points directly to a specific record in the database. diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/sets.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/sets.mdx new file mode 100644 index 000000000..f06a275f0 --- /dev/null +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/sets.mdx @@ -0,0 +1,48 @@ +--- +sidebar_position: 17 +sidebar_label: Sets +title: Sets | SurrealQL +description: A set is a collection type of deduplicated values that can have a maximum size limit. + +--- + +# Sets + +A set is similar to an array, but deduplicates items. + +```surql +DEFINE FIELD visited ON TABLE traveler TYPE set>; +CREATE traveler:one SET visited = [country:canada, country:usa, country:korea, country:japan]; +-- Traveler comes back from a trip +UPDATE traveler:one SET visited += country:uk; +-- And again +UPDATE traveler:one SET visited += country:uk; +``` + +```bash title="Response" +[ + { + id: traveler:one, + visited: [ + country:canada, + country:usa, + country:korea, + country:japan, + country:uk + ] + } +] +``` + +A maximum number of items can be specified for a set. + +```surql +DEFINE FIELD employees ON TABLE team TYPE set, 5>; +CREATE team:my_team SET employees = [employee:one, employee:two, employee:three, employee:four, employee:five]; +UPDATE team:my_team SET employees += employee:one; +``` + +```surql +UPDATE team:my_team SET employees += employee:one; +UPDATE team:my_team SET employees += employee:doesnt_belong; +``` \ No newline at end of file diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/strings.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/strings.mdx index 59b5f1378..d6c4ad6f0 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/strings.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/strings.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 13 +sidebar_position: 18 sidebar_label: Strings title: Strings | SurrealQL description: Strings can be used to store text values. All text fields can include unicode values, emojis, and tabular and multine breaks. diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/uuid.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/uuid.mdx index fda7613da..bebba9785 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/uuid.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/uuid.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 15 +sidebar_position: 19 sidebar_label: UUIDs title: UUIDs | SurrealQL description: UUID values in SurrealQL represent UUID values diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/values.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/values.mdx index 17494e8be..070c43106 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/values.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/datamodel/values.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 16 +sidebar_position: 20 sidebar_label: Values title: Values | SurrealQL description: Every type in SurrealDB is a value diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/field.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/field.mdx index d052e542a..15e5161ff 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/field.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/field.mdx @@ -346,3 +346,45 @@ CREATE person SET first_name = "Bob", last_name = "Bobson"; ``` A good rule of thumb is to organize your `DEFINE FIELD` statements in alphabetical order. + +## Defining a literal on a field + + + +A field can also be defined as a [literal type](/docs/surrealdb/surrealql/datamodel/literals), by specifying one or more possible values and/or permitted types. + +```surql +DEFINE FIELD coffee ON TABLE order TYPE "regular" | "large" | { special_order: string }; + +CREATE order SET coffee = { special_order: "Venti Quadruple Ristretto Half-Decaf Soy Latte with 4 pumps of sugar-free vanilla syrup" }; +CREATE order SET coffee = "small"; +``` + +```bash title="Response" +-------- Query -------- + +[ + { + coffee: { + special_order: 'Venti Quadruple Ristretto Half-Decaf Soy Latte with 4 pumps of sugar-free vanilla syrup' + }, + id: order:ga3m9qxtv8m02wdgoe73 + } +] + +-------- Query -------- +"Found 'small' for field `coffee`, with record `order:juq3twfic1s6gxw9ljgj`, but expected a 'regular' | 'large' | { special_order: string }" +``` + +One more example of a literal containing settings for a [full text search](/docs/surrealdb/reference-guide/full-text-search) filter: + +```surql +DEFINE FIELD filter ON TABLE search_settings TYPE + "None" | + { type: "Ascii" } | + { type: "EdgeNgram", from: int, to: int } | + { type: "Lowercase" } | + { type: "Ngram", from: int, to: int } | + { type: "Snowball", language: string } | + { type: "Uppercase" }; +``` \ No newline at end of file diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/for.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/for.mdx index fda11effc..9c4f72812 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/for.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/for.mdx @@ -5,6 +5,8 @@ title: FOR statement | SurrealQL description: The FOR statement creates a loop that iterates over the values of an array. --- +import Since from '@site/src/components/Since' + # `FOR` statement The `FOR` statement can be used to iterate over the values of an array, and to perform certain actions with those values. @@ -38,4 +40,18 @@ The following query shows the `FOR` statement being used update a property on ev FOR $person IN (SELECT VALUE id FROM person WHERE age >= 18) { UPDATE $person SET can_vote = true; }; +``` + +## Ranges in FOR loops + + + +A `FOR` loop can also be made out of a [range UUID](/docs/surrealdb/surrealql/datamodel/ranges) of integers. + +```surql +FOR $year IN 0..=2024 { + CREATE historical_events SET + for_year = $year, + events = "To be added"; +} ``` \ No newline at end of file