You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@asterixdb.apache.org by bu...@apache.org on 2016/10/03 06:37:42 UTC
[1/5] asterixdb git commit: Revise builtin function documents.
Repository: asterixdb
Updated Branches:
refs/heads/master ccb140807 -> f7f3a7f2b
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/site/site.xml
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/site/site.xml b/asterixdb/asterix-doc/src/site/site.xml
index 6d7a733..33ce7eb 100644
--- a/asterixdb/asterix-doc/src/site/site.xml
+++ b/asterixdb/asterix-doc/src/site/site.xml
@@ -90,15 +90,12 @@
<menu name="Queries - SQL++">
<item name="The SQL++ Query Language" href="sqlpp/manual.html"/>
+ <item name="Builtin Functions" href="sqlpp/builtins.html"/>
</menu>
<menu name="Queries - AQL">
<item name="The Asterix Query Language (AQL)" href="aql/manual.html"/>
- </menu>
-
- <menu name="Functions">
- <item name="Builtin Functions" href="aql/functions.html"/>
- <item name="AQL Allen's Relations Functions" href="aql/allens.html"/>
+ <item name="Builtin Functions" href="aql/builtins.html"/>
</menu>
<menu name="Advanced Features">
[2/5] asterixdb git commit: Revise builtin function documents.
Posted by bu...@apache.org.
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/site/markdown/aql/functions.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/site/markdown/aql/functions.md b/asterixdb/asterix-doc/src/site/markdown/aql/functions.md
deleted file mode 100644
index 81ef9c7..0000000
--- a/asterixdb/asterix-doc/src/site/markdown/aql/functions.md
+++ /dev/null
@@ -1,2676 +0,0 @@
-<!--
- ! Licensed to the Apache Software Foundation (ASF) under one
- ! or more contributor license agreements. See the NOTICE file
- ! distributed with this work for additional information
- ! regarding copyright ownership. The ASF licenses this file
- ! to you under the Apache License, Version 2.0 (the
- ! "License"); you may not use this file except in compliance
- ! with the License. You may obtain a copy of the License at
- !
- ! http://www.apache.org/licenses/LICENSE-2.0
- !
- ! Unless required by applicable law or agreed to in writing,
- ! software distributed under the License is distributed on an
- ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ! KIND, either express or implied. See the License for the
- ! specific language governing permissions and limitations
- ! under the License.
- !-->
-
-# Asterix: Using Functions #
-
-## <a id="toc">Table of Contents</a> ##
-
-* [Numeric Functions](#NumericFunctions)
-* [String Functions](#StringFunctions)
-* [Binary Functions](#BinaryFunctions)
-* [Aggregate Functions](#AggregateFunctions)
-* [Spatial Functions](#SpatialFunctions)
-* [Similarity Functions](#SimilarityFunctions)
-* [Tokenizing Functions](#TokenizingFunctions)
-* [Temporal Functions](#TemporalFunctions)
-* [Record Functions](#RecordFunctions)
-* [Other Functions](#OtherFunctions)
-
-Asterix provides various classes of functions to support operations on numeric, string, spatial, and temporal data. This document explains how to use these functions.
-
-## <a id="NumericFunctions">Numeric Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
-### abs ###
- * Syntax:
-
- abs(numeric_value)
-
- * Computes the absolute value of the argument.
- * Arguments:
- * `numeric_value`: A `int8`/`int16`/`int32`/`int64`/`float`/`double` value.
- * Return Value:
- * The absolute value of the argument with the same type as the input argument, or `null` if the argument is a `null` value.
-
- * Example:
-
- let $v1 := abs(2013)
- let $v2 := abs(-4036)
- let $v3 := abs(0)
- let $v4 := abs(float("-2013.5"))
- let $v5 := abs(double("-2013.593823748327284"))
- return { "v1": $v1, "v2": $v2, "v3": $v3, "v4": $v4, "v5": $v5 }
-
-
- * The expected result is:
-
- { "v1": 2013, "v2": 4036, "v3": 0, "v4": 2013.5f, "v5": 2013.5938237483274d }
-
-
-### ceiling ###
- * Syntax:
-
- ceiling(numeric_value)
-
- * Computes the smallest (closest to negative infinity) number with no fractional part that is not less than the value of the argument. If the argument is already equal to mathematical integer, then the result is the same as the argument.
- * Arguments:
- * `numeric_value`: A `int8`/`int16`/`int32`/`int64`/`float`/`double` value.
- * Return Value:
- * The ceiling value for the given number in the same type as the input argument, or `null` if the input is `null`.
-
- * Example:
-
- let $v1 := ceiling(2013)
- let $v2 := ceiling(-4036)
- let $v3 := ceiling(0.3)
- let $v4 := ceiling(float("-2013.2"))
- let $v5 := ceiling(double("-2013.893823748327284"))
- return { "v1": $v1, "v2": $v2, "v3": $v3, "v4": $v4, "v5": $v5 }
-
-
- * The expected result is:
-
- { "v1": 2013, "v2": -4036, "v3": 1.0d, "v4": -2013.0f, "v5": -2013.0d }
-
-
-### floor ###
- * Syntax:
-
- floor(numeric_value)
-
- * Computes the largest (closest to positive infinity) number with no fractional part that is not greater than the value. If the argument is already equal to mathematical integer, then the result is the same as the argument.
- * Arguments:
- * `numeric_value`: A `int8`/`int16`/`int32`/`int64`/`float`/`double` value.
- * Return Value:
- * The floor value for the given number in the same type as the input argument, or `null` if the input is `null`.
-
- * Example:
-
- let $v1 := floor(2013)
- let $v2 := floor(-4036)
- let $v3 := floor(0.8)
- let $v4 := floor(float("-2013.2"))
- let $v5 := floor(double("-2013.893823748327284"))
- return { "v1": $v1, "v2": $v2, "v3": $v3, "v4": $v4, "v5": $v5 }
-
-
- * The expected result is:
-
- { "v1": 2013, "v2": -4036, "v3": 0.0d, "v4": -2014.0f, "v5": -2014.0d }
-
-
-### round ###
- * Syntax:
-
- round(numeric_value)
-
- * Computes the number with no fractional part that is closest (and also closest to positive infinity) to the argument.
- * Arguments:
- * `numeric_value`: A `int8`/`int16`/`int32`/`int64`/`float`/`double` value.
- * Return Value:
- * The rounded value for the given number in the same type as the input argument, or `null` if the input is `null`.
-
- * Example:
-
- let $v1 := round(2013)
- let $v2 := round(-4036)
- let $v3 := round(0.8)
- let $v4 := round(float("-2013.256"))
- let $v5 := round(double("-2013.893823748327284"))
- return { "v1": $v1, "v2": $v2, "v3": $v3, "v4": $v4, "v5": $v5 }
-
-
- * The expected result is:
-
- { "v1": 2013, "v2": -4036, "v3": 1.0d, "v4": -2013.0f, "v5": -2014.0d }
-
-
-### round-half-to-even ###
- * Syntax:
-
- round-half-to-even(numeric_value, [precision])
-
- * Computes the closest numeric value to `numeric_value` that is a multiple of ten to the power of minus `precision`. `precision` is optional and by default value `0` is used.
- * Arguments:
- * `numeric_value`: A `int8`/`int16`/`int32`/`int64`/`float`/`double` value.
- * `precision`: An optional integer field representing the number of digits in the fraction of the the result
- * Return Value:
- * The rounded value for the given number in the same type as the input argument, or `null` if the input is `null`.
-
- * Example:
-
- let $v1 := round-half-to-even(2013)
- let $v2 := round-half-to-even(-4036)
- let $v3 := round-half-to-even(0.8)
- let $v4 := round-half-to-even(float("-2013.256"))
- let $v5 := round-half-to-even(double("-2013.893823748327284"))
- let $v6 := round-half-to-even(double("-2013.893823748327284"), 2)
- let $v7 := round-half-to-even(2013, 4)
- let $v8 := round-half-to-even(float("-2013.256"), 5)
- return { "v1": $v1, "v2": $v2, "v3": $v3, "v4": $v4, "v5": $v5, "v6": $v6, "v7": $v7, "v8": $v8 }
-
-
- * The expected result is:
-
- { "v1": 2013, "v2": -4036, "v3": 1.0d, "v4": -2013.0f, "v5": -2014.0d, "v6": -2013.89d, "v7": 2013, "v8": -2013.256f }
-
-
-## <a id="StringFunctions">String Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
-### string-to-codepoint ###
- * Syntax:
-
- string-to-codepoint(string)
-
- * Converts the string `string` to its code-based representation.
- * Arguments:
- * `string` : A `string` that will be converted.
- * Return Value:
- * An `OrderedList` of the code points for the string `string`.
-
-### codepoint-to-string ###
- * Syntax:
-
- codepoint-to-string(list)
-
- * Converts the ordered code-based representation `list` to the corresponding string.
- * Arguments:
- * `list` : An `OrderedList` of code-points.
- * Return Value:
- * A `string` representation of `list`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $s := "Hello ASTERIX!"
- let $l := string-to-codepoint($s)
- let $ss := codepoint-to-string($l)
- return {"codes": $l, "string": $ss}
-
-
- * The expected result is:
-
- { "codes": [ 72, 101, 108, 108, 111, 32, 65, 83, 84, 69, 82, 73, 88, 33 ], "string": "Hello ASTERIX!" }
-
-
-### contains ###
- * Syntax:
-
- contains(string, substring_to_contain)
-
- * Checks whether the string `string` contains the string `substring_to_contain`
- * Arguments:
- * `string` : A `string` that might contain the given substring.
- * `substring_to_contain` : A target `string` that might be contained.
- * Return Value:
- * A `boolean` value, `true` if `string` contains `substring_to_contain`, and `false` otherwise.
- * Note: An [n-gram index](similarity.html#UsingIndexesToSupportSimilarityQueries) can be utilized for this function.
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('FacebookMessages')
- where contains($i.message, "phone")
- return {"mid": $i.message-id, "message": $i.message}
-
-
- * The expected result is:
-
- { "mid": 2, "message": " dislike iphone its touch-screen is horrible" }
- { "mid": 13, "message": " dislike iphone the voice-command is bad:(" }
- { "mid": 15, "message": " like iphone the voicemail-service is awesome" }
-
-
-### like ###
- * Syntax:
-
- like(string, string_pattern)
-
- * Checks whether the string `string` contains the string pattern `string_pattern`. Compared to the `contains` function, the `like` function also supports regular expressions.
- * Arguments:
- * `string` : A `string` that might contain the pattern or `null`.
- * `string_pattern` : A pattern `string` that might be contained or `null`.
- * Return Value:
- * A `boolean` value, `true` if `string` contains the pattern `string_pattern`, and `false` otherwise.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('FacebookMessages')
- where like($i.message, "%at&t%")
- return $i.message
-
-
- * The expected result is:
-
- " can't stand at&t the network is horrible:("
- " can't stand at&t its plan is terrible"
- " love at&t its 3G is good:)"
-
-
-### starts-with ###
- * Syntax:
-
- starts-with(string, substring_to_start_with)
-
- * Checks whether the string `string` starts with the string `substring_to_start_with`.
- * Arguments:
- * `string` : A `string` that might start with the given string.
- * `substring_to_start_with` : A `string` that might be contained as the starting substring.
- * Return Value:
- * A `boolean`, returns `true` if `string` starts with the string `substring_to_start_with`, and `false` otherwise.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('FacebookMessages')
- where starts-with($i.message, " like")
- return $i.message
-
-
- * The expected result is:
-
- " like samsung the plan is amazing"
- " like t-mobile its platform is mind-blowing"
- " like verizon the 3G is awesome:)"
- " like iphone the voicemail-service is awesome"
-
-
-### ends-with ###
- * Syntax:
-
- ends-with(string, substring_to_end_with)
-
- * Checks whether the string `string` ends with the string `substring_to_end_with`.
- * Arguments:
- * `string` : A `string` that might end with the given string.
- * `substring_to_end_with` : A `string` that might be contained as the ending substring.
- * Return Value:
- * A `boolean`, returns `true` if `string` ends with the string `substring_to_end_with`, and `false` otherwise.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('FacebookMessages')
- where ends-with($i.message, ":)")
- return $i.message
-
-
- * The expected result is:
-
- " love sprint its shortcut-menu is awesome:)"
- " like verizon the 3G is awesome:)"
- " love at&t its 3G is good:)"
-
-
-### string-concat ###
- * Syntax:
-
- string-concat(list)
-
- * Concatenates a list of strings `list` into a single string.
- * Arguments:
- * `list` : An `OrderedList` or `UnorderedList` of `string`s (could be `null`) to be concatenated.
- * Return Value:
- * Returns the concatenated `string` value.
-
- * Example:
-
- let $i := "ASTERIX"
- let $j := " "
- let $k := "ROCKS!"
- return string-concat([$i, $j, $k])
-
-
- * The expected result is:
-
- "ASTERIX ROCKS!"
-
-
-### string-join ###
- * Syntax:
-
- string-join(list, string)
-
- * Joins a list of strings `list` with the given separator `string` into a single string.
- * Arguments:
- * `list` : An `OrderedList` or `UnorderedList` of strings (could be `null`) to be joined.
- * `string` : A `string` as the separator.
- * Return Value:
- * Returns the joined `String`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $i := ["ASTERIX", "ROCKS~"]
- return string-join($i, "!! ")
-
-
- * The expected result is:
-
- "ASTERIX!! ROCKS~"
-
-
-### lowercase ###
- * Syntax:
-
- lowercase(string)
-
- * Converts a given string `string` to its lowercase form.
- * Arguments:
- * `string` : A `string` to be converted.
- * Return Value:
- * Returns a `string` as the lowercase form of the given `string`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $i := "ASTERIX"
- return lowercase($i)
-
-
- * The expected result is:
-
- asterix
-
-### uppercase ###
- * Syntax:
-
- uppercase(string)
-
- * Converts a given string `string` to its uppercase form.
- * Arguments:
- * `string` : A `string` to be converted.
- * Return Value:
- * Returns a `string` as the uppercase form of the given `string`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $i := "asterix"
- return uppercase($i)
-
-
- * The expected result is:
-
- ASTERIX
-
-### matches ###
- * Syntax:
-
- matches(string, string_pattern)
-
- * Checks whether the strings `string` matches the given pattern `string_pattern` (A Java regular expression pattern).
- * Arguments:
- * `string` : A `string` that might contain the pattern.
- * `string_pattern` : A pattern `string` to be matched.
- * Return Value:
- * A `boolean`, returns `true` if `string` matches the pattern `string_pattern`, and `false` otherwise.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('FacebookMessages')
- where matches($i.message, "dislike iphone")
- return $i.message
-
-
- * The expected result is:
-
- " dislike iphone its touch-screen is horrible"
- " dislike iphone the voice-command is bad:("
-
-
-### replace ###
- * Syntax:
-
- replace(string, string_pattern, string_replacement[, string_flags])
-
- * Checks whether the string `string` matches the given pattern `string_pattern`, and replace the matched pattern `string_pattern` with the new pattern `string_replacement`.
- * Arguments:
- * `string` : A `string` that might contain the pattern.
- * `string_pattern` : A pattern `string` to be matched.
- * `string_replacement` : A pattern `string` to be used as the replacement.
- * `string_flag` : (Optional) A `string` with flags to be used during replace.
- * The following modes are enabled with these flags: dotall (s), multiline (m), case-insenitive (i), and comments and whitespace (x).
- * Return Value:
- * Returns a `string` that is obtained after the replacements.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('FacebookMessages')
- where matches($i.message, " like iphone")
- return replace($i.message, " like iphone", "like android")
-
-
- * The expected result is:
-
- "like android the voicemail-service is awesome"
-
-
-### string-length ###
- * Syntax:
-
- string-length(string)
-
- * Returns the length of the string `string`.
- * Arguments:
- * `string` : A `string` or `null` that represents the string to be checked.
- * Return Value:
- * An `int64` that represents the length of `string`.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('FacebookMessages')
- return {"mid": $i.message-id, "message-len": string-length($i.message)}
-
-
- * The expected result is:
-
- { "mid": 1, "message-len": 43 }
- { "mid": 2, "message-len": 44 }
- { "mid": 3, "message-len": 33 }
- { "mid": 4, "message-len": 43 }
- { "mid": 5, "message-len": 46 }
- { "mid": 6, "message-len": 43 }
- { "mid": 7, "message-len": 37 }
- { "mid": 8, "message-len": 33 }
- { "mid": 9, "message-len": 34 }
- { "mid": 10, "message-len": 50 }
- { "mid": 11, "message-len": 38 }
- { "mid": 12, "message-len": 52 }
- { "mid": 13, "message-len": 42 }
- { "mid": 14, "message-len": 27 }
- { "mid": 15, "message-len": 45 }
-
-
-### substring ###
- * Syntax:
-
- substring(string, offset[, length])
-
- * Returns the substring from the given string `string` based on the given start offset `offset` with the optional `length`.
- * Arguments:
- * `string` : A `string` to be extracted.
- * `offset` : An `int64` as the starting offset of the substring in `string`.
- * `length` : (Optional) An `int64` as the length of the substring.
- * Return Value:
- * A `string` that represents the substring.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('FacebookMessages')
- where string-length($i.message) > 50
- return substring($i.message, 50)
-
-
- * The expected result is:
-
- "G:("
-
-
-### substring-before ###
- * Syntax:
-
- substring-before(string, string_pattern)
-
- * Returns the substring from the given string `string` before the given pattern `string_pattern`.
- * Arguments:
- * `string` : A `string` to be extracted.
- * `string_pattern` : A `string` pattern to be searched.
- * Return Value:
- * A `string` that represents the substring.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('FacebookMessages')
- where contains($i.message, "iphone")
- return substring-before($i.message, "iphone")
-
-
- * The expected result is:
-
- " dislike "
- " dislike "
- " like "
-
-
-### substring-after ###
- * Syntax:
-
- substring-after(string, string_pattern)
-
- * Returns the substring from the given string `string` after the given pattern `string_pattern`.
- * Arguments:
- * `string` : A `string` to be extracted.
- * `string_pattern` : A `string` pattern to be searched.
- * Return Value:
- * A `string` that represents the substring.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('FacebookMessages')
- where contains($i.message, "iphone")
- return substring-after($i.message, "iphone")
-
-
- * The expected result is:
-
- " its touch-screen is horrible"
- " the voice-command is bad:("
- " the voicemail-service is awesome"
-
-## <a id="BinaryFunctions">Binary Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
-### parse-binary ###
- * Syntax:
-
- parse-binary(string, encoding)
-
- * Creates a `binary` from an string encoded in `encoding` format.
- * Arguments:
- * `string` : An encoded `string`
- * `encoding` : A string notation specifies the encoding type of the given `string`.
- Currently we support `hex` and `base64` format.
- * Return Value:
- * A `binary` that is decoded from the given `string`.
-
- * Example:
-
- let $c1 := parse-binary("ABCDEF0123456789","hex")
- let $c2 := parse-binary("abcdef0123456789","HEX")
- let $c3 := parse-binary('QXN0ZXJpeAE=',"base64")
- return [ $c1, $c2, $c3 ]
-
- * The expected result is:
-
- [ hex("ABCDEF0123456789"), hex("ABCDEF0123456789"), hex("4173746572697801") ]
-
-### print-binary ###
- * Syntax:
-
- print-binary(binary, encoding)
-
- * Prints a `binary` to the required encoding `string` format.
- * Arguments:
- * `binary` : A `binary` data need to be printed.
- * `encoding` : A string notation specifies the expected encoding type.
- Currently we support `hex` and `base64` format.
- * Return Value:
- * A `string` that represents the encoded format of a `binary`.
-
- * Example:
-
- print-binary(hex("ABCDEF0123456789"), "base64")
- print-binary(base64("q83vASNFZ4k="), "hex")
-
- * The expected result is:
-
- "q83vASNFZ4k="
- "ABCDEF0123456789"
-
-### binary-length ###
- * Syntax:
-
- binary-length(binary)
-
- * Returns the number of bytes storing the binary data.
- * Arguments:
- * `binary` : A `binary` data to be checked.
- * Return Value:
- * An `int64` that represents the number of bytes
- * Example:
-
- binary-length(hex("00AA"))
-
- * The expected result is:
-
- 2
-
-### sub-binary ###
- * Syntax:
-
- sub-binary(binary, offset[, length])
-
- * Returns the sub binary from the given `binary` based on the given start offset with the optional `length`.
- * Arguments:
- * `binary` : A `binary` to be extracted.
- * `offset` : An `int64` as the starting offset of the sub binary in `binary`.
- * `length` : (Optional) An `int64` as the length of the sub binary.
- * Return Value:
- * A `binary` that represents the sub binary.
- * Example:
-
- sub-binary(hex("AABBCCDD"), 4)
-
- * The expected result is
-
- hex("DD")
-
-### binary-concat ###
- * Syntax:
-
- binary-concat(list)
-
- * Concatenates a list of binary `list` into a single binary.
- * Arguments:
- * `list` : An OrderedList of binaries (could be null) to be concatenated.
- * Return Value :
- * Returns the concatenated `binary` value.
- * Example:
-
- binary-concat([hex("42"), hex(""), hex('42')])
-
- * The expected result is
-
- hex("4242")
-
-## <a id="AggregateFunctions">Aggregate Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
-### count ###
- * Syntax:
-
- count(list)
-
- * Gets the number of items in the given list.
- * Arguments:
- * `list`: An `orderedList` or `unorderedList` containing the items to be counted, or a `null` value.
- * Return Value:
- * An `int64` value representing the number of items in the given list. `0i64` is returned if the input is `null`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $l1 := ['hello', 'world', 1, 2, 3]
- let $l2 := for $i in dataset TwitterUsers return $i
- return {"count1": count($l1), "count2": count($l2)}
-
- * The expected result is:
-
- { "count1": 5i64, "count2": 4i64 }
-
-### avg ###
- * Syntax:
-
- avg(num_list)
-
- * Gets the average value of the items in the given list.
- * Arguments:
- * `num_list`: An `orderedList` or `unorderedList` containing numeric or null values, or a `null` value.
- * Return Value:
- * An `double` value representing the average of the numbers in the given list. `null` is returned if the input is `null`, or the input list contains `null`. Non-numeric types in the input list will cause an error.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $l := for $i in dataset TwitterUsers return $i.friends_count
- return {"avg_friend_count": avg($l)}
-
- * The expected result is:
-
- { "avg_friend_count": 191.5d }
-
-### sum ###
- * Syntax:
-
- sum(num_list)
-
- * Gets the sum of the items in the given list.
- * Arguments:
- * `num_list`: An `orderedList` or `unorderedList` containing numeric or null values, or a `null` value.
- * Return Value:
- * The sum of the numbers in the given list. The returning type is decided by the item type with the highest order in the numeric type promotion order (`int8`-> `int16`->`int32`->`int64`->`float`->`double`) among items. `null` is returned if the input is `null`, or the input list contains `null`. Non-numeric types in the input list will cause an error.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $l := for $i in dataset TwitterUsers return $i.friends_count
- return {"sum_friend_count": sum($l)}
-
- * The expected result is:
-
- { "sum_friend_count": 766 }
-
-### min/max ###
- * Syntax:
-
- min(num_list), max(num_list)
-
- * Gets the min/max value of numeric items in the given list.
- * Arguments:
- * `num_list`: An `orderedList` or `unorderedList` containing the items to be compared, or a `null` value.
- * Return Value:
- * The min/max value of the given list. The returning type is decided by the item type with the highest order in the numeric type promotion order (`int8`-> `int16`->`int32`->`int64`->`float`->`double`) among items. `null` is returned if the input is `null`, or the input list contains `null`. Non-numeric types in the input list will cause an error.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $l := for $i in dataset TwitterUsers return $i. friends_count
- return {"min_friend_count": min($l), "max_friend_count": max($l)}
-
- * The expected result is:
-
- { "min_friend_count": 18, "max_friend_count": 445 }
-
-
-### sql-count ###
- * Syntax:
-
- sql-count(list)
-
- * Gets the number of non-null items in the given list.
- * Arguments:
- * `list`: An `orderedList` or `unorderedList` containing the items to be counted, or a `null` value.
- * Return Value:
- * An `int64` value representing the number of non-null items in the given list. The value `0i64` is returned if the input is `null`.
-
- * Example:
-
-
- let $l1 := ['hello', 'world', 1, 2, 3, null]
- return {"count": sql-count($l1)}
-
- * The expected result is:
-
- { "count": 5i64 }
-
-
-### sql-avg ###
-
- * Syntax:
-
- sql-avg(num_list)
-
- * Gets the average value of the non-null items in the given list.
- * Arguments:
- * `num_list`: An `orderedList` or `unorderedList` containing numeric or null values, or a `null` value.
- * Return Value:
- * A `double` value representing the average of the non-null numbers in the given list. The `null` value is returned if the input is `null`. Non-numeric types in the input list will cause an error.
-
- * Example:
-
- let $l := [1.2, 2.3, 3.4, 0, null]
- return {"avg": sql-avg($l)}
-
- * The expected result is:
-
- { "avg": 1.725d }
-
-
-### sql-sum ###
- * Syntax:
-
- sql-sum(num_list)
-
- * Gets the sum of the non-null items in the given list.
- * Arguments:
- * `num_list`: An `orderedList` or `unorderedList` containing numeric or null values, or a `null` value.
- * Return Value:
- * The sum of the non-null numbers in the given list. The returning type is decided by the item type with the highest order in the numeric type promotion order (`int8`-> `int16`->`int32`->`int64`->`float`->`double`) among items. The value `null` is returned if the input is `null`. Non-numeric types in the input list will cause an error.
-
- * Example:
-
- let $l := [1.2, 2.3, 3.4, 0, null]
- return {"sum": sql-sum($l)}
-
- * The expected result is:
-
- { "sum": 6.9d }
-
-
-### sql-min/max ###
- * Syntax:
-
- sql-min(num_list), sql-max(num_list)
-
- * Gets the min/max value of the non-null numeric items in the given list.
- * Arguments:
- * `num_list`: An `orderedList` or `unorderedList` containing the items to be compared, or a `null` value.
- * Return Value:
- * The min/max value of the given list. The returning type is decided by the item type with the highest order in the numeric type promotion order (`int8`-> `int16`->`int32`->`int64`->`float`->`double`) among items. The value `null` is returned if the input is `null`. Non-numeric types in the input list will cause an error.
-
- * Example:
-
- let $l := [1.2, 2.3, 3.4, 0, null]
- return {"min": sql-min($l), "max": sql-max($l)}
-
- * The expected result is:
-
- { "min": 0.0d, "max": 3.4d }
-
-## <a id="SpatialFunctions">Spatial Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
-### create-point ###
- * Syntax:
-
- create-point(x, y)
-
- * Creates the primitive type `point` using an `x` and `y` value.
- * Arguments:
- * `x` : A `double` that represents the x-coordinate.
- * `y` : A `double` that represents the y-coordinate.
- * Return Value:
- * A `point` representing the ordered pair (`x`, `y`).
-
- * Example:
-
- use dataverse TinySocial;
-
- let $c := create-point(30.0,70.0)
- return {"point": $c}
-
-
- * The expected result is:
-
- { "point": point("30.0,70.0") }
-
-
-### create-line ###
- * Syntax:
-
- create-line(point1, point2)
-
- * Creates the primitive type `line` using `point1` and `point2`.
- * Arguments:
- * `point1` : A `point` that represents the start point of the line.
- * `point2` : A `point` that represents the end point of the line.
- * Return Value:
- * A spatial `line` created using the points provided in `point1` and `point2`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $c := create-line(create-point(30.0,70.0), create-point(50.0,90.0))
- return {"line": $c}
-
-
- * The expected result is:
-
- { "line": line("30.0,70.0 50.0,90.0") }
-
-
-### create-rectangle ###
- * Syntax:
-
- create-rectangle(point1, point2)
-
- * Creates the primitive type `rectangle` using `point1` and `point2`.
- * Arguments:
- * `point1` : A `point` that represents the lower-left point of the rectangle.
- * `point2` : A `point` that represents the upper-right point of the rectangle.
- * Return Value:
- * A spatial `rectangle` created using the points provided in `point1` and `point2`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $c := create-rectangle(create-point(30.0,70.0), create-point(50.0,90.0))
- return {"rectangle": $c}
-
-
- * The expected result is:
-
- { "rectangle": rectangle("30.0,70.0 50.0,90.0") }
-
-
-### create-circle ###
- * Syntax:
-
- create-circle(point, radius)
-
- * Creates the primitive type `circle` using `point` and `radius`.
- * Arguments:
- * `point` : A `point` that represents the center of the circle.
- * `radius` : A `double` that represents the radius of the circle.
- * Return Value:
- * A spatial `circle` created using the center point and the radius provided in `point` and `radius`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $c := create-circle(create-point(30.0,70.0), 5.0)
- return {"circle": $c}
-
-
- * The expected result is:
-
- { "circle": circle("30.0,70.0 5.0") }
-
-
-### create-polygon ###
- * Syntax:
-
- create-polygon(list)
-
- * Creates the primitive type `polygon` using the double values provided in the argument `list`. Each two consecutive double values represent a point starting from the first double value in the list. Note that at least six double values should be specified, meaning a total of three points.
- * Arguments:
- * `list` : An OrderedList of doubles representing the points of the polygon.
- * Return Value:
- * A `polygon`, represents a spatial simple polygon created using the points provided in `list`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $c := create-polygon([1.0,1.0,2.0,2.0,3.0,3.0,4.0,4.0])
- return {"polygon": $c}
-
-
- * The expected result is:
-
- { "polygon": polygon("1.0,1.0 2.0,2.0 3.0,3.0 4.0,4.0") }
-
-
-### get-x/get-y ###
- * Syntax:
-
- get-x(point) or get-y(point)
-
- * Returns the x or y coordinates of a point `point`.
- * Arguments:
- * `point` : A `point`.
- * Return Value:
- * A `double` representing the x or y coordinates of the point `point`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $point := create-point(2.3,5.0)
- return {"x-coordinate": get-x($point), "y-coordinate": get-y($point)}
-
-
- * The expected result is:
-
- { "x-coordinate": 2.3d, "y-coordinate": 5.0d }
-
-
-### get-points ###
- * Syntax:
-
- get-points(spatial_object)
-
- * Returns an ordered list of the points forming the spatial object `spatial_object`.
- * Arguments:
- * `spatial_object` : A `point`, `line`, `rectangle`, `circle`, or `polygon`.
- * Return Value:
- * An `OrderedList` of the points forming the spatial object `spatial_object`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $line := create-line(create-point(100.6,99.4), create-point(-72.0,-76.9))
- let $rectangle := create-rectangle(create-point(9.2,49.0), create-point(77.8,111.1))
- let $polygon := create-polygon([1.0,1.0,2.0,2.0,3.0,3.0,4.0,4.0])
- let $line_list := get-points($line)
- let $rectangle_list := get-points($rectangle)
- let $polygon_list := get-points($polygon)
- return {"line-first-point": $line_list[0], "line-second-point": $line_list[1], "rectangle-left-bottom-point": $rectangle_list[0], "rectangle-top-upper-point": $rectangle_list[1], "polygon-first-point": $polygon_list[0], "polygon-second-point": $polygon_list[1], "polygon-third-point": $polygon_list[2], "polygon-forth-point": $polygon_list[3]}
-
-
- * The expected result is:
-
- { "line-first-point": point("100.6,99.4"), "line-second-point": point("-72.0,-76.9"), "rectangle-left-bottom-point": point("9.2,49.0"), "rectangle-top-upper-point": point("77.8,111.1"), "polygon-first-point": point("1.0,1.0"), "polygon-second-point": point("2.0,2.0"), "polygon-third-point": point("3.0,3.0"), "polygon-forth-point": point("4.0,4.0") }
-
-
-### get-center/get-radius ###
- * Syntax:
-
- get-center(circle_expression) or get-radius(circle_expression)
-
- * Returns the center and the radius of a circle `circle_expression`, respectively.
- * Arguments:
- * `circle_expression` : A `circle`.
- * Return Value:
- * A `point` or `double`, represent the center or radius of the circle `circle_expression`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $circle := create-circle(create-point(6.0,3.0), 1.0)
- return {"circle-radius": get-radius($circle), "circle-center": get-center($circle)}
-
-
-
- * The expected result is:
-
- { "circle-radius": 1.0d, "circle-center": point("6.0,3.0") }
-
-
-
-### spatial-distance ###
- * Syntax:
-
- spatial-distance(point1, point2)
-
- * Returns the Euclidean distance between `point1` and `point2`.
- * Arguments:
- * `point1` : A `point`.
- * `point2` : A `point`.
- * Return Value:
- * A `double` as the Euclidean distance between `point1` and `point2`.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $t in dataset('TweetMessages')
- let $d := spatial-distance($t.sender-location, create-point(30.0,70.0))
- return {"point": $t.sender-location, "distance": $d}
-
-
-
- * The expected result is:
-
- { "point": point("47.44,80.65"), "distance": 20.434678857275934d }
- { "point": point("29.15,76.53"), "distance": 6.585089217315132d }
- { "point": point("37.59,68.42"), "distance": 7.752709203884797d }
- { "point": point("24.82,94.63"), "distance": 25.168816023007512d }
- { "point": point("32.84,67.14"), "distance": 4.030533463451212d }
- { "point": point("29.72,75.8"), "distance": 5.806754687430835d }
- { "point": point("39.28,70.48"), "distance": 9.292405501268227d }
- { "point": point("40.09,92.69"), "distance": 24.832321679617472d }
- { "point": point("47.51,83.99"), "distance": 22.41250097601782d }
- { "point": point("36.21,72.6"), "distance": 6.73231758015024d }
- { "point": point("46.05,93.34"), "distance": 28.325926286707734d }
- { "point": point("36.86,74.62"), "distance": 8.270671073135482d }
-
-
-### spatial-area ###
- * Syntax:
-
- spatial-area(spatial_2d_expression)
-
- * Returns the spatial area of `spatial_2d_expression`.
- * Arguments:
- * `spatial_2d_expression` : A `rectangle`, `circle`, or `polygon`.
- * Return Value:
- * A `double` representing the area of `spatial_2d_expression`.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $circleArea := spatial-area(create-circle(create-point(0.0,0.0), 5.0))
- return {"Area":$circleArea}
-
-
-
- * The expected result is:
-
- { "Area": 78.53981625d }
-
-
-### spatial-intersect ###
- * Syntax:
-
- spatial-intersect(spatial_object1, spatial_object2)
-
- * Checks whether `@arg1` and `@arg2` spatially intersect each other.
- * Arguments:
- * `spatial_object1` : A `point`, `line`, `rectangle`, `circle`, or `polygon`.
- * `spatial_object2` : A `point`, `line`, `rectangle`, `circle`, or `polygon`.
- * Return Value:
- * A `boolean` representing whether `spatial_object1` and `spatial_object2` spatially overlap with each other.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $t in dataset('TweetMessages')
- where spatial-intersect($t.sender-location, create-rectangle(create-point(30.0,70.0), create-point(40.0,80.0)))
- return $t
-
-
- * The expected result is:
-
- { "tweetid": "4", "user": { "screen-name": "NathanGiesen@211", "lang": "en", "friends_count": 39339, "statuses_count": 473, "name": "Nathan Giesen", "followers_count": 49416 }, "sender-location": point("39.28,70.48"), "send-time": datetime("2011-12-26T10:10:00.000Z"), "referred-topics": {{ "sprint", "voice-command" }}, "message-text": " like sprint the voice-command is mind-blowing:)" }
- { "tweetid": "7", "user": { "screen-name": "ChangEwing_573", "lang": "en", "friends_count": 182, "statuses_count": 394, "name": "Chang Ewing", "followers_count": 32136 }, "sender-location": point("36.21,72.6"), "send-time": datetime("2011-08-25T10:10:00.000Z"), "referred-topics": {{ "samsung", "platform" }}, "message-text": " like samsung the platform is good" }
- { "tweetid": "9", "user": { "screen-name": "NathanGiesen@211", "lang": "en", "friends_count": 39339, "statuses_count": 473, "name": "Nathan Giesen", "followers_count": 49416 }, "sender-location": point("36.86,74.62"), "send-time": datetime("2012-07-21T10:10:00.000Z"), "referred-topics": {{ "verizon", "voicemail-service" }}, "message-text": " love verizon its voicemail-service is awesome" }
-
-
-### spatial-cell ###
- * Syntax:
-
- spatial-cell(point1, point2, x_increment, y_increment)
-
- * Returns the grid cell that `point1` belongs to.
- * Arguments:
- * `point1` : A `point` representing the point of interest that its grid cell will be returned.
- * `point2` : A `point` representing the origin of the grid.
- * `x_increment` : A `double`, represents X increments.
- * `y_increment` : A `double`, represents Y increments.
- * Return Value:
- * A `rectangle` representing the grid cell that `point1` belongs to.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $t in dataset('TweetMessages')
- group by $c := spatial-cell($t.sender-location, create-point(20.0,50.0), 5.5, 6.0) with $t
- let $num := count($t)
- return { "cell": $c, "count": $num}
-
-
- * The expected result is:
-
- { "cell": rectangle("20.0,92.0 25.5,98.0"), "count": 1i64 }
- { "cell": rectangle("25.5,74.0 31.0,80.0"), "count": 2i64 }
- { "cell": rectangle("31.0,62.0 36.5,68.0"), "count": 1i64 }
- { "cell": rectangle("31.0,68.0 36.5,74.0"), "count": 1i64 }
- { "cell": rectangle("36.5,68.0 42.0,74.0"), "count": 2i64 }
- { "cell": rectangle("36.5,74.0 42.0,80.0"), "count": 1i64 }
- { "cell": rectangle("36.5,92.0 42.0,98.0"), "count": 1i64 }
- { "cell": rectangle("42.0,80.0 47.5,86.0"), "count": 1i64 }
- { "cell": rectangle("42.0,92.0 47.5,98.0"), "count": 1i64 }
- { "cell": rectangle("47.5,80.0 53.0,86.0"), "count": 1i64 }
-
-
-
-
-## <a id="SimilarityFunctions">Similarity Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
-
-AsterixDB supports queries with different similarity functions,
-including [edit distance](http://en.wikipedia.org/wiki/Levenshtein_distance) and [Jaccard](https://en.wikipedia.org/wiki/Jaccard_index).
-
-### edit-distance ###
- * Syntax:
-
- edit-distance(expression1, expression2)
-
- * Returns the edit distance of `expression1` and `expression2`.
- * Arguments:
- * `expression1` : A `string` or a homogeneous `OrderedList` of a comparable item type.
- * `expression2` : The same type as `expression1`.
- * Return Value:
- * An `int64` that represents the edit distance between `expression1` and `expression2`.
- * Note: An [n-gram index](similarity.html#UsingIndexesToSupportSimilarityQueries) can be utilized for this function.
- * Example:
-
- use dataverse TinySocial;
-
- for $user in dataset('FacebookUsers')
- let $ed := edit-distance($user.name, "Suzanna Tilson")
- where $ed <= 2
- return $user
-
-
- * The expected result is:
-
- {
- "id": 7, "alias": "Suzanna", "name": "SuzannaTillson", "user-since": datetime("2012-08-07T10:10:00.000Z"), "friend-ids": {{ 6 }},
- "employment": [ { "organization-name": "Labzatron", "start-date": date("2011-04-19"), "end-date": null } ]
- }
-
-
-### edit-distance-check ###
- * Syntax:
-
- edit-distance-check(expression1, expression2, threshold)
-
- * Checks whether `expression1` and `expression2` have an [edit distance](http://en.wikipedia.org/wiki/Levenshtein_distance) within a given threshold. The \u201ccheck\u201d version of edit distance is faster than the "non-check" version because the former can detect whether two items satisfy a given threshold using early-termination techniques, as opposed to computing their real distance. Although possible, it is not necessary for the user to write queries using the \u201ccheck\u201d versions explicitly, since a rewrite rule can perform an appropriate transformation from a \u201cnon-check\u201d version to a \u201ccheck\u201d version.
-
- * Arguments:
- * `expression1` : A `string` or a homogeneous `OrderedList` of a comparable item type.
- * `expression2` : The same type as `expression1`.
- * `threshold` : An `int64` that represents the distance threshold.
- * Return Value:
- * An `OrderedList` with two items:
- * The first item contains a `boolean` value representing whether `expression1` and `expression2` are similar.
- * The second item contains an `int64` that represents the edit distance of `expression1` and `expression2` if it is within the threshold, or 0 otherwise.
- * Note: An [n-gram index](similarity.html#UsingIndexesToSupportSimilarityQueries) can be utilized for this function.
- * Example:
-
- use dataverse TinySocial;
-
- for $user in dataset('FacebookUsers')
- let $ed := edit-distance-check($user.name, "Suzanna Tilson", 2)
- where $ed[0]
- return $ed[1]
-
-
- * The expected result is:
-
- 2
-
-### edit-distance-contains ###
-* Syntax:
-
- edit-distance-contains(expression1, expression2, threshold)
-
-* Checks whether `expression1` contains `expression2` with an [edit distance](http://en.wikipedia.org/wiki/Levenshtein_distance) within a given threshold.
-
-* Arguments:
- * `expression1` : A `string` or a homogeneous `OrderedList` of a comparable item type.
- * `expression2` : The same type as `expression1`.
- * `threshold` : An `int32` that represents the distance threshold.
-* Return Value:
- * An `OrderedList` with two items:
- * The first item contains a `boolean` value representing whether `expression1` can contain `expression2`.
- * The second item contains an `int32` that represents the required edit distance for `expression1` to contain `expression2` if the first item is true.
-* Note: An [n-gram index](similarity.html#UsingIndexesToSupportSimilarityQueries) can be utilized for this function.
-* Example:
-
- let $i := edit-distance-contains("happy","hapr",2)
- return $i;
-
-
-* The expected result is:
-
- [ true, 1 ]
-
-
-
-### similarity-jaccard ###
- * Syntax:
-
- similarity-jaccard(list1, list2)
-
- * Returns the [Jaccard similarity](http://en.wikipedia.org/wiki/Jaccard_index) of `list1` and `list2`.
- * Arguments:
- * `list1` : An `UnorderedList` or `OrderedList`.
- * `list2` : An `UnorderedList` or `OrderedList`.
- * Return Value:
- * A `float` that represents the Jaccard similarity of `list1` and `list2`.
- * Note: A [keyword index](similarity.html#UsingIndexesToSupportSimilarityQueries) can be utilized for this function.
- * Example:
-
- use dataverse TinySocial;
-
- for $user in dataset('FacebookUsers')
- let $sim := similarity-jaccard($user.friend-ids, [1,5,9,10])
- where $sim >= 0.6f
- return $user
-
-
- * The expected result is:
-
- {
- "id": 3, "alias": "Emory", "name": "EmoryUnk", "user-since": datetime("2012-07-10T10:10:00.000Z"), "friend-ids": {{ 1, 5, 8, 9 }},
- "employment": [ { "organization-name": "geomedia", "start-date": date("2010-06-17"), "end-date": date("2010-01-26") } ]
- }
- {
- "id": 10, "alias": "Bram", "name": "BramHatch", "user-since": datetime("2010-10-16T10:10:00.000Z"), "friend-ids": {{ 1, 5, 9 }},
- "employment": [ { "organization-name": "physcane", "start-date": date("2007-06-05"), "end-date": date("2011-11-05") } ]
- }
-
-
-### similarity-jaccard-check ###
- * Syntax:
-
- similarity-jaccard-check(list1, list2, threshold)
-
- * Checks whether `list1` and `list2` have a [Jaccard similarity](http://en.wikipedia.org/wiki/Jaccard_index) greater than or equal to threshold. Again, the \u201ccheck\u201d version of Jaccard is faster than the "non-check" version.
-
- * Arguments:
- * `list1` : An `UnorderedList` or `OrderedList`.
- * `list2` : An `UnorderedList` or `OrderedList`.
- * `threshold` : A `float` that represents the similarity threshold.
- * Return Value:
- * An `OrderedList` with two items:
- * The first item contains a `boolean` value representing whether `list1` and `list2` are similar.
- * The second item contains a `float` that represents the Jaccard similarity of `list1` and `list2` if it is greater than or equal to the threshold, or 0 otherwise.
- * Note: A [keyword index](similarity.html#UsingIndexesToSupportSimilarityQueries) can be utilized for this function.
- * Example:
-
- use dataverse TinySocial;
-
- for $user in dataset('FacebookUsers')
- let $sim := similarity-jaccard-check($user.friend-ids, [1,5,9,10], 0.6f)
- where $sim[0]
- return $sim[1]
-
-
- * The expected result is:
-
- 0.75f
- 1.0f
-
-
-### Similarity Operator ~= ###
- * "`~=`" is syntactic sugar for expressing a similarity condition with a given similarity threshold.
- * The similarity function and threshold for "`~=`" are controlled via "set" directives.
- * The "`~=`" operator returns a `boolean` value that represents whether the operands are similar.
-
- * Example for Jaccard similarity:
-
- use dataverse TinySocial;
-
- set simfunction "jaccard";
- set simthreshold "0.6f";
-
- for $user in dataset('FacebookUsers')
- where $user.friend-ids ~= [1,5,9,10]
- return $user
-
-
- * The expected result is:
-
- {
- "id": 3, "alias": "Emory", "name": "EmoryUnk", "user-since": datetime("2012-07-10T10:10:00.000Z"), "friend-ids": {{ 1, 5, 8, 9 }},
- "employment": [ { "organization-name": "geomedia", "start-date": date("2010-06-17"), "end-date": date("2010-01-26") } ]
- }
- {
- "id": 10, "alias": "Bram", "name": "BramHatch", "user-since": datetime("2010-10-16T10:10:00.000Z"), "friend-ids": {{ 1, 5, 9 }},
- "employment": [ { "organization-name": "physcane", "start-date": date("2007-06-05"), "end-date": date("2011-11-05") } ]
- }
-
-
- * Example for edit-distance similarity:
-
- use dataverse TinySocial;
-
- set simfunction "edit-distance";
- set simthreshold "2";
-
- for $user in dataset('FacebookUsers')
- where $user.name ~= "Suzanna Tilson"
- return $user
-
-
- * The expected output is:
-
- {
- "id": 7, "alias": "Suzanna", "name": "SuzannaTillson", "user-since": datetime("2012-08-07T10:10:00.000Z"), "friend-ids": {{ 6 }},
- "employment": [ { "organization-name": "Labzatron", "start-date": date("2011-04-19"), "end-date": null } ]
- }
-
-
-## <a id="TokenizingFunctions">Tokenizing Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
-### word-tokens ###
-
- * Syntax:
-
- word-tokens(string)
-
- * Returns a list of word tokens of `string` using non-alphanumeric characters as delimiters.
- * Arguments:
- * `string` : A `string` that will be tokenized.
- * Return Value:
- * An `OrderedList` of `string` word tokens.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $t in dataset('TweetMessages')
- let $tokens := word-tokens($t.message-text)
- where $t.send-time >= datetime('2012-01-01T00:00:00')
- return {
- "tweetid": $t.tweetid,
- "word-tokens": $tokens
- }
-
-
- * The expected result is:
-
- { "tweetid": "9", "word-tokens": [ "love", "verizon", "its", "voicemail", "service", "is", "awesome" ] }
-
-
-<!--### hashed-word-tokens ###
- * Syntax:
-
- hashed-word-tokens(string)
-
- * Returns a list of hashed word tokens of `string`.
- * Arguments:
- * `string` : A `string` that will be tokenized.
- * Return Value:
- * An `OrderedList` of `int32` hashed tokens.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $t in dataset('TweetMessages')
- let $tokens := hashed-word-tokens($t.message-text)
- where $t.send-time >= datetime('2012-01-01T00:00:00')
- return {
- "tweetid": $t.tweetid,
- "hashed-word-tokens": $tokens
- }
-
-
- * The expected result is:
-
- { "tweetid": "9", "hashed-word-tokens": [ -1217719622, -447857469, -1884722688, -325178649, 210976949, 285049676, 1916743959 ] }
-
-
-### counthashed-word-tokens ###
- * Syntax:
-
- counthashed-word-tokens(string)
-
- * Returns a list of hashed word tokens of `string`. The hashing mechanism gives duplicate tokens different hash values, based on the occurrence count of that token.
- * Arguments:
- * `string` : A `String` that will be tokenized.
- * Return Value:
- * An `OrderedList` of `Int32` hashed tokens.
- * Example:
-
- use dataverse TinySocial;
-
- for $t in dataset('TweetMessages')
- let $tokens := counthashed-word-tokens($t.message-text)
- where $t.send-time >= datetime('2012-01-01T00:00:00')
- return {
- "tweetid": $t.tweetid,
- "counthashed-word-tokens": $tokens
- }
-
-
- * The expected result is:
-
- { "tweetid": "9", "counthashed-word-tokens": [ -1217719622, -447857469, -1884722688, -325178649, 210976949, 285049676, 1916743959 ] }
-
-
-### gram-tokens ###
- * Syntax:
-
- gram-tokens(string, gram_length, boolean_expression)
-
- * Returns a list of gram tokens of `string`, which can be obtained by scanning the characters using a sliding window of a fixed length.
- * Arguments:
- * `string` : A `String` that will be tokenized.
- * `gram_length` : An `Int32` as the length of grams.
- * `boolean_expression` : A `Boolean` value to indicate whether to generate additional grams by pre- and postfixing `string` with special characters.
- * Return Value:
- * An `OrderedList` of String gram tokens.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $t in dataset('TweetMessages')
- let $tokens := gram-tokens($t.message-text, 3, true)
- where $t.send-time >= datetime('2012-01-01T00:00:00')
- return {
- "tweetid": $t.tweetid,
- "gram-tokens": $tokens
- }
-
-
- * The expected result is:
-
- {
- "tweetid": "9",
- "gram-tokens": [ "## ", "# l", " lo", "lov", "ove", "ve ", "e v", " ve", "ver", "eri", "riz", "izo", "zon", "on ", "n i", " it", "its", "ts ", "s v", " vo", "voi", "oic", "ice",
- "cem", "ema", "mai", "ail", "il-", "l-s", "-se", "ser", "erv", "rvi", "vic", "ice", "ce ", "e i", " is", "is ", "s a", " aw", "awe", "wes", "eso", "som", "ome", "me$", "e$$" ]
- }
-
-
-### hashed-gram-tokens ###
- * Syntax:
-
- hashed-gram-tokens(string, gram_length, boolean_expression)
-
- * Returns a list of hashed gram tokens of `string`.
- * Arguments:
- * `string` : A `String` that will be tokenized.
- * `gram_length` : An `Int32` as the length of grams.
- * `boolean_expression` : A `Boolean` to indicate whether to generate additional grams by pre- and postfixing `string` with special characters.
- * Return Value:
- * An `OrderedList` of `Int32` hashed gram tokens.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $t in dataset('TweetMessages')
- let $tokens := hashed-gram-tokens($t.message-text, 3, true)
- where $t.send-time >= datetime('2012-01-01T00:00:00')
- return {
- "tweetid": $t.tweetid,
- "hashed-gram-tokens": $tokens
- }
-
-
- * The expected result is:
-
- {
- "tweetid": "9",
- "hashed-gram-tokens": [ 40557178, -2002241593, 161665899, -856104603, -500544946, 693410611, 395674299, -1015235909, 1115608337, 1187999872, -31006095, -219180466, -1676061637,
- 1040194153, -1339307841, -1527110163, -1884722688, -179148713, -431014627, -1789789823, -1209719926, 684519765, -486734513, 1734740619, -1971673751, -932421915, -2064668066,
- -937135958, -790946468, -69070309, 1561601454, 26169001, -160734571, 1330043462, -486734513, -18796768, -470303314, 113421364, 1615760212, 1688217556, 1223719184, 536568131,
- 1682609873, 2935161, -414769471, -1027490137, 1602276102, 1050490461 ]
- }
-
-
-### counthashed-gram-tokens ###
- * Syntax:
-
- counthashed-gram-tokens(string, gram_length, boolean_expression)
-
- * Returns a list of hashed gram tokens of `string`. The hashing mechanism gives duplicate tokens different hash values, based on the occurrence count of that token.
- * Arguments:
- * `string` : A `String` that will be tokenized.
- * `gram_length` : An `Int32`, length of grams to generate.
- * `boolean_expression` : A `Boolean`, whether to generate additional grams by pre- and postfixing `string` with special characters.
- * Return Value:
- * An `OrderedList` of `Int32` hashed gram tokens.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $t in dataset('TweetMessages')
- let $tokens := counthashed-gram-tokens($t.message-text, 3, true)
- where $t.send-time >= datetime('2012-01-01T00:00:00')
- return {
- "tweetid": $t.tweetid,
- "counthashed-gram-tokens": $tokens
- }
-
-
- * The expected result is:
-
- {
- "tweetid": "9",
- "counthashed-gram-tokens": [ 40557178, -2002241593, 161665899, -856104603, -500544946, 693410611, 395674299, -1015235909, 1115608337, 1187999872, -31006095, -219180466, -1676061637,
- 1040194153, -1339307841, -1527110163, -1884722688, -179148713, -431014627, -1789789823, -1209719926, 684519765, -486734513, 1734740619, -1971673751, -932421915, -2064668066, -937135958,
- -790946468, -69070309, 1561601454, 26169001, -160734571, 1330043462, -486734512, -18796768, -470303314, 113421364, 1615760212, 1688217556, 1223719184, 536568131, 1682609873, 2935161,
- -414769471, -1027490137, 1602276102, 1050490461 ]
- }
--->
-
-## <a id="TemporalFunctions">Temporal Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
-
-
-### get-year/get-month/get-day/get-hour/get-minute/get-second/get-millisecond ###
- * Syntax:
-
- get-year/get-month/get-day/get-hour/get-minute/get-second/get-millisecond(temporal_value)
-
- * Accessors for accessing fields in a temporal value
- * Arguments:
- * `temporal_value` : a temporal value represented as one of the following types: `date`, `datetime`, `time`, and `duration`.
- * Return Value:
- * An `int64` value representing the field to be extracted.
-
- * Example:
-
- let $c1 := date("2010-10-30")
- let $c2 := datetime("1987-11-19T23:49:23.938")
- let $c3 := time("12:23:34.930+07:00")
- let $c4 := duration("P3Y73M632DT49H743M3948.94S")
-
- return {"year": get-year($c1), "month": get-month($c2), "day": get-day($c1), "hour": get-hour($c3), "min": get-minute($c4), "second": get-second($c2), "ms": get-millisecond($c4)}
-
-
- * The expected result is:
-
- { "year": 2010, "month": 11, "day": 30, "hour": 5, "min": 28, "second": 23, "ms": 94 }
-
-
-### adjust-datetime-for-timezone ###
- * Syntax:
-
- adjust-datetime-for-timezone(datetime, string)
-
- * Adjusts the given datetime `datetime` by applying the timezone information `string`.
- * Arguments:
- * `datetime` : A `datetime` value to be adjusted.
- * `string` : A `string` representing the timezone information.
- * Return Value:
- * A `string` value representing the new datetime after being adjusted by the timezone information.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('TweetMessages')
- return {"adjusted-send-time": adjust-datetime-for-timezone($i.send-time, "+08:00"), "message": $i.message-text}
-
-
- * The expected result is:
-
- { "adjusted-send-time": "2008-04-26T18:10:00.000+08:00", "message": " love t-mobile its customization is good:)" }
- { "adjusted-send-time": "2010-05-13T18:10:00.000+08:00", "message": " like verizon its shortcut-menu is awesome:)" }
- { "adjusted-send-time": "2006-11-04T18:10:00.000+08:00", "message": " like motorola the speed is good:)" }
- { "adjusted-send-time": "2011-12-26T18:10:00.000+08:00", "message": " like sprint the voice-command is mind-blowing:)" }
- { "adjusted-send-time": "2006-08-04T18:10:00.000+08:00", "message": " can't stand motorola its speed is terrible:(" }
- { "adjusted-send-time": "2010-05-07T18:10:00.000+08:00", "message": " like iphone the voice-clarity is good:)" }
- { "adjusted-send-time": "2011-08-25T18:10:00.000+08:00", "message": " like samsung the platform is good" }
- { "adjusted-send-time": "2005-10-14T18:10:00.000+08:00", "message": " like t-mobile the shortcut-menu is awesome:)" }
- { "adjusted-send-time": "2012-07-21T18:10:00.000+08:00", "message": " love verizon its voicemail-service is awesome" }
- { "adjusted-send-time": "2008-01-26T18:10:00.000+08:00", "message": " hate verizon its voice-clarity is OMG:(" }
- { "adjusted-send-time": "2008-03-09T18:10:00.000+08:00", "message": " can't stand iphone its platform is terrible" }
- { "adjusted-send-time": "2010-02-13T18:10:00.000+08:00", "message": " like samsung the voice-command is amazing:)" }
-
-
-### adjust-time-for-timezone ###
- * Syntax:
-
- adjust-time-for-timezone(time, string)
-
- * Adjusts the given time `time` by applying the timezone information `string`.
- * Arguments:
- * `time` : A `time` value to be adjusted.
- * `string` : A `string` representing the timezone information.
- * Return Value:
- * A `string` value representing the new time after being adjusted by the timezone information.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('TweetMessages')
- return {"adjusted-send-time": adjust-time-for-timezone(time-from-datetime($i.send-time), "+08:00"), "message": $i.message-text}
-
-
- * The expected result is:
-
- { "adjusted-send-time": "18:10:00.000+08:00", "message": " love t-mobile its customization is good:)" }
- { "adjusted-send-time": "18:10:00.000+08:00", "message": " like verizon its shortcut-menu is awesome:)" }
- { "adjusted-send-time": "18:10:00.000+08:00", "message": " like motorola the speed is good:)" }
- { "adjusted-send-time": "18:10:00.000+08:00", "message": " like sprint the voice-command is mind-blowing:)" }
- { "adjusted-send-time": "18:10:00.000+08:00", "message": " can't stand motorola its speed is terrible:(" }
- { "adjusted-send-time": "18:10:00.000+08:00", "message": " like iphone the voice-clarity is good:)" }
- { "adjusted-send-time": "18:10:00.000+08:00", "message": " like samsung the platform is good" }
- { "adjusted-send-time": "18:10:00.000+08:00", "message": " like t-mobile the shortcut-menu is awesome:)" }
- { "adjusted-send-time": "18:10:00.000+08:00", "message": " love verizon its voicemail-service is awesome" }
- { "adjusted-send-time": "18:10:00.000+08:00", "message": " hate verizon its voice-clarity is OMG:(" }
- { "adjusted-send-time": "18:10:00.000+08:00", "message": " can't stand iphone its platform is terrible" }
- { "adjusted-send-time": "18:10:00.000+08:00", "message": " like samsung the voice-command is amazing:)" }
-
-
-### calendar-duration-from-datetime ###
- * Syntax:
-
- calendar-duration-from-datetime(datetime, duration_value)
-
- * Gets a user-friendly representation of the duration `duration_value` based on the given datetime `datetime`.
- * Arguments:
- * `datetime` : A `datetime` value to be used as the reference time point.
- * `duration_value` : A `duration` value to be converted.
- * Return Value:
- * A `duration` value with the duration as `duration_value` but with a user-friendly representation.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('TweetMessages')
- where $i.send-time > datetime("2011-01-01T00:00:00")
- return {"since-2011": subtract-datetime($i.send-time, datetime("2011-01-01T00:00:00")), "since-2011-user-friendly": calendar-duration-from-datetime($i.send-time, subtract-datetime($i.send-time, datetime("2011-01-01T00:00:00")))}
-
-
- * The expected result is:
-
- { "since-2011": duration("P359DT10H10M"), "since-2011-user-friendly": duration("P11M23DT10H10M") }
- { "since-2011": duration("P236DT10H10M"), "since-2011-user-friendly": duration("P7M23DT10H10M") }
- { "since-2011": duration("P567DT10H10M"), "since-2011-user-friendly": duration("P1Y6M18DT10H10M") }
-
-
-### get-year-month-duration/get-day-time-duration ###
- * Syntax:
-
- get-year-month-duration/get-day-time-duration(duration_value)
-
- * Extracts the correct `duration` subtype from `duration_value`.
- * Arguments:
- * `duration_value` : A `duration` value to be converted.
- * Return Value:
- * A `year-month-duration` value or a `day-time-duration` value.
-
- * Example:
-
- let $i := get-year-month-duration(duration("P12M50DT10H"))
- return $i;
-
-
- * The expected result is:
-
- year-month-duration("P1Y")
-
-### months-from-year-month-duration/milliseconds-from-day-time-duration ###
-* Syntax:
-
- months-from-year-month-duration/milliseconds-from-day-time-duration(duration_value)
-
-* Extracts the number of months or the number of milliseconds from the `duration` subtype.
-* Arguments:
- * `duration_value` : A `duration` of the correct subtype.
-* Return Value:
- * An `int64` representing the number or months/milliseconds.
-
-* Example:
-
- let $i := months-from-year-month-duration(get-year-month-duration(duration("P5Y7MT50M")))
- return $i;
-
-
-* The expected result is:
-
- 67
-
-
-### duration-from-months/duration-from-ms ###
-* Syntax:
-
- duration-from-months/duration-from-ms(number_value)
-
-* Creates a `duration` from `number_value`.
-* Arguments:
- * `number_value` : An `int64` representing the number of months/milliseconds
-* Return Value:
- * A `duration` containing `number_value` value for months/milliseconds
-
-* Example:
-
- let $i := duration-from-months(8)
- return $i;
-
-* The expected result is:
-
- duration("P8M")
-
-
-### duration-from-interval ###
-* Syntax:
-
- duration-from-interval(interval_value)
-
-* Creates a `duration` from `interval_value`.
-* Arguments:
- * `interval_value` : An `interval` value
-* Return Value:
- * A `duration` repesenting the time in the `interval_value`
-
-* Example:
-
- let $itv1 := interval("2010-10-30", "2010-12-21")
- let $itv2 := interval("2012-06-26T01:01:01.111", "2012-07-27T02:02:02.222")
- let $itv3 := interval("12:32:38", "20:29:20")
-
- return { "dr1" : duration-from-interval($itv1),
- "dr2" : duration-from-interval($itv2),
- "dr3" : duration-from-interval($itv3),
- "dr4" : duration-from-interval(null) }
-
-* The expected result is:
-
- { "dr1": day-time-duration("P52D"),
- "dr2": day-time-duration("P31DT1H1M1.111S"),
- "dr3": day-time-duration("PT7H56M42S"),
- "dr4": null }
-
-
-### current-date ###
- * Syntax:
-
- current-date()
-
- * Gets the current date.
- * Arguments: None
- * Return Value:
- * A `date` value of the date when the function is called.
-
-### current-time ###
- * Syntax:
-
- current-time()
-
- * Get the current time
- * Arguments: None
- * Return Value:
- * A `time` value of the time when the function is called.
-
-### current-datetime ###
- * Syntax:
-
- current-datetime()
-
- * Get the current datetime
- * Arguments: None
- * Return Value:
- * A `datetime` value of the datetime when the function is called.
-
- * Example:
-
- {"current-date": current-date(),
- "current-time": current-time(),
- "current-datetime": current-datetime()}
-
-
- * The expected result is:
-
- { "current-date": date("2013-04-06"),
- "current-time": time("00:48:44.093Z"),
- "current-datetime": datetime("2013-04-06T00:48:44.093Z") }
-
-
-### get-date-from-datetime ###
- * Syntax:
-
- get-date-from-datetime(datetime)
-
- * Gets the date value from the given datetime value `datetime`.
- * Arguments:
- * `datetime`: A `datetime` value to be extracted from.
- * Return Value:
- * A `date` value from the datetime.
-
-### get-time-from-datetime ###
- * Syntax:
-
- get-time-from-datetime(datetime)
-
- * Get the time value from the given datetime value `datetime`
- * Arguments:
- * `datetime`: A `datetime` value to be extracted from.
- * Return Value:
- * A `time` value from the datetime.
-
- * Example:
-
- use dataverse TinySocial;
-
- for $i in dataset('TweetMessages')
- where $i.send-time > datetime("2011-01-01T00:00:00")
- return {"send-date": get-date-from-datetime($i.send-time), "send-time": get-time-from-datetime($i.send-time)}
-
-
- * The expected result is:
-
- { "send-date": date("2011-12-26"), "send-time": time("10:10:00.000Z") }
- { "send-date": date("2011-08-25"), "send-time": time("10:10:00.000Z") }
- { "send-date": date("2012-07-21"), "send-time": time("10:10:00.000Z") }
-
-
-### day-of-week ###
-* Syntax:
-
- day-of-week(date)
-
-* Finds the day of the week for a given date (1-7)
-* Arguments:
- * `date`: A `date` value (Can also be a `datetime`)
-* Return Value:
- * An `int8` representing the day of the week (1-7)
-
-* Example:
-
- let $i := day-of-week( datetime("2012-12-30T12:12:12.039Z"))
- return $i;
-
-
-* The expected result is:
-
- 7
-
-
-### date-from-unix-time-in-days ###
- * Syntax:
-
- date-from-unix-time-in-days(numeric_value)
-
- * Gets a date representing the time after `numeric_value` days since 1970-01-01.
- * Arguments:
- * `numeric_value`: A `int8`/`int16`/`int32`/`int64` value representing the number of days.
- * Return Value:
- * A `date` value as the time after `numeric_value` days since 1970-01-01.
-
-### datetime-from-unix-time-in-ms ###
- * Syntax:
-
- datetime-from-unix-time-in-ms(numeric_value)
-
- * Gets a datetime representing the time after `numeric_value` milliseconds since 1970-01-01T00:00:00Z.
- * Arguments:
- * `numeric_value`: A `int8`/`int16`/`int32`/`int64` value representing the number of milliseconds.
- * Return Value:
- * A `datetime` value as the time after `numeric_value` milliseconds since 1970-01-01T00:00:00Z.
-
-### datetime-from-unix-time-in-secs ###
- * Syntax:
-
- datetime-from-unix-time-in-secs(numeric_value)
-
- * Gets a datetime representing the time after `numeric_value` seconds since 1970-01-01T00:00:00Z.
- * Arguments:
- * `numeric_value`: A `int8`/`int16`/`int32`/`int64` value representing the number of seconds.
- * Return Value:
- * A `datetime` value as the time after `numeric_value` seconds since 1970-01-01T00:00:00Z.
-
-
-### datetime-from-date-time ###
-* Syntax:
-
-datetime-from-date-time(date,time)
-
-* Gets a datetime representing the combination of `date` and `time`
- * Arguments:
- * `date`: A `date` value
- * `time` A `time` value
-* Return Value:
- * A `datetime` value by combining `date` and `time`
-
-### time-from-unix-time-in-ms ###
- * Syntax:
-
- time-from-unix-time-in-ms(numeric_value)
-
- * Gets a time representing the time after `numeric_value` milliseconds since 00:00:00.000Z.
- * Arguments:
- * `numeric_value`: A `int8`/`int16`/`int32`/`int64` value representing the number of milliseconds.
- * Return Value:
- * A `time` value as the time after `numeric_value` milliseconds since 00:00:00.000Z.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $d := date-from-unix-time-in-days(15800)
- let $dt := datetime-from-unix-time-in-ms(1365139700000)
- let $t := time-from-unix-time-in-ms(3748)
- return {"date": $d, "datetime": $dt, "time": $t}
-
-
- * The expected result is:
-
- { "date": date("2013-04-05"), "datetime": datetime("2013-04-05T05:28:20.000Z"), "time": time("00:00:03.748Z") }
-
-
-### unix-time-from-date-in-days ###
- * Syntax:
-
- unix-time-from-date-in-days(date_value)
-
- * Gets an integer value representing the number of days since 1970-01-01 for `date_value`.
- * Arguments:
- * `date_value`: A `date` value.
- * Return Value:
- * A `int64` value representing the number of days.
-
-### unix-time-from-datetime-in-ms ###
- * Syntax:
-
- unix-time-from-datetime-in-ms(datetime_value)
-
- * Gets an integer value representing the time in milliseconds since 1970-01-01T00:00:00Z for `datetime_value`.
- * Arguments:
- * `datetime_value` : A `datetime` value.
- * Return Value:
- * A `int64` value representing the number of milliseconds.
-
-### unix-time-from-datetime-in-secs ###
- * Syntax:
-
- unix-time-from-datetime-in-secs(datetime_value)
-
- * Gets an integer value representing the time in seconds since 1970-01-01T00:00:00Z for `datetime_value`.
- * Arguments:
- * `datetime_value` : A `datetime` value.
- * Return Value:
- * A `int64` value representing the number of seconds.
-
-
-### unix-time-from-time-in-ms ###
- * Syntax:
-
- unix-time-from-time-in-ms(time_value)
-
- * Gets an integer value representing the time the milliseconds since 00:00:00.000Z for `time_value`.
- * Arguments:
- * `time_value` : A `time` value.
- * Return Value:
- * A `int64` value representing the number of milliseconds.
-
- * Example:
-
- use dataverse TinySocial;
-
- let $d := date-from-unix-time-in-days(15800)
- let $dt := datetime-from-unix-time-in-ms(1365139700000)
- let $t := time-from-unix-time-in-ms(3748)
- return {"date": $d, "datetime": $dt, "time": $t}
-
-
- * The expected result is:
-
- { "date": date("2013-04-05"), "datetime": datetime("2013-04-05T05:28:20.000Z"), "time": time("00:00:03.748Z") }
-
-
-### parse-date/parse-time/parse-datetime ###
-* Syntax:
-
-parse-date/parse-time/parse-datetime(date,formatting_expression)
-
-* Creates a `date/time/date-time` value by treating `date` with formatting `formatting_expression`
-* Arguments:
- * `date`: A `string` value representing the `date/time/datetime`.
- * `formatting_expression` A `string` value providing the formatting for `date_expression`.Characters used to create date expression:
- * `h` hours
- * `m` minutes
- * `s` seconds
- * `n` milliseconds
- * `a` am/pm
- * `z` timezone
- * `Y` year
- * `M` month
- * `D` day
- * `W` weekday
- * `-`, `'`, `/`, `.`, `,`, `T` seperators for both time and date
-* Return Value:
- * A `date/time/date-time` value corresponding to `date`
-
-* Example:
-
- let $i := parse-time("30:30","m:s")
- return $i;
-
-* The expected result is:
-
- time("00:30:30.000Z")
-
-
-### print-date/print-time/print-datetime ###
-* Syntax:
-
- print-date/print-time/print-datetime(date,formatting_expression)
-
-* Creates a `string` representing a `date/time/date-time` value of the `date` using the formatting `formatting_expression`
-* Arguments:
- * `date`: A `date/time/datetime` value.
- * `formatting_expression` A `string` value providing the formatting for `date_expression`. Characters used to create date expression:
- * `h` hours
- * `m` minutes
- * `s` seconds
- * `n` milliseconds
- * `a` am/pm
- * `z` timezone
- * `Y` year
- * `M` month
- * `D` day
- * `W` weekday
- * `-`, `'`, `/`, `.`, `,`, `T` seperators for both time and date
-* Return Value:
- * A `string` value corresponding to `date`
-
-* Example:
-
- let $i := print-time(time("00:30:30.000Z"),"m:s")
- return $i;
-
-* The expected result is:
-
- "30:30"
-
-
-### get-interval-start, get-interval-end ###
- * Syntax:
-
- get-interval-start/get-interval-end(interval)
-
- * Gets the start/end of the given interval.
- * Arguments:
- * `interval`: the interval to be accessed.
- * Return Value:
- * A `time`, `date`, or `datetime` (depending on the time instances of the interval) representing the starting or ending time.
-
- * Example:
-
- let $itv := interval-start-from-date("1984-01-01", "P1Y")
- return {"start": get-interval-start($itv), "end": get-interval-end($itv)}
-
-
- * The expected result is:
-
- { "start": date("1984-01-01"), "end": date("1985-01-01") }
-
-
-### get-interval-start-date/get-interval-start-datetimeget-interval-start-time, get-interval-end-date/get-interval-end-datetime/get-interval-end-time ###
- * Syntax:
-
- get-interval-start-date/get-interval-start-datetime/get-interval-start-time/get-interval-end-date/get-interval-end-datetime/get-interval-end-time(interval)
-
- * Gets the start/end of the given interval for the specific date/datetime/time type.
- * Arguments:
- * `interval`: the interval to be accessed.
- * Return Value:
- * A `time`, `date`, or `datetime` (depending on the function) representing the starting or ending time.
-
- * Example:
-
- let $itv1 := interval-start-from-date("1984-01-01", "P1Y")
- let $itv2 := interval-start-from-datetime("1984-01-01T08:30:00.000", "P1Y1H")
- let $itv3 := interval-start-from-time("08:30:00.000", "P1H")
- return {"start": get-interval-start-date($itv1), "end": get-interval-end-date($itv1), "start": get-interval-start-datetime($itv2), "end": get-interval-end-datetime($itv2), "start": get-interval-start-time($itv3), "end": get-interval-end-time($itv3)}
-
-
- * The expected result is:
-
- { "start": date("1984-01-01"), "end": date("1985-01-01"), "start": datetime("1984-01-01T08:30:00.000"), "end": datetime("1984-02-01T09:30:00.000"), "start": date("08:30:00.000"), "end": time("09:30:00.000") }
-
-
-### get-overlapping-interval ###
- * Syntax:
-
- get-overlapping-interval(interval1, interval2)
-
- * Gets the start/end of the given interval for the specific date/datetime/time type.
- * Arguments:
- * `interval1`: an `interval` value
- * `interval2`: an `interval` value
- * Return Value:
- * Returns an `interval` that is overlapping `interval1` and `interval2`. If `interval1` and `interval2` do not overlap `null` is returned. Note each interval must be of the same type.
-
- * Example:
-
- { "overlap1": get-overlapping-interval(interval(time("11:23:39"), time("18:27:19")), interval(time("12:23:39"), time("23:18:00"))),
- "overlap2": get-overlapping-interval(interval(time("12:23:39"), time("18:27:19")), interval(time("07:19:39"), time("09:18:00"))),
- "overlap3": get-overlapping-interval(interval(date("1980-11-30"), date("1999-09-09")), interval(date("2013-01-01"), date("2014-01-01"))),
- "overlap4": get-overlapping-interval(interval(date("1980-11-30"), date("2099-09-09")), interval(date("2013-01-01"), date("2014-01-01"))),
- "overlap5": get-overlapping-interval(interval(datetime("1844-03-03T11:19:39"), datetime("2000-10-30T18:27:19")), interval(datetime("1989-03-04T12:23:39"), datetime("2009-10-10T23:18:00"))),
- "overlap6": get-overlapping-interval(interval(datetime("1989-03-04T12:23:39"), datetime("2000-10-30T18:27:19")), interval(datetime("1844-03-03T11:19:39"), datetime("1888-10-10T23:18:00"))) }
-
- * The expected result is:
-
- { "overlap1": interval(time("12:23:39.000Z"), time("18:27:19.000Z")),
- "overlap2": null,
- "overlap3": null,
- "overlap4": interval(date("2013-01-01"), date("2014-01-01")),
- "overlap5": interval(datetime("1989-03-04T12:23:39.000Z"), datetime("2000-10-30T18:27:19.000Z")),
- "overlap6": null }
-
-
-### interval-before/interval-after/interval-meets/interval-met-by/interval-overlaps/interval-overlapped-by/interval-overlapping/interval-starts/interval-started-by/interval-covers/interval-covered-by/interval-ends/interval-ended-by ###
-
-
-See the [Allen's Relations](allens.html).
-
-
-### interval-bin ###
- * Syntax:
-
- interval-bin(time-to-bin, time-bin-anchor, duration-bin-size)
-
- * Return the `interval` value representing the bin containing the `time-to-bin` value.
- * Arguments:
- * `time-to-bin`: a date/time/datetime value representing the time to be binned.
- * `time-bin-anchor`: a date/time/datetime value representing an anchor of a bin starts. The type of this argument should be the same as the first `time-to-bin` argument.
- * `duration-bin-size`: the duration value representing the size of the bin, in the type of year-month-duration or day-time-duration. The type of this duration should be compatible with the type of `time-to-bin`, so that the arithmetic operation between `time-to-bin` and `duration-bin-size` is well-defined. Currently AsterixDB supports the following arithmetic operations:
- * datetime +|- year-month-duration
- * datetime +|- day-time-duration
- * date +|- year-month-duration
- * date +|- day-time-duration
- * time +|- day-time-duration
- * Return Value:
- * A `interval` value representing the bin containing the `time-to-bin` value. Note that the internal type of this interval value should be the same as the `time-to-bin` type.
-
- * Example:
-
- let $c1 := date("2010-10-30")
- let $c2 := datetime("-1987-11-19T23:49:23.938")
- let $c3 := time("12:23:34.930+07:00")
-
- return { "bin1": interval-bin($c1, date("1990-01-01"), year-month-duration("P1Y")),
- "bin2": interval-bin($c2, datetime("1990-01-01T00:00:00.000Z"), year-month-duration("P6M")),
- "bin3": interval-bin($c3, time("00:00:00"), day-time-duration("PT1M")),
- "bin4": interval-bin($c2, datetime("2013-01-01T00:00:00.000"), day-time-duration("PT24H"))
- }
-
- * The expected result is:
-
- { "bin1": interval(date("2010-01-01"), date("2011-01-01")),
- "bin2": interval(datetime("-1987-07-01T00:00:00.000Z"), datetime("-1986-01-01T00:00:00.000Z")),
- "bin3": interval(time("05:23:00.000Z"), time("05:24:00.000Z")),
- "bin4": interval(datetime("-1987-11-19T00:00:00.000Z"), datetime("-1987-11-20T00:00:00.000Z")) }
-
-
-### interval-start-from-date/time/datetime ###
- * Syntax:
-
- interval-start-from-date/time/datetime(date/time/datetime, duration)
-
- * Construct an `interval` value by the given starting `date`/`time`/`datetime` and the `duration` that the interval lasts.
- * Arguments:
- * `date/time/datetime`: a `string` representing a `date`, `time` or `datetime`, or a `date`/`time`/`datetime` value, representing the starting time point.
- * `duration`: a `string` or `duration` value representing the duration of the interval. Note that duration cannot be negative value.
- * Return Value:
- * An `interval` value representing the interval starting from the given time point with the length of duration.
-
- * Example:
-
- let $itv1 := interval-start-from-date("1984-01-01", "P1Y")
- let $itv2 := interval-start-from-time(time("02:23:28.394"), "PT3H24M")
- let $itv3 := interval-start-from-datetime("1999-09-09T09:09:09.999", duration("P2M30D"))
- return {"interval1": $itv1, "interval2": $itv2, "interval3": $itv3}
-
- * The expectecd result is:
-
- { "interval1": interval(date("1984-01-01"), date("1985-01-01")),
- "interval2": interval(time("02:23:28.394Z"), time("05:47:28.394Z")),
- "interval3": interval(datetime("1999-09-09T09:09:09.999Z"), datetime("1999-12-09T09:09:09.999Z")) }
-
-
-### overlap-bins ###
- * Return Value:
- * A `interval` value representing the bin containing the `time-to-bin` value. Note that the internal type of this interval value should be the same as the `time-to-bin` type.
-
- * Syntax:
-
- overlap-bins(interval, time-bin-anchor, duration-bin-size)
-
- * Returns an ordered list of `interval` values representing each bin that is overlapping the `interval`.
- * Arguments:
- * `interval`: an `interval` value
- * `time-bin-anchor`: a date/time/datetime value representing an anchor of a bin starts. The type of this argument should be the same as the first `time-to-bin` argument.
- * `duration-bin-size`: the duration value representing the size of the bin, in the type of year-month-duration or day-time-duration. The type of this duration should be compatible with the type of `time-to-bin`, so that the arithmetic operation between `time-to-bin` and `duration-bin-size` is well-defined. Currently AsterixDB supports the following arithmetic operations:
- * datetime +|- year-month-duration
- * datetime +|- day-time-duration
- * date +|- year-month-duration
- * date +|- day-time-duration
- * time +|- day-time-duration
- * Return Value:
- * A ordered list of `interval` values representing each bin that is overlapping the `interval`. Note that the internal type as `time-to-bin` and `duration-bin-size`.
-
- * Example:
-
- let $itv1 := interval(time("17:23:37"), time("18:30:21"))
- let $itv2 := interval(date("1984-03-17"), date("2013-08-22"))
- let $itv3 := interval(datetime("1800-01-01T23:59:48.938"), datetime("2015-07-26T13:28:30.218"))
- return { "timebins": overlap-bins($itv1, time("00:00:00"), day-time-duration("PT30M")),
- "datebins": overlap-bins($itv2, date("1990-01-01"), year-month-duration("P10Y")),
- "datetimebins": overlap-bins($itv3, datetime("1900-01-01T00:00:00.000"), year-month-duration("P100Y")) }
-
- * The expected result is:
-
- { "timebins": [ interval(time("17:00:00.000Z"), time("17:30:00.000Z")),
- interval(time("17:30:00.000Z"), time("18:00:00.000Z")),
- interval(time("18:00:00.000Z"), time("18:30:00.000Z")),
- interval(time("18:30:00.000Z"), time("19:00:00.000Z")) ],
- "datebins": [ interval(date("1980-01-01"), date("1990-01-01")),
- interval(date("1990-01-01"), date("2000-01-01")),
- interval(date("2000-01-01"), date("2010-01-01")),
- interval(date("2010-01-01"), date("2020-01-01")) ],
- "datetimebins": [ interval(datetime("1800-01-01T00:00:00.000Z"), datetime("1900-01-01T00:00:00.000Z")),
- interval(datetime("1900-01-01T00:00:00.000Z"), datetime("2000-01-01T00:00:00.000Z")),
- interval(datetime("2000-01-01T00:00:00.000Z"), datetime("2100-01-01T00:00:00.000Z")) ] }
-
-
-## <a id="RecordFunctions">Record Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
-
-
-### get-record-fields ###
- * Syntax:
-
- get-record-fields(input_record)
-
- * Access the record field names, type and open status for a given record.
- * Arguments:
- * `input_record` : a record value.
- * Return Value:
- * An order list of `record` values that include the field-name `string`, field-type `string`, is-open `boolean` (used for debug purposes only: `true` if field is open and `false` otherwise), and optional nested `orderedList` for the values of a nested record.
-
- * Example:
-
- let $r1 := {"id": 1,
- "project": "AsterixDB",
- "address": {"city": "Irvine", "state": "CA"},
- "related": ["Hivestrix", "Preglix", "Apache VXQuery"] }
- return get-record-fields($r1)
-
- * The expected result is:
-
- [ { "field-name": "id", "field-type": "INT64", "is-open": false },
- { "field-name": "project", "field-type": "STRING", "is-open": false },
- { "field-name": "address", "field-type": "RECORD", "is-open": false, "nested": [
- { "field-name": "city", "field-type": "STRING", "is-open": false },
- { "field-name": "state", "field-type": "STRING", "is-open": false } ] },
- { "field-name": "related", "field-type": "ORDEREDLIST", "is-open": false, "list": [
- { "field-type": "STRING" },
- { "field-type": "STRING" },
- { "field-type": "STRING" } ] } ]
-
- ]
-### get-record-field-value ###
- * Syntax:
-
- get-record-field-value(input_record, string)
-
- * Access the field name given in the `string_expression` from the `record_expression`.
- * Arguments:
- * `input_record` : A `record` value.
- * `string` : A `string` representing the top level field name.
- * Return Value:
- * An `any` value saved in the designated field of the record.
-
- * Example:
-
- let $r1 := {"id": 1,
- "project": "AsterixDB",
- "address": {"city": "Irvine", "state": "CA"},
- "related": ["Hivestrix", "Preglix", "Apache VXQuery"] }
- return get-record-field-value($r1, "project")
-
- * The expected result is:
-
- "AsterixDB"
-
-### record-remove-fields ###
- * Syntax:
-
- record-remove-fields(input_record, field_names)
-
- * Remove indicated fields from a record given a list of field names.
- * Arguments:
- * `input_record`: a record value.
- * `field_names`: an ordered list of strings and/or ordered list of ordered list of strings.
-
- * Return Value:
- * A new record value without the fields listed in the second argument.
-
-
- * Example:
-
- let $r1 := {"id":1,
- "project":"AsterixDB",
- "address":{"city":"Irvine", "state":"CA"},
- "related":["Hivestrix", "Preglix", "Apache VXQuery"] }
- return remove-fields($r1, [["address", "city"], "related"])
-
- * The expected result is:
-
- { "id":1,
- "project":"AsterixDB",
- "address":{"state":"CA"}}
-
-### record-add-fields ###
- * Syntax:
-
- record-add-fields(input_record, fields)
-
- * Add fields from a record given a list of field names.
- * Arguments:
- * `input_record` : a record value.
- * `fields`: an ordered list of field descriptor records where each record has field-name and field-value.
- * Return Value:
- * A new record value with the new fields included.
-
-
- * Example:
-
- let $r1 := {"id":1,
- "project":"AsterixDB",
- "address":{"city":"Irvine", "state":"CA"},
- "related":["Hivestrix", "Preglix", "Apache VXQuery"] }
- return record-add-fields($r1, [{"field-name":"employment-location", "field-value":create-point(30.0,70.0)}])
-
- * The expected result is:
-
- {"id":1,
- "project":"AsterixDB",
- "address":{"city":"Irvine", "state":"CA"},
- "related":["Hivestrix", "Preglix", "Apache VXQuery"]
- "employment-location": point("30.0,70.0")}
-
-### record-merge ###
- * Syntax:
-
- record-merge(record1, record2)
-
- * Merge two different records into a new record.
- * Arguments:
- * `record1` : a record value.
- * `record2` : a record value.
- * Return Value:
- * A new record value with fields from both input records. If a field\u2019s names in both records are the same, an exception is issued.
-
-
- * Example:
-
- let $r1 := {"id":1,
- "project":"AsterixDB",
- "address":{"city":"Irvine", "state":"CA"},
- "related":["Hivestrix", "Preglix", "Apache VXQuery"] }
-
- let $r2 := {"user_id": 22,
- "employer": "UC Irvine",
- "employment-type": "visitor" }
- return record-merge($r1, $r2)
-
- * The expected result is:
-
- {"id":1,
- "project":"AsterixDB",
- "address":{"city":"Irvine", "state":"CA"},
- "related":["Hivestrix", "Preglix", "Apache VXQuery"]
- "user-id": 22,
- "employer": "UC Irvine",
- "employment-type": "visitor"}
-
-## <a id="OtherFunctions">Other Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
-
-### create-uuid ###
- * Syntax:
-
- create-uuid()
-
-* Generates a `uuid`.
-* Arguments:
- * none
-* Return Value:
- * A generated `uuid`.
-
-
-### is-null ###
- * Syntax:
-
- is-null(var)
-
- * Chec
<TRUNCATED>
[5/5] asterixdb git commit: Revise builtin function documents.
Posted by bu...@apache.org.
Revise builtin function documents.
- splitted the original function document,
- shared all function documents between SQL++ and AQL,
except the aggregation function document.
Change-Id: I4b05108b1bc741585717192b0b721ad00959bd83
Reviewed-on: https://asterix-gerrit.ics.uci.edu/1221
Sonar-Qube: Jenkins <je...@fulliautomatix.ics.uci.edu>
Tested-by: Jenkins <je...@fulliautomatix.ics.uci.edu>
Reviewed-by: Yingyi Bu <bu...@gmail.com>
Project: http://git-wip-us.apache.org/repos/asf/asterixdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/asterixdb/commit/f7f3a7f2
Tree: http://git-wip-us.apache.org/repos/asf/asterixdb/tree/f7f3a7f2
Diff: http://git-wip-us.apache.org/repos/asf/asterixdb/diff/f7f3a7f2
Branch: refs/heads/master
Commit: f7f3a7f2bd7a1743783ff5c1c1e4ede69381bcf5
Parents: ccb1408
Author: Yingyi Bu <yi...@couchbase.com>
Authored: Sun Oct 2 21:18:30 2016 -0700
Committer: Yingyi Bu <bu...@gmail.com>
Committed: Sun Oct 2 23:37:11 2016 -0700
----------------------------------------------------------------------
asterixdb/asterix-doc/pom.xml | 10 +-
.../src/main/markdown/builtins/0_toc.md | 37 +
.../src/main/markdown/builtins/10_comparison.md | 76 +
.../src/main/markdown/builtins/11_others.md | 249 ++
.../src/main/markdown/builtins/1_numeric.md | 518 ++++
.../src/main/markdown/builtins/2_string.md | 690 +++++
.../src/main/markdown/builtins/3_binary.md | 143 +
.../src/main/markdown/builtins/4_spatial.md | 326 +++
.../src/main/markdown/builtins/5_similarity.md | 146 +
.../src/main/markdown/builtins/6_tokenizing.md | 45 +
.../src/main/markdown/builtins/7_allens.md | 277 ++
.../src/main/markdown/builtins/7_temporal.md | 803 ++++++
.../src/main/markdown/builtins/8_record.md | 235 ++
.../main/markdown/builtins/9_aggregate_aql.md | 297 ++
.../main/markdown/builtins/9_aggregate_sql.md | 303 ++
.../src/main/markdown/sqlpp/0_toc.md | 19 +
.../src/main/markdown/sqlpp/1_intro.md | 19 +
.../src/main/markdown/sqlpp/2_expr.md | 19 +
.../src/main/markdown/sqlpp/3_query.md | 40 +-
.../src/main/markdown/sqlpp/4_ddl.md | 19 +
.../asterix-doc/src/site/markdown/aql/allens.md | 274 --
.../src/site/markdown/aql/functions.md | 2676 ------------------
asterixdb/asterix-doc/src/site/site.xml | 7 +-
23 files changed, 4261 insertions(+), 2967 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/pom.xml
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/pom.xml b/asterixdb/asterix-doc/pom.xml
index ab28e81..27a6095 100644
--- a/asterixdb/asterix-doc/pom.xml
+++ b/asterixdb/asterix-doc/pom.xml
@@ -48,7 +48,7 @@
<version>1.8</version>
<executions>
<execution>
- <id>concat</id>
+ <id>manual</id>
<phase>pre-site</phase>
<configuration>
<target>
@@ -56,6 +56,14 @@
<filelist dir="${project.basedir}/src/main/markdown/sqlpp"
files="0_toc.md,1_intro.md,2_expr.md,3_query.md,4_ddl.md"/>
</concat>
+ <concat destfile="${project.build.directory}/generated-site/markdown/sqlpp/builtins.md">
+ <filelist dir="${project.basedir}/src/main/markdown/builtins"
+ files="0_toc.md,1_numeric.md,2_string.md,3_binary.md,4_spatial.md,5_similarity.md,6_tokenizing.md,7_temporal.md,7_allens.md,8_record.md,9_aggregate_sql.md,10_comparison.md,11_others.md"/>
+ </concat>
+ <concat destfile="${project.build.directory}/generated-site/markdown/aql/builtins.md">
+ <filelist dir="${project.basedir}/src/main/markdown/builtins"
+ files="0_toc.md,1_numeric.md,2_string.md,3_binary.md,4_spatial.md,5_similarity.md,6_tokenizing.md,7_temporal.md,7_allens.md,8_record.md,9_aggregate_aql.md,10_comparison.md,11_others.md"/>
+ </concat>
</target>
</configuration>
<goals>
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/0_toc.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/0_toc.md b/asterixdb/asterix-doc/src/main/markdown/builtins/0_toc.md
new file mode 100644
index 0000000..2c8dedf
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/0_toc.md
@@ -0,0 +1,37 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+# Builtin Functions #
+
+## <a id="toc">Table of Contents</a> ##
+
+* [Numeric Functions](#NumericFunctions)
+* [String Functions](#StringFunctions)
+* [Binary Functions](#BinaryFunctions)
+* [Spatial Functions](#SpatialFunctions)
+* [Similarity Functions](#SimilarityFunctions)
+* [Tokenizing Functions](#TokenizingFunctions)
+* [Temporal Functions](#TemporalFunctions)
+* [Record Functions](#RecordFunctions)
+* [Aggregate Functions (Array Functions)](#AggregateFunctions)
+* [Comparison Functions](#ComparisonFunctions)
+* [Other Functions](#OtherFunctions)
+
+The system provides various classes of functions to support operations on numeric, string, spatial, and temporal data.
+This document explains how to use these functions.
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/10_comparison.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/10_comparison.md b/asterixdb/asterix-doc/src/main/markdown/builtins/10_comparison.md
new file mode 100644
index 0000000..9a19566
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/10_comparison.md
@@ -0,0 +1,76 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+## <a id="ComparisonFunctions">Comparison Functions</a> ##
+
+### greatest ###
+ * Syntax:
+
+ greatest(numeric_value1, numeric_value2, ...)
+
+ * Computes the greatest value among arguments.
+ * Arguments:
+ * `numeric_value1`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value,
+ * `numeric_value2`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value,
+ * ....
+ * Return Value:
+ * the greatest values among arguments.
+ The returning type is decided by the item type with the highest
+ order in the numeric type promotion order (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`)
+ among items.
+ * `null` if any argument is a `missing` value or `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": greatest(1, 2, 3), "v2": greatest(float("0.5"), double("-0.5"), 5000) };
+
+
+ * The expected result is:
+
+ { "v1": 3, "v2": 5000.0 }
+
+
+### least ###
+ * Syntax:
+
+ least(numeric_value1, numeric_value2, ...)
+
+ * Computes the least value among arguments.
+ * Arguments:
+ * `numeric_value1`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value,
+ * `numeric_value2`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value,
+ * ....
+ * Return Value:
+ * the least values among arguments.
+ The returning type is decided by the item type with the highest
+ order in the numeric type promotion order (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`)
+ among items.
+ * `null` if any argument is a `missing` value or `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": least(1, 2, 3), "v2": least(float("0.5"), double("-0.5"), 5000) };
+
+
+ * The expected result is:
+
+ { "v1": 1, "v2": -0.5 }
+
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/11_others.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/11_others.md b/asterixdb/asterix-doc/src/main/markdown/builtins/11_others.md
new file mode 100644
index 0000000..a20b8b3
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/11_others.md
@@ -0,0 +1,249 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+## <a id="OtherFunctions">Other Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
+
+### uuid ###
+ * Syntax:
+
+ uuid()
+
+* Generates a `uuid`.
+* Arguments:
+ * none
+* Return Value:
+ * a generated, random `uuid`.
+
+
+### is_null ###
+ * Syntax:
+
+ is_null(expr)
+
+ * Checks whether the given expression is evaluated to be a `null` value.
+ * Arguments:
+ * `expr` : an expression (any type is allowed).
+ * Return Value:
+ * a `boolean` on whether the variable is a `null` or not,
+ * a `missing` if the input is `missing`.
+
+ * Example:
+
+ { "v1": is_null(null), "v2": is_null(1), "v3": is_null(missing) };
+
+
+ * The expected result is:
+
+ { "v1": true, "v2": false }
+
+
+### is_missing ###
+ * Syntax:
+
+ is_missing(expr)
+
+ * Checks whether the given expression is evaluated to be a `missing` value.
+ * Arguments:
+ * `expr` : an expression (any type is allowed).
+ * Return Value:
+ * a `boolean` on whether the variable is a `missing` or not.
+
+ * Example:
+
+ { "v1": is_missing(null), "v2": is_missing(1), "v3": is_missing(missing) };
+
+
+ * The expected result is:
+
+ { "v1": false, "v2": false, "v3": true }
+
+
+### is_unknown ###
+ * Syntax:
+
+ is_unknown(expr)
+
+ * Checks whether the given variable is a `null` value or a `missing` value.
+ * Arguments:
+ * `expr` : an expression (any type is allowed).
+ * Return Value:
+ * a `boolean` on whether the variable is a `null`/``missing` value (`true`) or not (`false`).
+
+ * Example:
+
+ { "v1": is_unknown(null), "v2": is_unknown(1), "v3": is_unknown(missing) };
+
+
+ * The expected result is:
+
+ { "v1": true, "v2": false, "v3": true }
+
+
+### len ###
+ * Syntax:
+
+ len(array)
+
+ * Returns the length of the array array.
+ * Arguments:
+ * `array` : an `array`, `multiset`, `null`, or `missing`, represents the collection that needs to be checked.
+ * Return Value:
+ * an `integer` that represents the length of input array or the size of the input multiset,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value.
+
+ * Example:
+
+ len(["Hello", "World"])
+
+
+ * The expected result is:
+
+ 2
+
+
+### not ###
+ * Syntax:
+
+ not(expr)
+
+ * Inverts a `boolean` value
+ * Arguments:
+ * `expr` : an expression
+ * Return Value:
+ * a `boolean`, the inverse of `expr`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * other non-boolean argument value will cause a type error.
+ * Example:
+
+ { "v1": `not`(true), "v2": `not`(false), "v3": `not`(null), "v4": `not`(missing) };
+
+ * The expected result is:
+
+ { "v1": false, "v2": true, "v3": null }
+
+
+### range ###
+ * Syntax:
+
+ range(start_numeric_value, end_numeric_value)
+
+* Generates a series of `bigint` values based start the `start_numeric_value` until the `end_numeric_value`.
+* Arguments:
+ * `start_numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint` value representing the start value.
+ * `end_numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint` value representing the max final value.
+* Return Value:
+ * an array that starts with the integer value of `start_numeric_value` and ends with
+ the integer value of `end_numeric_value`, where the value of each entry in the array is
+ the integer successor of the value in the preceding entry.
+* Example:
+
+ range(0, 3);
+
+ * The expected result is:
+
+ [ 0, 1, 2, 3 ]
+
+
+### switch_case ###
+ * Syntax:
+
+ switch_case(
+ condition,
+ case1, case1_result,
+ case2, case2_result,
+ ...,
+ default, default_result
+ )
+
+ * Switches amongst a sequence of cases and returns the result of the first matching case. If no match is found, the result of the default case is returned.
+ * Arguments:
+ * `condition`: a variable (any type is allowed).
+ * `caseI/default`: a variable (any type is allowed).
+ * `caseI/default_result`: a variable (any type is allowed).
+ * Return Value:
+ * `caseI_result` if `condition` matches `caseI`, otherwise `default_result`.
+ * Example 1:
+
+ switch_case(
+ "a",
+ "a", 0,
+ "x", 1,
+ "y", 2,
+ "z", 3
+ );
+
+
+ * The expected result is:
+
+ 0
+
+ * Example 2:
+
+ switch_case(
+ "a",
+ "x", 1,
+ "y", 2,
+ "z", 3
+ );
+
+ * The expected result is:
+
+ 3
+
+
+### deep_equal ###
+* Syntax:
+
+ deep_equal(expr1, expr2)
+
+
+ * Assess the equality between two expressions of any type (e.g., record, arrays, or multiset).
+ Two objects are deeply equal iff both their types and values are equal.
+ * Arguments:
+ * `expr1` : an expression,
+ * `expr2` : an expression.
+ * Return Value:
+ * `true` or `false` depending on the data equality,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value.
+
+
+ * Example:
+
+ deep_equal(
+ {
+ "id":1,
+ "project":"AsterixDB",
+ "address":{"city":"Irvine", "state":"CA"},
+ "related":["Hivestrix", "Preglix", "Apache VXQuery"]
+ },
+ {
+ "id":1,
+ "project":"AsterixDB",
+ "address":{"city":"San Diego", "state":"CA"},
+ "related":["Hivestrix", "Preglix", "Apache VXQuery"]
+ }
+ );
+
+ * The expected result is:
+
+ false
+
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/1_numeric.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/1_numeric.md b/asterixdb/asterix-doc/src/main/markdown/builtins/1_numeric.md
new file mode 100644
index 0000000..7cdc63f
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/1_numeric.md
@@ -0,0 +1,518 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+## <a id="NumericFunctions">Numeric Functions</a> ##
+### abs ###
+ * Syntax:
+
+ abs(numeric_value)
+
+ * Computes the absolute value of the argument.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * The absolute value of the argument with the same type as the input argument,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": abs(2013), "v2": abs(-4036), "v3": abs(0), "v4": abs(float("-2013.5")), "v5": abs(double("-2013.593823748327284")) };
+
+
+ * The expected result is:
+
+ { "v1": 2013, "v2": 4036, "v3": 0, "v4": 2013.5, "v5": 2013.5938237483274 }
+
+
+### acos ###
+ * Syntax:
+
+ acos(numeric_value)
+
+ * Computes the arc cosine value of the argument.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * the `double` arc cosine in radians for the argument,
+ if the argument is in the range of -1 (inclusive) to 1 (inclusive),
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error,
+ * NaN for other legitimate numeric values.
+
+ * Example:
+
+ { "v1": acos(1), "v2": acos(2), "v3": abs(0), "v4": acos(float("0.5")), "v5": acos(double("-0.5")) };
+
+
+ * The expected result is:
+
+ { "v1": 0.0, "v2": NaN, "v3": 0, "v4": 1.0471975511965979, "v5": 2.0943951023931957 }
+
+
+### asin ###
+ * Syntax:
+
+ asin(numeric_value)
+
+ * Computes the arc sine value of the argument.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * the `double` arc sin in radians for the argument,
+ if the argument is in the range of -1 (inclusive) to 1 (inclusive),
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error,
+ * NaN for other legitimate numeric values.
+
+ * Example:
+
+ { "v1": asin(1), "v2": asin(2), "v3": asin(0), "v4": asin(float("0.5")), "v5": asin(double("-0.5")) };
+
+
+ * The expected result is:
+
+ { "v1": 1.5707963267948966, "v2": NaN, "v3": 0.0, "v4": 0.5235987755982989, "v5": -0.5235987755982989 }
+
+
+### atan ###
+ * Syntax:
+
+ atan(numeric_value)
+
+ * Computes the arc tangent value of the argument.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * the `double` arc tangent in radians for the argument,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": atan(1), "v2": atan(2), "v3": atan(0), "v4": atan(float("0.5")), "v5": atan(double("1000")) };
+
+
+ * The expected result is:
+
+ { "v1": 0.7853981633974483, "v2": 1.1071487177940904, "v3": 0.0, "v4": 0.4636476090008061, "v5": 1.5697963271282298 }
+
+
+### atan2 ###
+ * Syntax:
+
+ atan2(numeric_value1, numeric_value2)
+
+ * Computes the arc tangent value of arguments.
+ * Arguments:
+ * `numeric_value1`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value,
+ * `numeric_value2`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * the `double` arc tangent in radians for `numeric_value1` and `numeric_value2`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": atan2(1, 2), "v2": atan2(0, 4), "v3": atan2(float("0.5"), double("-0.5")) };
+
+
+ * The expected result is:
+
+ { "v1": 0.4636476090008061, "v2": 0.0, "v3": 2.356194490192345 }
+
+
+### ceil ###
+ * Syntax:
+
+ ceil(numeric_value)
+
+ * Computes the smallest (closest to negative infinity) number with no fractional part that is not less than the value of the argument. If the argument is already equal to mathematical integer, then the result is the same as the argument.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * The ceiling value for the given number in the same type as the input argument,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ {
+ "v1": ceil(2013),
+ "v2": ceil(-4036),
+ "v3": ceil(0.3),
+ "v4": ceil(float("-2013.2")),
+ "v5": ceil(double("-2013.893823748327284"))
+ };
+
+
+ * The expected result is:
+
+ { "v1": 2013, "v2": -4036, "v3": 1.0, "v4": -2013.0, "v5": -2013.0 }
+
+
+### cos ###
+ * Syntax:
+
+ cos(numeric_value)
+
+ * Computes the cosine value of the argument.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * the `double` cosine value for the argument,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": cos(1), "v2": cos(2), "v3": cos(0), "v4": cos(float("0.5")), "v5": cos(double("1000")) };
+
+
+ * The expected result is:
+
+ { "v1": 0.5403023058681398, "v2": -0.4161468365471424, "v3": 1.0, "v4": 0.8775825618903728, "v5": 0.562379076290703 }
+
+
+### exp ###
+ * Syntax:
+
+ exp(numeric_value)
+
+ * Computes e<sup>numeric_value</sup>.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * e<sup>numeric_value</sup>,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": exp(1), "v2": exp(2), "v3": exp(0), "v4": exp(float("0.5")), "v5": exp(double("1000")) };
+
+
+ * The expected result is:
+
+ { "v1": 2.718281828459045, "v2": 7.38905609893065, "v3": 1.0, "v4": 1.6487212707001282, "v5": Infinity }
+
+
+### floor ###
+ * Syntax:
+
+ floor(numeric_value)
+
+ * Computes the largest (closest to positive infinity) number with no fractional part that is not greater than the value.
+ If the argument is already equal to mathematical integer, then the result is the same as the argument.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * The floor value for the given number in the same type as the input argument,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ {
+ "v1": floor(2013),
+ "v2": floor(-4036),
+ "v3": floor(0.8),
+ "v4": floor(float("-2013.2")),
+ "v5": floor(double("-2013.893823748327284"))
+ };
+
+
+ * The expected result is:
+
+ { "v1": 2013, "v2": -4036, "v3": 0.0, "v4": -2014.0, "v5": -2014.0 }
+
+
+### ln ###
+ * Syntax:
+
+ ln(numeric_value)
+
+ * Computes log<sub>e</sub>numeric_value.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * log<sub>e</sub>numeric_value,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": exp(1), "v2": exp(2), "v3": exp(0), "v4": exp(float("0.5")), "v5": exp(double("1000")) };
+
+
+ * The expected result is:
+
+ { "v1": 2.718281828459045, "v2": 7.38905609893065, "v3": 1.0, "v4": 1.6487212707001282, "v5": Infinity }
+
+
+### log ###
+ * Syntax:
+
+ log(numeric_value)
+
+ * Computes log<sub>10</sub>numeric_value.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * log<sub>10</sub>numeric_value,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": exp(1), "v2": exp(2), "v3": exp(0), "v4": exp(float("0.5")), "v5": exp(double("1000")) };
+
+
+ * The expected result is:
+
+ { "v1": 2.718281828459045, "v2": 7.38905609893065, "v3": 1.0, "v4": 1.6487212707001282, "v5": Infinity }
+
+
+### atan2 ###
+ * Syntax:
+
+ power(numeric_value1, numeric_value2)
+
+ * Computes numeric_value1<sup>numeric_value2</sup>.
+ * Arguments:
+ * `numeric_value1`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value,
+ * `numeric_value2`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * numeric_value1<sup>numeric_value2</sup>,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": power(1, 2), "v3": power(0, 4), "v4": power(float("0.5"), double("-0.5")) };
+
+
+ * The expected result is:
+
+ { "v1": 1, "v3": 0, "v4": 1.4142135623730951 }
+
+
+### round ###
+ * Syntax:
+
+ round(numeric_value)
+
+ * Computes the number with no fractional part that is closest (and also closest to positive infinity) to the argument.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * The rounded value for the given number in the same type as the input argument,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ {
+ "v1": round(2013),
+ "v2": round(-4036),
+ "v3": round(0.8),
+ "v4": round(float("-2013.256")),
+ "v5": round(double("-2013.893823748327284"))
+ };
+
+
+ * The expected result is:
+
+ { "v1": 2013, "v2": -4036, "v3": 1.0, "v4": -2013.0, "v5": -2014.0 }
+
+
+### round_half_to_even ###
+ * Syntax:
+
+ round_half_to_even(numeric_value, [precision])
+
+ * Computes the closest numeric value to `numeric_value` that is a multiple of ten to the power of minus `precision`.
+ `precision` is optional and by default value `0` is used.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * `precision`: an optional `tinyint`/`smallint`/`integer`/`bigint` field representing the
+ number of digits in the fraction of the the result
+ * Return Value:
+ * The rounded value for the given number in the same type as the input argument,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-numeric value,
+ * or, the second argument is any other non-tinyint, non-smallint, non-integer, or non-bigint value.
+
+ * Example:
+
+ {
+ "v1": round_half_to_even(2013),
+ "v2": round_half_to_even(-4036),
+ "v3": round_half_to_even(0.8),
+ "v4": round_half_to_even(float("-2013.256")),
+ "v5": round_half_to_even(double("-2013.893823748327284")),
+ "v6": round_half_to_even(double("-2013.893823748327284"), 2),
+ "v7": round_half_to_even(2013, 4),
+ "v8": round_half_to_even(float("-2013.256"), 5)
+ };
+
+
+ * The expected result is:
+
+ { "v1": 2013, "v2": -4036, "v3": 1.0, "v4": -2013.0, "v5": -2014.0, "v6": -2013.89, "v7": 2013, "v8": -2013.256 }
+
+
+### sign ###
+ * Syntax:
+
+ sign(numeric_value)
+
+ * Computes the sign of the argument.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * the sign (a `tinyint`) of the argument, -1 for negative values, 0 for 0, and 1 for positive values,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": sign(1), "v2": sign(2), "v3": sign(0), "v4": sign(float("0.5")), "v5": sign(double("1000")) };
+
+
+ * The expected result is:
+
+ { "v1": 1, "v2": 1, "v3": 0, "v4": 1, "v5": -1 }
+
+
+### sin ###
+ * Syntax:
+
+ sin(numeric_value)
+
+ * Computes the sine value of the argument.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * the `double` sine value for the argument,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": sin(1), "v2": sin(2), "v3": sin(0), "v4": sin(float("0.5")), "v5": sin(double("1000")) };
+
+
+ * The expected result is:
+
+ { "v1": 0.8414709848078965, "v2": 0.9092974268256817, "v3": 0.0, "v4": 0.479425538604203, "v5": 0.8268795405320025 }
+
+
+### sqrt ###
+ * Syntax:
+
+ sqrt(numeric_value)
+
+ * Computes the square root of the argument.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * the `double` square root value for the argument,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": sqrt(1), "v2": sqrt(2), "v3": sqrt(0), "v4": sqrt(float("0.5")), "v5": sqrt(double("1000")) };
+
+
+ * The expected result is:
+
+ { "v1": 1.0, "v2": 1.4142135623730951, "v3": 0.0, "v4": 0.7071067811865476, "v5": 31.622776601683793 }
+
+
+### tan ###
+ * Syntax:
+
+ tan(numeric_value)
+
+ * Computes the tangent value of the argument.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value.
+ * Return Value:
+ * the `double` tangent value for the argument,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ { "v1": tan(1), "v2": tan(2), "v3": tan(0), "v4": tan(float("0.5")), "v5": tan(double("1000")) };
+
+
+ * The expected result is:
+
+ { "v1": 1.5574077246549023, "v2": -2.185039863261519, "v3": 0.0, "v4": 0.5463024898437905, "v5": 1.4703241557027185 }
+
+
+### trunc ###
+ * Syntax:
+
+ trunc(numeric_value, number_digits)
+
+ * Truncates the number to the given number of integer digits to the right of the decimal point (left if digits is negative).
+ Digits is 0 if not given.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint`/`float`/`double` value,
+ * `number_digits`: a `tinyint`/`smallint`/`integer`/`bigint` value.
+ * Return Value:
+ * the `double` tangent value for the argument,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is `missing`,
+ * a type error will be raised if:
+ * the first argument is any other non-numeric value,
+ * the second argument is any other non-tinyint, non-smallint, non-integer, and non-bigint value.
+
+ * Example:
+
+ { "v1": trunc(1, 1), "v2": trunc(2, -2), "v3": trunc(0.122, 2), "v4": trunc(float("11.52"), -1), "v5": trunc(double("1000.5252"), 3) };
+
+
+ * The expected result is:
+
+ { "v1": 1, "v2": 2, "v3": 0.12, "v4": 10.0, "v5": 1000.525 }
+
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/2_string.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/2_string.md b/asterixdb/asterix-doc/src/main/markdown/builtins/2_string.md
new file mode 100644
index 0000000..365b6f4
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/2_string.md
@@ -0,0 +1,690 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+## <a id="StringFunctions">String Functions</a> ##
+### concat ###
+ * Syntax:
+
+ concat(string1, string2, ...)
+
+ * Returns a concatenated string from arguments.
+ * Arguments:
+ * `string1`: a string value,
+ * `string2`: a string value,
+ * ....
+ * Return Value:
+ * a concatenated string from arguments,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error.
+
+ * Example:
+
+ concat("test ", "driven ", "development");
+
+
+ * The expected result is:
+
+ "test driven development"
+
+
+### contains ###
+ * Syntax:
+
+ contains(string, substring_to_contain)
+
+ * Checks whether the string `string` contains the string `substring_to_contain`
+ * Arguments:
+ * `string` : a `string` that might contain the given substring,
+ * `substring_to_contain` : a target `string` that might be contained.
+ * Return Value:
+ * a `boolean` value, `true` if `string` contains `substring_to_contain`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error,
+ * `false` otherwise.
+
+ * Note: an [n_gram index](similarity.html#UsingIndexesToSupportSimilarityQueries) can be utilized for this function.
+ * Example:
+
+ { "v1": contains("I like iphone", "phone"), "v2": contains("one", "phone") };
+
+
+ * The expected result is:
+
+ { "v1": true, "v2": false }
+
+
+### ends_with ###
+ * Syntax:
+
+ ends_with(string, substring_to_end_with)
+
+ * Checks whether the string `string` ends with the string `substring_to_end_with`.
+ * Arguments:
+ * `string` : a `string` that might end with the given string,
+ * `substring_to_end_with` : a `string` that might be contained as the ending substring.
+ * Return Value:
+ * a `boolean` value, `true` if `string` contains `substring_to_contain`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error,
+ * `false` otherwise.
+
+ * Example:
+
+ {
+ "v1": ends_with(" love sprint its shortcut_menu is awesome:)", ":)"),
+ "v2": ends_with(" awsome:)", ":-)")
+ };
+
+
+ * The expected result is:
+
+ { "v1": true, "v2": false }
+
+
+### initcap (title) ###
+ * Syntax:
+
+ initcap(string)
+
+ * Converts a given string `string` so that the first letter of each word is uppercase and
+ every other letter is lowercase.
+ The function has an alias called "title".
+ * Arguments:
+ * `string` : a `string` to be converted.
+ * Return Value:
+ * a `string` as the title form of the given `string`,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-string input value will cause a type error.
+
+ * Example:
+
+ { "v1": initcap("ASTERIXDB is here!"), "v2": title("ASTERIXDB is here!") };
+
+
+ * The expected result is:
+
+ { "v1": "Asterixdb Is Here!", "v2": "Asterixdb Is Here!" }
+
+
+### length ###
+ * Syntax:
+
+ length(string)
+
+ * Returns the length of the string `string`.
+ * Arguments:
+ * `string` : a `string` or `null` that represents the string to be checked.
+ * Return Value:
+ * an `bigint` that represents the length of `string`,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-string input value will cause a type error.
+
+ * Example:
+
+ length("test string");
+
+
+ * The expected result is:
+
+ 11
+
+
+### lower ###
+ * Syntax:
+
+ lower(string)
+
+ * Converts a given string `string` to its lowercase form.
+ * Arguments:
+ * `string` : a `string` to be converted.
+ * Return Value:
+ * a `string` as the lowercase form of the given `string`,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-string input value will cause a type error.
+
+ * Example:
+
+ lower("ASTERIXDB");
+
+
+ * The expected result is:
+
+ "asterixdb"
+
+
+### ltrim ###
+ * Syntax:
+
+ ltrim(string[, chars]);
+
+ * Returns a new string with all leading characters that appear in `chars` removed.
+ By default, white space is the character to trim.
+ * Arguments:
+ * `string` : a `string` to be trimmed,
+ * `chars` : a `string` that contains characters that are used to trim.
+ * Return Value:
+ * a trimmed, new `string`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error.
+
+
+ * Example:
+
+ ltrim("i like iphone", "iphone");
+
+
+ * The expected result is:
+
+ " like iphone"
+
+
+### position ###
+ * Syntax:
+
+ position(string, string_pattern)
+
+ * Returns the first position of `string_pattern` within `string`.
+ * Arguments:
+ * `string` : a `string` that might contain the pattern,
+ * `string_pattern` : a pattern `string` to be matched.
+ * Return Value:
+ * the first position that `string_pattern` appears within `string`,
+ or -1 if it does not appear,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error.
+
+ * Example:
+
+ {
+ "v1": position("pphonepp", "phone"),
+ "v2": position("hone", "phone")
+ };
+
+
+ * The expected result is:
+
+ { "v1": 1, "v2": -1 }
+
+
+### regexp_contains ###
+ * Syntax:
+
+ regexp_contains(string, string_pattern[, string_flags])
+
+ * Checks whether the strings `string` contains the regular expression
+ pattern `string_pattern` (a Java regular expression pattern).
+ * Arguments:
+ * `string` : a `string` that might contain the pattern,
+ * `string_pattern` : a pattern `string` to be matched,
+ * `string_flag` : (Optional) a `string` with flags to be used during regular expression matching.
+ * The following modes are enabled with these flags: dotall (s), multiline (m), case_insenitive (i), and comments and whitespace (x).
+ * Return Value:
+ * a `boolean`, returns `true` if `string` contains the pattern `string_pattern`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error,
+ * `false` otherwise.
+
+ * Example:
+
+ {
+ "v1": regexp_contains("pphonepp", "p*hone"),
+ "v2": regexp_contains("hone", "p+hone")
+ }
+
+
+ * The expected result is:
+
+ { "v1": true, "v2": false }
+
+
+### regexp_like ###
+ * Syntax:
+
+ regexp_like(string, string_pattern[, string_flags])
+
+ * Checks whether the string `string` exactly matches the regular expression pattern `string_pattern`
+ (a Java regular expression pattern).
+ * Arguments:
+ * `string` : a `string` that might contain the pattern,
+ * `string_pattern` : a pattern `string` that might be contained,
+ * `string_flag` : (Optional) a `string` with flags to be used during regular expression matching.
+ * The following modes are enabled with these flags: dotall (s), multiline (m), case_insenitive (i), and comments and whitespace (x).
+ * Return Value:
+ * a `boolean` value, `true` if `string` contains the pattern `string_pattern`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error,
+ * `false` otherwise.
+
+ * Example:
+
+ {
+ "v1": regexp_like(" can't stand at&t the network is horrible:(", ".*at&t.*"),
+ "v2": regexp_like("at&t", ".*att.*")
+ };
+
+ * The expected result is:
+
+ { "v1": true, "v2": false }
+
+
+### regexp_position ###
+ * Syntax:
+
+ regexp_position(string, string_pattern[, string_flags])
+
+ * Returns first position of the regular expression `string_pattern` (a Java regular expression pattern)
+ within `string`.
+ * Arguments:
+ * `string` : a `string` that might contain the pattern,
+ * `string_pattern` : a pattern `string` to be matched,
+ * `string_flag` : (Optional) a `string` with flags to be used during regular expression matching.
+ * The following modes are enabled with these flags: dotall (s), multiline (m), case_insenitive (i), and comments and whitespace (x).
+ * Return Value:
+ * the first position that the regular expression `string_pattern` appears in `string`,
+ or -1 if it does not appear.
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error.
+
+ * Example:
+
+ {
+ "v1": regexp_position("pphonepp", "p*hone"),
+ "v2": regexp_position("hone", "p+hone")
+ };
+
+
+ * The expected result is:
+
+ { "v1": 0, "v2": -1 }
+
+
+### regexp_replace ###
+ * Syntax:
+
+ regexp_replace(string, string_pattern, string_replacement[, string_flags])
+
+ * Checks whether the string `string` matches the given
+ regular expression pattern `string_pattern` (a Java regular expression pattern),
+ and replace the matched pattern `string_pattern` with the new pattern `string_replacement`.
+ * Arguments:
+ * `string` : a `string` that might contain the pattern,
+ * `string_pattern` : a pattern `string` to be matched,
+ * `string_replacement` : a pattern `string` to be used as the replacement,
+ * `string_flag` : (Optional) a `string` with flags to be used during replace.
+ * The following modes are enabled with these flags: dotall (s), multiline (m), case_insenitive (i), and comments and whitespace (x).
+ * Return Value:
+ * Returns a `string` that is obtained after the replacements,
+ * `missing` if any argument is a `missing` value,
+ * any other non-string input value will cause a type error,
+ * `null` if any argument is a `null` value but no argument is a `missing` value.
+
+ * Example:
+
+ regexp_replace(" like iphone the voicemail_service is awesome", " like iphone", "like android")
+
+
+ * The expected result is:
+
+ "like android the voicemail_service is awesome"
+
+
+### repeat ###
+ * Syntax:
+
+ repeat(string, n)
+
+ * Returns a string formed by repeating the input `string` `n` times.
+ * Arguments:
+ * `string` : a `string` to be extracted,
+ * `offset` : an `tinyint`/`smallint`/`integer`/`bigint` value as the starting offset of the substring in `string`.
+ * Return Value:
+ * a string that repeats the input `string` `n` times,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-string value,
+ * or, the second argument is not a `tinyint`, `smallint`, `integer`, or `bigint`.
+
+ * Example:
+
+ repeat("test", 3);
+
+
+ * The expected result is:
+
+ "testtesttest"
+
+
+### rtrim ###
+ * Syntax:
+
+ rtrim(string[, chars]);
+
+ * Returns a new string with all trailing characters that appear in `chars` removed.
+ By default, white space is the character to trim.
+ * Arguments:
+ * `string` : a `string` to be trimmed,
+ * `chars` : a `string` that contains characters that are used to trim.
+ * Return Value:
+ * a trimmed, new `string`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error.
+
+
+ * Example:
+
+ rtrim("i like iphone", "iphone");
+
+
+ * The expected result is:
+
+ "i like "
+
+
+### split ###
+ * Syntax:
+
+ split(string, sep)
+
+ * Splits the input `string` into an array of substrings separated by the string `sep`.
+ * Arguments:
+ * `string` : a `string` to be split.
+ * Return Value:
+ * an array of substrings by splitting the input `string` by `sep`,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-string input value will cause a type error.
+
+ * Example:
+
+ split("test driven development", " ");
+
+
+ * The expected result is:
+
+ [ "test", "driven", "development" ]
+
+
+### starts_with ###
+ * Syntax:
+
+ starts_with(string, substring_to_start_with)
+
+ * Checks whether the string `string` starts with the string `substring_to_start_with`.
+ * Arguments:
+ * `string` : a `string` that might start with the given string.
+ * `substring_to_start_with` : a `string` that might be contained as the starting substring.
+ * Return Value:
+ * a `boolean`, returns `true` if `string` starts with the string `substring_to_start_with`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error,
+ * `false` otherwise.
+
+ * Example:
+
+ {
+ "v1" : starts_with(" like the plan, amazing", " like"),
+ "v2" : starts_with("I like the plan, amazing", " like")
+ };
+
+
+ * The expected result is:
+
+ { "v1": true, "v2": false }
+
+
+### string_concat ###
+ * Syntax:
+
+ string_concat(array)
+
+ * Concatenates an array of strings `array` into a single string.
+ * Arguments:
+ * `array` : an `array` or `multiset` of `string`s (could be `null` or `missing`) to be concatenated.
+ * Return Value:
+ * the concatenated `string` value,
+ * `missing` if the argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * `missing` if any element in the input array is `missing`,
+ * `null` if any element in the input array is `null` but no element in the input array is `missing`,
+ * any other non-array input value or non-integer element in the input array will cause a type error.
+
+ * Example:
+
+ string_concat(["ASTERIX", " ", "ROCKS!"]);
+
+
+ * The expected result is:
+
+ "ASTERIX ROCKS!"
+
+
+### string_join ###
+ * Syntax:
+
+ string_join(array, string)
+
+ * Joins a array or multiset of strings `array` with the given separator `string` into a single string.
+ * Arguments:
+ * `array` : an `array` or `multiset` of strings (could be `null`) to be joined.
+ * `string` : a `string` as the separator.
+ * Return Value:
+ * the joined `string`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * `missing` if the first argument array contains a `missing`,
+ * `null` if the first argument array contains a `null` but does not contain a `missing`,
+ * a type error will be raised if:
+ * the first argument is any other non-array value, or contains any other non-string value,
+ * or, the second argument is any other non-string value.
+
+ * Example:
+
+ string_join(["ASTERIX", "ROCKS~"], "!! ");
+
+
+ * The expected result is:
+
+ "ASTERIX!! ROCKS~"
+
+
+### string_to_codepoint ###
+ * Syntax:
+
+ string_to_codepoint(string)
+
+ * Converts the string `string` to its code_based representation.
+ * Arguments:
+ * `string` : a `string` that will be converted.
+ * Return Value:
+ * an `array` of the code points for the string `string`,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-string input value will cause a type error.
+
+
+
+### codepoint_to_string ###
+ * Syntax:
+
+ codepoint_to_string(array)
+
+ * Converts the ordered code_based representation `array` to the corresponding string.
+ * Arguments:
+ * `array` : an `array` of integer code_points.
+ * Return Value:
+ * a `string` representation of `array`.
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * `missing` if any element in the input array is `missing`,
+ * `null` if any element in the input array is `null` but no element in the input array is `missing`,
+ * any other non-array input value or non-integer element in the input array will cause a type error.
+
+ * Example:
+
+ { "codes": string_to_codepoint("Hello ASTERIX!"), "string": codepoint_to_string(string_to_codepoint("Hello ASTERIX!"))};
+
+
+ * The expected result is:
+
+ { "codes": [ 72, 101, 108, 108, 111, 32, 65, 83, 84, 69, 82, 73, 88, 33 ], "string": "Hello ASTERIX!" }
+
+
+### substr ###
+ * Syntax:
+
+ substr(string, offset[, length])
+
+ * Returns the substring from the given string `string` based on the given start offset `offset` with the optional `length`.
+ * Arguments:
+ * `string` : a `string` to be extracted,
+ * `offset` : an `tinyint`/`smallint`/`integer`/`bigint` value as the starting offset of the substring in `string`,
+ * `length` : (Optional) an an `tinyint`/`smallint`/`integer`/`bigint` value as the length of the substring.
+ * Return Value:
+ * a `string` that represents the substring,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-string value,
+ * or, the second argument is not a `tinyint`, `smallint`, `integer`, or `bigint`,
+ * or, the third argument is not a `tinyint`, `smallint`, `integer`, or `bigint` if the argument is present.
+
+ * Example:
+
+ substr("test string", 6, 3);
+
+
+ * The expected result is:
+
+ "str"
+
+
+### substring_before ###
+ * Syntax:
+
+ substring_before(string, string_pattern)
+
+ * Returns the substring from the given string `string` before the given pattern `string_pattern`.
+ * Arguments:
+ * `string` : a `string` to be extracted.
+ * `string_pattern` : a `string` pattern to be searched.
+ * Return Value:
+ * a `string` that represents the substring,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error.
+
+ * Example:
+
+ substring_before(" like iphone", "iphone");
+
+
+* The expected result is:
+
+ " like "
+
+### substring_after ###
+ * Syntax:
+
+ substring_after(string, string_pattern);
+
+ * Returns the substring from the given string `string` after the given pattern `string_pattern`.
+ * Arguments:
+ * `string` : a `string` to be extracted.
+ * `string_pattern` : a `string` pattern to be searched.
+ * Return Value:
+ * a `string` that represents the substring,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error.
+
+
+ * Example:
+
+ substring_after(" like iphone", "iphone");
+
+
+ * The expected result is:
+
+ ""
+
+
+### trim ###
+ * Syntax:
+
+ trim(string[, chars]);
+
+ * Returns a new string with all leading characters that appear in `chars` removed.
+ By default, white space is the character to trim.
+ * Arguments:
+ * `string` : a `string` to be trimmed,
+ * `chars` : a `string` that contains characters that are used to trim.
+ * Return Value:
+ * a trimmed, new `string`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error.
+
+
+ * Example:
+
+ trim("i like iphone", "iphone");
+
+
+ * The expected result is:
+
+ " like "
+
+
+### upper ###
+ * Syntax:
+
+ upper(string)
+
+ * Converts a given string `string` to its uppercase form.
+ * Arguments:
+ * `string` : a `string` to be converted.
+ * Return Value:
+ * a `string` as the uppercase form of the given `string`,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-string input value will cause a type error.
+
+ * Example:
+
+ upper("hello")
+
+
+ * The expected result is:
+
+ "HELLO"
+
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/3_binary.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/3_binary.md b/asterixdb/asterix-doc/src/main/markdown/builtins/3_binary.md
new file mode 100644
index 0000000..2902496
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/3_binary.md
@@ -0,0 +1,143 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+## <a id="BinaryFunctions">Binary Functions</a> ##
+### parse_binary ###
+ * Syntax:
+
+ parse_binary(string, encoding)
+
+ * Creates a `binary` from an string encoded in `encoding` format.
+ * Arguments:
+ * `string` : an encoded `string`,
+ * `encoding` : a string notation specifies the encoding type of the given `string`.
+ Currently we support `hex` and `base64` format.
+ * Return Value:
+ * a `binary` that is decoded from the given `string`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error.
+
+ * Example:
+
+ [ parse_binary("ABCDEF0123456789","hex"), parse_binary("abcdef0123456789","HEX"), parse_binary('QXN0ZXJpeAE=',"base64") ];
+
+ * The expected result is:
+
+ [ hex("ABCDEF0123456789"), hex("ABCDEF0123456789"), hex("4173746572697801") ]
+
+### print_binary ###
+ * Syntax:
+
+ print_binary(binary, encoding)
+
+ * Prints a `binary` to the required encoding `string` format.
+ * Arguments:
+ * `binary` : a `binary` data need to be printed.
+ * `encoding` : a string notation specifies the expected encoding type.
+ Currently we support `hex` and `base64` format.
+ * Return Value:
+ * a `string` that represents the encoded format of a `binary`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error.
+
+ * Example:
+
+ [ print_binary(hex("ABCDEF0123456789"), "base64"), print_binary(base64("q83vASNFZ4k="), "hex") ]
+
+ * The expected result are:
+
+ [ "q83vASNFZ4k=", "ABCDEF0123456789" ]
+
+### binary_length ###
+ * Syntax:
+
+ binary_length(binary)
+
+ * Returns the number of bytes storing the binary data.
+ * Arguments:
+ * `binary` : a `binary` value to be checked.
+ * Return Value:
+ * an `bigint` that represents the number of bytes,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-binary input value will cause a type error.
+
+ * Example:
+
+ binary_length(hex("00AA"))
+
+ * The expected result is:
+
+ 2
+
+### sub_binary ###
+ * Syntax:
+
+ sub_binary(binary, offset[, length])
+
+ * Returns the sub binary from the given `binary` based on the given start offset with the optional `length`.
+ * Arguments:
+ * `binary` : a `binary` to be extracted,
+ * `offset` : a `tinyint`, `smallint`, `integer`, or `bigint` value
+ as the starting offset of the sub binary in `binary`,
+ * `length` : (Optional) a `tinyint`, `smallint`, `integer`, or `bigint` value
+ as the length of the sub binary.
+ * Return Value:
+ * a `binary` that represents the sub binary,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-binary value,
+ * or, the second argument is any other non-integer value,
+ * or, the third argument is any other non-integer value, if it is present.
+
+ * Example:
+
+ sub_binary(hex("AABBCCDD"), 4);
+
+ * The expected result is
+
+ hex("DD")
+
+### binary_concat ###
+ * Syntax:
+
+ binary_concat(array)
+
+ * Concatenates a binary `array` or `multiset` into a single binary.
+ * Arguments:
+ * `array` : an `array` or `multiset` of binaries (could be `null` or `missing`) to be concatenated.
+ * Return Value :
+ * the concatenated `binary` value,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * `missing` if any element in the input array is `missing`,
+ * `null` if any element in the input array is `null` but no element in the input array is `missing`,
+ * any other non-array input value or non-binary element in the input array will cause a type error.
+
+ * Example:
+
+ binary_concat([hex("42"), hex(""), hex('42')]);
+
+ * The expected result is
+
+ hex("4242")
+
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/4_spatial.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/4_spatial.md b/asterixdb/asterix-doc/src/main/markdown/builtins/4_spatial.md
new file mode 100644
index 0000000..c526844
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/4_spatial.md
@@ -0,0 +1,326 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+## <a id="SpatialFunctions">Spatial Functions</a> ##
+### create_point ###
+ * Syntax:
+
+ create_point(x, y)
+
+ * Creates the primitive type `point` using an `x` and `y` value.
+ * Arguments:
+ * `x` : a `double` that represents the x-coordinate,
+ * `y` : a `double` that represents the y-coordinate.
+ * Return Value:
+ * a `point` representing the ordered pair (`x`, `y`),
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-double input value will cause a type error.
+
+ * Example:
+
+ { "point": create_point(30.0,70.0) };
+
+
+ * The expected result is:
+
+ { "point": point("30.0,70.0") }
+
+
+### create_line ###
+ * Syntax:
+
+ create_line(point1, point2)
+
+ * Creates the primitive type `line` using `point1` and `point2`.
+ * Arguments:
+ * `point1` : a `point` that represents the start point of the line.
+ * `point2` : a `point` that represents the end point of the line.
+ * Return Value:
+ * a spatial `line` created using the points provided in `point1` and `point2`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-point input value will cause a type error.
+
+ * Example:
+
+ { "line": create_line(create_point(30.0,70.0), create_point(50.0,90.0)) };
+
+
+ * The expected result is:
+
+ { "line": line("30.0,70.0 50.0,90.0") }
+
+
+### create_rectangle ###
+ * Syntax:
+
+ create_rectangle(point1, point2)
+
+ * Creates the primitive type `rectangle` using `point1` and `point2`.
+ * Arguments:
+ * `point1` : a `point` that represents the lower_left point of the rectangle.
+ * `point2` : a `point` that represents the upper_right point of the rectangle.
+ * Return Value:
+ * a spatial `rectangle` created using the points provided in `point1` and `point2`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-point input value will cause a type error.
+
+ * Example:
+
+ { "rectangle": create_rectangle(create_point(30.0,70.0), create_point(50.0,90.0)) };
+
+
+ * The expected result is:
+
+ { "rectangle": rectangle("30.0,70.0 50.0,90.0") }
+
+
+### create_circle ###
+ * Syntax:
+
+ create_circle(point, radius)
+
+ * Creates the primitive type `circle` using `point` and `radius`.
+ * Arguments:
+ * `point` : a `point` that represents the center of the circle.
+ * `radius` : a `double` that represents the radius of the circle.
+ * Return Value:
+ * a spatial `circle` created using the center point and the radius provided in `point` and `radius`.
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-point value,
+ * or, the second argument is any other non-double value.
+
+ * Example:
+
+ { "circle": create_circle(create_point(30.0,70.0), 5.0) }
+
+
+ * The expected result is:
+
+ { "circle": circle("30.0,70.0 5.0") }
+
+
+### create_polygon ###
+ * Syntax:
+
+ create_polygon(array)
+
+ * Creates the primitive type `polygon` using the double values provided in the argument `array`.
+ Each two consecutive double values represent a point starting from the first double value in the array.
+ Note that at least six double values should be specified, meaning a total of three points.
+ * Arguments:
+ * `array` : an array of doubles representing the points of the polygon.
+ * Return Value:
+ * a `polygon`, represents a spatial simple polygon created using the points provided in `array`.
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * `missing` if any element in the input array is `missing`,
+ * `null` if any element in the input array is `null` but no element in the input array is `missing`,
+ * any other non-array input value or non-double element in the input array will cause a type error.
+
+
+ * Example:
+
+ { "polygon": create_polygon([1.0,1.0,2.0,2.0,3.0,3.0,4.0,4.0]) };
+
+
+ * The expected result is:
+
+ { "polygon": polygon("1.0,1.0 2.0,2.0 3.0,3.0 4.0,4.0") }
+
+
+### get_x/get_y ###
+ * Syntax:
+
+ get_x(point) or get_y(point)
+
+ * Returns the x or y coordinates of a point `point`.
+ * Arguments:
+ * `point` : a `point`.
+ * Return Value:
+ * a `double` representing the x or y coordinates of the point `point`,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-point input value will cause a type error.
+
+ * Example:
+
+ { "x_coordinate": get_x(create_point(2.3,5.0)), "y_coordinate": get_y(create_point(2.3,5.0)) };
+
+
+ * The expected result is:
+
+ { "x_coordinate": 2.3, "y_coordinate": 5.0 }
+
+
+### get_points ###
+ * Syntax:
+
+ get_points(spatial_object)
+
+ * Returns an ordered array of the points forming the spatial object `spatial_object`.
+ * Arguments:
+ * `spatial_object` : a `point`, `line`, `rectangle`, `circle`, or `polygon`.
+ * Return Value:
+ * an `array` of the points forming the spatial object `spatial_object`,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-spatial-object input value will cause a type error.
+
+ * Example:
+
+ get_points(create_polygon([1.0,1.0,2.0,2.0,3.0,3.0,4.0,4.0]))
+
+ * The expected result is:
+
+ [ point("1.0,1.0"), point("2.0,2.0"), point("3.0,3.0"), point("4.0,4.0") ]
+
+
+### get_center/get_radius ###
+ * Syntax:
+
+ get_center(circle_expression) or get_radius(circle_expression)
+
+ * Returns the center and the radius of a circle `circle_expression`, respectively.
+ * Arguments:
+ * `circle_expression` : a `circle`.
+ * Return Value:
+ * a `point` or `double`, represent the center or radius of the circle `circle_expression`.
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-circle input value will cause a type error.
+
+ * Example:
+
+ {
+ "circle_radius": get_radius(create_circle(create_point(6.0,3.0), 1.0)),
+ "circle_center": get_center(create_circle(create_point(6.0,3.0), 1.0))
+ };
+
+
+ * The expected result is:
+
+ { "circle_radius": 1.0, "circle_center": point("6.0,3.0") }
+
+
+
+### spatial_distance ###
+ * Syntax:
+
+ spatial_distance(point1, point2)
+
+ * Returns the Euclidean distance between `point1` and `point2`.
+ * Arguments:
+ * `point1` : a `point`.
+ * `point2` : a `point`.
+ * Return Value:
+ * a `double` as the Euclidean distance between `point1` and `point2`.
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-point input value will cause a type error.
+
+ * Example:
+
+ spatial_distance(point("47.44,80.65"), create_point(30.0,70.0));
+
+
+ * The expected result is:
+
+ 20.434678857275934
+
+### spatial_area ###
+ * Syntax:
+
+ spatial_area(spatial_2d_expression)
+
+ * Returns the spatial area of `spatial_2d_expression`.
+ * Arguments:
+ * `spatial_2d_expression` : a `rectangle`, `circle`, or `polygon`.
+ * Return Value:
+ * a `double` representing the area of `spatial_2d_expression`.
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-2d-spatial-object will cause a type error.
+
+ * Example:
+
+ spatial_area(create_circle(create_point(0.0,0.0), 5.0));
+
+
+ * The expected result is:
+
+ 78.53981625
+
+
+### spatial_intersect ###
+ * Syntax:
+
+ spatial_intersect(spatial_object1, spatial_object2)
+
+ * Checks whether `@arg1` and `@arg2` spatially intersect each other.
+ * Arguments:
+ * `spatial_object1` : a `point`, `line`, `rectangle`, `circle`, or `polygon`.
+ * `spatial_object2` : a `point`, `line`, `rectangle`, `circle`, or `polygon`.
+ * Return Value:
+ * a `boolean` representing whether `spatial_object1` and `spatial_object2` spatially overlap with each other,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-spatial-object input value will cause a type error.
+
+ * Example:
+
+ spatial_intersect(point("39.28,70.48"), create_rectangle(create_point(30.0,70.0), create_point(40.0,80.0)));
+
+
+ * The expected result is:
+
+ true
+
+### spatial_cell ###
+ * Syntax:
+
+ spatial_cell(point1, point2, x_increment, y_increment)
+
+ * Returns the grid cell that `point1` belongs to.
+ * Arguments:
+ * `point1` : a `point` representing the point of interest that its grid cell will be returned.
+ * `point2` : a `point` representing the origin of the grid.
+ * `x_increment` : a `double`, represents X increments.
+ * `y_increment` : a `double`, represents Y increments.
+ * Return Value:
+ * a `rectangle` representing the grid cell that `point1` belongs to,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first or second argument is any other non-point value,
+ * or, the second or third argument is any other non-double value.
+
+ * Example:
+
+ spatial_cell(point("39.28,70.48"), create_point(20.0,50.0), 5.5, 6.0);
+
+
+ * The expected result is:
+
+ rectangle("36.5,68.0 42.0,74.0");
+
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/5_similarity.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/5_similarity.md b/asterixdb/asterix-doc/src/main/markdown/builtins/5_similarity.md
new file mode 100644
index 0000000..89ef0f7
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/5_similarity.md
@@ -0,0 +1,146 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+## <a id="SimilarityFunctions">Similarity Functions</a> ##
+
+AsterixDB supports queries with different similarity functions,
+including [edit distance](http://en.wikipedia.org/wiki/Levenshtein_distance) and
+[Jaccard](https://en.wikipedia.org/wiki/Jaccard_index).
+
+### edit_distance ###
+ * Syntax:
+
+ edit_distance(expression1, expression2)
+
+ * Returns the edit distance of `expression1` and `expression2`.
+ * Arguments:
+ * `expression1` : a `string` or a homogeneous `array` of a comparable item type.
+ * `expression2` : The same type as `expression1`.
+ * Return Value:
+ * an `bigint` that represents the edit distance between `expression1` and `expression2`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-string input value will cause a type error.
+ * Note: an [n_gram index](similarity.html#UsingIndexesToSupportSimilarityQueries) can be utilized for this function.
+ * Example:
+
+ edit_distance("SuzannaTillson", "Suzanna Tilson");
+
+
+ * The expected result is:
+
+ 2
+
+
+### edit_distance_contains ###
+* Syntax:
+
+ edit_distance_contains(expression1, expression2, threshold)
+
+* Checks whether `expression1` contains `expression2` with an [edit distance](http://en.wikipedia.org/wiki/Levenshtein_distance) within a given threshold.
+
+* Arguments:
+ * `expression1` : a `string` or a homogeneous `array` of a comparable item type.
+ * `expression2` : The same type as `expression1`.
+ * `threshold` : a `bigint` that represents the distance threshold.
+* Return Value:
+ * an `array` with two items:
+ * The first item contains a `boolean` value representing whether `expression1` can contain `expression2`.
+ * The second item contains an `integer` that represents the required edit distance for `expression1` to contain
+ `expression2` if the first item is true.
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first or second argument is any other non-string value,
+ * or, the third argument is any other non-bigint value.
+* Note: an [n_gram index](similarity.html#UsingIndexesToSupportSimilarityQueries) can be utilized for this function.
+* Example:
+
+ edit_distance_contains("happy","hapr",2);
+
+
+* The expected result is:
+
+ [ true, 1 ]
+
+
+
+### similarity_jaccard ###
+ * Syntax:
+
+ similarity_jaccard(array1, array2)
+
+ * Returns the [Jaccard similarity](http://en.wikipedia.org/wiki/Jaccard_index) of `array1` and `array2`.
+ * Arguments:
+ * `array1` : an `array` or `multiset`.
+ * `array2` : an `array` or `multiset`.
+ * Return Value:
+ * a `float` that represents the Jaccard similarity of `array1` and `array2`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * `missing` if any element in any input array is `missing`,
+ * `null` if any element in any input array is `null` but no element in the input array is `missing`,
+ * any other non-array input value or non-integer element in any input array will cause a type error.
+
+ * Note: a [keyword index](similarity.html#UsingIndexesToSupportSimilarityQueries) can be utilized for this function.
+ * Example:
+
+ similarity_jaccard([1,5,8,9], [1,5,9,10]);
+
+
+ * The expected result is:
+
+ 0.6
+
+
+### similarity_jaccard_check ###
+ * Syntax:
+
+ similarity_jaccard_check(array1, array2, threshold)
+
+ * Checks whether `array1` and `array2` have a [Jaccard similarity](http://en.wikipedia.org/wiki/Jaccard_index) greater than or equal to threshold. Again, the \u201ccheck\u201d version of Jaccard is faster than the "non_check" version.
+
+ * Arguments:
+ * `array1` : an `array` or `multiset`.
+ * `array2` : an `array` or `multiset`.
+ * `threshold` : a `double` that represents the similarity threshold.
+ * Return Value:
+ * an `array` with two items:
+ * The first item contains a `boolean` value representing whether `array1` and `array2` are similar.
+ * The second item contains a `float` that represents the Jaccard similarity of `array1` and `array2`
+ if it is greater than or equal to the threshold, or 0 otherwise.
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * `missing` if any element in any input array is `missing`,
+ * `null` if any element in any input array is `null` but no element in the input array is `missing`,
+ * a type error will be raised if:
+ * the first or second argument is any other non-array value,
+ * or, the third argument is any other non-double value.
+
+ * Note: a [keyword index](similarity.html#UsingIndexesToSupportSimilarityQueries) can be utilized for this function.
+ * Example:
+
+ similarity_jaccard_check([1,5,8,9], [1,5,9,10], 0.6);
+
+
+ * The expected result is:
+
+ [ false, 0.0 ]
+
+
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/6_tokenizing.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/6_tokenizing.md b/asterixdb/asterix-doc/src/main/markdown/builtins/6_tokenizing.md
new file mode 100644
index 0000000..4783cc8
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/6_tokenizing.md
@@ -0,0 +1,45 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+## <a id="TokenizingFunctions">Tokenizing Functions</a> ##
+### word_tokens ###
+
+
+ * Syntax:
+
+ word_tokens(string)
+
+ * Returns an array of word tokens of `string` using non_alphanumeric characters as delimiters.
+ * Arguments:
+ * `string` : a `string` that will be tokenized.
+ * Return Value:
+ * an `array` of `string` word tokens,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-string input value will cause a type error.
+
+ * Example:
+
+ word_tokens("I like the phone, awesome!");
+
+
+ * The expected result is:
+
+ [ "i", "like", "the", "phone", "awesome" ]
+
[4/5] asterixdb git commit: Revise builtin function documents.
Posted by bu...@apache.org.
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/7_allens.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/7_allens.md b/asterixdb/asterix-doc/src/main/markdown/builtins/7_allens.md
new file mode 100644
index 0000000..1f69d8e
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/7_allens.md
@@ -0,0 +1,277 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+### interval_before, interval_after ###
+
+ * Syntax:
+
+ interval_before(interval1, interval2)
+ interval_after(interval1, interval2)
+
+ * These two functions check whether an interval happens before/after another interval.
+ * Arguments:
+ * `interval1`, `interval2`: two intervals to be compared
+ * Return Value:
+ * a `boolean` value. Specifically, `interval_before(interval1, interval2)` is true if and
+ only if `interval1.end < interval2.start`, and `interval_after(interval1, interval2)` is true
+ if and only if `interval1.start > interval2.end`.
+ * `missing` if the argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-interval input value will cause a type error.
+
+ * Examples:
+
+ {
+ "interval_before": interval_before(interval(date("2000-01-01"), date("2005-01-01")),
+ interval(date("2005-05-01"), date("2012-09-09"))),
+ "interval_after": interval_after(interval(date("2005-05-01"), date("2012-09-09")),
+ interval(date("2000-01-01"), date("2005-01-01")))
+ };
+
+ * The expected result is:
+
+ { "interval_before": true, "interval_after": true }
+
+
+### interval_covers, interval_covered_by ###
+
+ * Syntax:
+
+ interval_covers(interval1, interval2)
+ interval_covered_by(interval1, interval2)
+
+ * These two functions check whether one interval covers the other interval.
+ * Arguments:
+ * `interval1`, `interval2`: two intervals to be compared
+ * Return Value:
+ * a `boolean` value. Specifically, `interval_covers(interval1, interval2)` is true if and only if
+
+ interval1.start <= interval2.start AND interval1.end >= interval2.end
+
+ `interval_covered_by(interval1, interval2)` is true if and only if
+
+ interval2.start <= interval1.start AND interval2.end >= interval1.end
+
+ * `missing` if the argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-interval input value will cause a type error.
+
+ * Examples:
+
+ {
+ "interval_covers": interval_covers(interval(date("2000-01-01"), date("2005-01-01")),
+ interval(date("2000-03-01"), date("2004-09-09"))),
+ "interval_covered_by": interval_covered_by(interval(date("2006-08-01"), date("2007-03-01")),
+ interval(date("2004-09-10"), date("2012-08-01")))
+ };
+
+ * The expected result is:
+
+ { "interval_covers": true, "interval_covered_by": true }
+
+
+### interval_overlaps, interval_overlapped_by ###
+
+ * Syntax:
+
+ interval_overlaps(interval1, interval2)
+ interval_overlapped_by(interval1, interval2)
+
+ * These functions check whether two intervals overlap with each other.
+ * Arguments:
+ * `interval1`, `interval2`: two intervals to be compared
+ * Return Value:
+
+ * a `boolean` value. Specifically, `interval_overlaps(interval1, interval2)` is true if and only if
+
+ interval1.start < interval2.start
+ AND interval2.end > interval1.end
+ AND interval1.end > interval2.start
+
+ `interval_overlapped_by(interval1, interval2)` is true if and only if
+
+ interval2.start < interval1.start
+ AND interval1.end > interval2.end
+ AND interval2.end > interval1.start
+
+ * `missing` if the argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-interval input value will cause a type error.
+
+ Note that `interval_overlaps` and `interval_overlapped_by` are following the Allen's relations on the definition of overlap.
+
+ * Examples:
+
+ {
+ "overlaps": interval_overlaps(interval(date("2000-01-01"), date("2005-01-01")),
+ interval(date("2004-05-01"), date("2012-09-09"))),
+ "overlapped_by": interval_overlapped_by(interval(date("2006-08-01"), date("2007-03-01")),
+ interval(date("2004-05-01"), date("2012-09-09"))))
+ };
+
+ * The expected result is:
+
+ { "overlaps": true, "overlapped_by": true }
+
+
+### interval_overlapping ###
+Note that `interval_overlapping` is not an Allen's Relation, but syntactic sugar we added for the case that the intersect of two intervals is not empty. Basically this function returns true if any of these functions return true: `interval_overlaps`, `interval_overlapped_by`, `interval_covers`, or `interval_covered_by`.
+
+ * Syntax:
+
+ interval_overlapping(interval1, interval2)
+
+ * This functions check whether two intervals share any points with each other.
+ * Arguments:
+ * `interval1`, `interval2`: two intervals to be compared
+ * Return Value:
+ * a `boolean` value. Specifically, `interval_overlapping(interval1, interval2)` is true if
+
+ (interval2.start >= interval1.start
+ AND interval2.start < interval1.end)
+ OR
+ (interval2.end > interval1.start
+ AND interval2.end <= interval1.end)
+
+ * `missing` if the argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-interval input value will cause a type error.
+
+ * Examples:
+
+ {
+ "overlapping1": interval_overlapping(interval(date("2000-01-01"), date("2005-01-01")),
+ interval(date("2004-05-01"), date("2012-09-09"))),
+ "overlapping2": interval_overlapping(interval(date("2006-08-01"), date("2007-03-01")),
+ interval(date("2004-09-10"), date("2006-12-31")))
+ };
+
+ * The expected result is:
+
+ { "overlapping1": true, "overlapping2": true }
+
+
+### interval_meets, interval_met_by ###
+
+ * Syntax:
+
+ interval_meets(interval1, interval2)
+ interval_met_by(interval1, interval2)
+
+ * These two functions check whether an interval meets with another interval.
+ * Arguments:
+ * `interval1`, `interval2`: two intervals to be compared
+ * Return Value:
+ * a `boolean` value. Specifically, `interval_meets(interval1, interval2)` is true if and only if
+ `interval1.end = interval2.start`, and `interval_met_by(interval1, interval2)` is true if and only
+ if `interval1.start = interval2.end`. If any of the two inputs is `null`, `null` is returned.
+ * `missing` if the argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-interval input value will cause a type error.
+
+ * Examples:
+
+ {
+ "meets": interval_meets(interval(date("2000-01-01"), date("2005-01-01")),
+ interval(date("2005-01-01"), date("2012-09-09"))),
+ "metby": interval_met_by(interval(date("2006-08-01"), date("2007-03-01")),
+ interval(date("2004-09-10"), date("2006-08-01")))
+ };
+
+ * The expected result is:
+
+ { "meets": true, "metby": true }
+
+
+### interval_starts, interval_started_by ###
+
+ * Syntax:
+
+ interval_starts(interval1, interval2)
+ interval_started_by(interval1, interval2)
+
+ * These two functions check whether one interval starts with the other interval.
+ * Arguments:
+ * `interval1`, `interval2`: two intervals to be compared
+ * Return Value:
+ * a `boolean` value. Specifically, `interval_starts(interval1, interval2)` returns true if and only if
+
+ interval1.start = interval2.start
+ AND interval1.end <= interval2.end
+
+ `interval_started_by(interval1, interval2)` returns true if and only if
+
+ interval1.start = interval2.start
+ AND interval2.end <= interval1.end
+
+ * `missing` if the argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-interval input value will cause a type error.
+
+ * Examples:
+
+ {
+ "interval_starts": interval_starts(interval(date("2000-01-01"), date("2005-01-01")),
+ interval(date("2000-01-01"), date("2012-09-09"))),
+ "interval_started_by": interval_started_by(interval(date("2006-08-01"), date("2007-03-01")),
+ interval(date("2006-08-01"), date("2006-08-02")))
+ };
+
+ * The expected result is:
+
+ { "interval_starts": true, "interval_started_by": true }
+
+
+### interval_ends, interval_ended_by ###
+
+* Syntax:
+
+ interval_ends(interval1, interval2)
+ interval_ended_by(interval1, interval2)
+
+ * These two functions check whether one interval ends with the other interval.
+ * Arguments:
+ * `interval1`, `interval2`: two intervals to be compared
+ * Return Value:
+ * a `boolean` value. Specifically, `interval_ends(interval1, interval2)` returns true if and only if
+
+ interval1.end = interval2.end
+ AND interval1.start >= interval2.start
+
+ `interval_ended_by(interval1, interval2)` returns true if and only if
+
+ interval2.end = interval1.end
+ AND interval2.start >= interval1.start
+
+ * `missing` if the argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-interval input value will cause a type error.
+
+* Examples:
+
+ {
+ "interval_ends": interval_ends(interval(date("2000-01-01"), date("2005-01-01")),
+ interval(date("1998-01-01"), date("2005-01-01"))),
+ "interval_ended_by": interval_ended_by(interval(date("2006-08-01"), date("2007-03-01")),
+ interval(date("2006-09-10"), date("2007-03-01")))
+ };
+
+* The expected result is:
+
+ { "interval_ends": true, "interval_ended_by": true }
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/7_temporal.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/7_temporal.md b/asterixdb/asterix-doc/src/main/markdown/builtins/7_temporal.md
new file mode 100644
index 0000000..df47037
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/7_temporal.md
@@ -0,0 +1,803 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+## <a id="TemporalFunctions">Temporal Functions</a> ##
+
+### get_year/get_month/get_day/get_hour/get_minute/get_second/get_millisecond ###
+ * Syntax:
+
+ get_year/get_month/get_day/get_hour/get_minute/get_second/get_millisecond(temporal_value)
+
+ * Accessors for accessing fields in a temporal value
+ * Arguments:
+ * `temporal_value` : a temporal value represented as one of the following types: `date`, `datetime`, `time`, and `duration`.
+ * Return Value:
+ * an `bigint` value representing the field to be extracted,
+ * `missing` if the argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-interval input value will cause a type error.
+
+ * Example:
+
+ {
+ "year": get_year(date("2010-10-30")),
+ "month": get_month(datetime("1987-11-19T23:49:23.938")),
+ "day": get_day(date("2010-10-30")),
+ "hour": get_hour(time("12:23:34.930+07:00")),
+ "min": get_minute(duration("P3Y73M632DT49H743M3948.94S")),
+ "second": get_second(datetime("1987-11-19T23:49:23.938")),
+ "ms": get_millisecond(duration("P3Y73M632DT49H743M3948.94S"))
+ };
+
+
+ * The expected result is:
+
+ { "year": 2010, "month": 11, "day": 30, "hour": 5, "min": 28, "second": 23, "ms": 94 }
+
+
+### adjust_datetime_for_timezone ###
+ * Syntax:
+
+ adjust_datetime_for_timezone(datetime, string)
+
+ * Adjusts the given datetime `datetime` by applying the timezone information `string`.
+ * Arguments:
+ * `datetime` : a `datetime` value to be adjusted.
+ * `string` : a `string` representing the timezone information.
+ * Return Value:
+ * a `string` value representing the new datetime after being adjusted by the timezone information,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-datetime value,
+ * or, the second argument is any other non-string value.
+
+ * Example:
+
+ adjust_datetime_for_timezone(datetime("2008-04-26T10:10:00"), "+08:00");
+
+
+ * The expected result is:
+
+ "2008-04-26T18:10:00.000+08:00"
+
+
+### adjust_time_for_timezone ###
+ * Syntax:
+
+ adjust_time_for_timezone(time, string)
+
+ * Adjusts the given time `time` by applying the timezone information `string`.
+ * Arguments:
+ * `time` : a `time` value to be adjusted.
+ * `string` : a `string` representing the timezone information.
+ * Return Value:
+ * a `string` value representing the new time after being adjusted by the timezone information,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-time value,
+ * or, the second argument is any other non-string value.
+
+ * Example:
+
+ adjust_time_for_timezone(get_time_from_datetime(datetime("2008-04-26T10:10:00")), "+08:00");
+
+
+ * The expected result is:
+
+ "18:10:00.000+08:00"
+
+
+### calendar_duration_from_datetime ###
+ * Syntax:
+
+ calendar_duration_from_datetime(datetime, duration_value)
+
+ * Gets a user_friendly representation of the duration `duration_value` based on the given datetime `datetime`.
+ * Arguments:
+ * `datetime` : a `datetime` value to be used as the reference time point.
+ * `duration_value` : a `duration` value to be converted.
+ * Return Value:
+ * a `duration` value with the duration as `duration_value` but with a user_friendly representation,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-datetime value,
+ * or, the second argument is any other non-duration input value.
+
+ * Example:
+
+ calendar_duration_from_datetime(
+ datetime("2016-03-26T10:10:00"),
+ datetime("2016-03-26T10:10:00") - datetime("2011-01-01T00:00:00")
+ );
+
+ * The expected result is:
+
+ duration("P5Y2M24DT10H10M")
+
+
+### get_year_month_duration/get_day_time_duration ###
+ * Syntax:
+
+ get_year_month_duration/get_day_time_duration(duration_value)
+
+ * Extracts the correct `duration` subtype from `duration_value`.
+ * Arguments:
+ * `duration_value` : a `duration` value to be converted.
+ * Return Value:
+ * a `year_month_duration` value or a `day_time_duration` value,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-duration input value will cause a type error.
+
+ * Example:
+
+ get_year_month_duration(duration("P12M50DT10H"));
+
+
+ * The expected result is:
+
+ year_month_duration("P1Y")
+
+### months_from_year_month_duration/milliseconds_from_day_time_duration ###
+* Syntax:
+
+ months_from_year_month_duration/milliseconds_from_day_time_duration(duration_value)
+
+* Extracts the number of months or the number of milliseconds from the `duration` subtype.
+* Arguments:
+ * `duration_value` : a `duration` of the correct subtype.
+* Return Value:
+ * an `bigint` representing the number or months/milliseconds,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-duration input value will cause a type error.
+
+* Example:
+
+ months_from_year_month_duration(get_year_month_duration(duration("P5Y7MT50M")));
+
+
+* The expected result is:
+
+ 67
+
+
+### duration_from_months/duration_from_ms ###
+* Syntax:
+
+ duration_from_months/duration_from_ms(number_value)
+
+* Creates a `duration` from `number_value`.
+* Arguments:
+ * `number_value` : a `bigint` representing the number of months/milliseconds
+* Return Value:
+ * a `duration` containing `number_value` value for months/milliseconds,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-duration input value will cause a type error.
+
+* Example:
+
+ duration_from_months(8);
+
+* The expected result is:
+
+ duration("P8M")
+
+
+### duration_from_interval ###
+* Syntax:
+
+ duration_from_interval(interval_value)
+
+* Creates a `duration` from `interval_value`.
+* Arguments:
+ * `interval_value` : an `interval` value
+* Return Value:
+ * a `duration` representing the time in the `interval_value`
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-duration input value will cause a type error.
+
+* Example:
+
+ {
+ "dr1" : duration_from_interval(interval(date("2010-10-30"), date("2010-12-21"))),
+ "dr2" : duration_from_interval(interval(datetime("2012-06-26T01:01:01.111"), datetime("2012-07-27T02:02:02.222"))),
+ "dr3" : duration_from_interval(interval(time("12:32:38"), time("20:29:20"))),
+ "dr4" : duration_from_interval(null)
+ };
+
+* The expected result is:
+
+ {
+ "dr1": day_time_duration("P52D"),
+ "dr2": day_time_duration("P31DT1H1M1.111S"),
+ "dr3": day_time_duration("PT7H56M42S"),
+ "dr4": null
+ }
+
+
+### current_date ###
+ * Syntax:
+
+ current_date()
+
+ * Gets the current date.
+ * Arguments: None
+ * Return Value:
+ * a `date` value of the date when the function is called.
+
+### current_time ###
+ * Syntax:
+
+ current_time()
+
+ * Get the current time
+ * Arguments: None
+ * Return Value:
+ * a `time` value of the time when the function is called.
+
+### current_datetime ###
+ * Syntax:
+
+ current_datetime()
+
+ * Get the current datetime
+ * Arguments: None
+ * Return Value:
+ * a `datetime` value of the datetime when the function is called.
+
+
+### get_date_from_datetime ###
+ * Syntax:
+
+ get_date_from_datetime(datetime)
+
+ * Gets the date value from the given datetime value `datetime`.
+ * Arguments:
+ * `datetime`: a `datetime` value to be extracted from.
+ * Return Value:
+ * a `date` value from the datetime,
+ * any other non-datetime input value will cause a type error.
+
+### get_time_from_datetime ###
+ * Syntax:
+
+ get_time_from_datetime(datetime)
+
+ * Get the time value from the given datetime value `datetime`
+ * Arguments:
+ * `datetime`: a `datetime` value to be extracted from.
+ * Return Value:
+ * a `time` value from the datetime.
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-datetime input value will cause a type error.
+
+ * Example:
+
+ get_time_from_datetime(datetime("2016-03-26T10:10:00"));
+
+ * The expected result is:
+
+ time("10:10:00.000Z")
+
+
+### day_of_week ###
+* Syntax:
+
+ day_of_week(date)
+
+* Finds the day of the week for a given date (1_7)
+* Arguments:
+ * `date`: a `date` value (Can also be a `datetime`)
+* Return Value:
+ * an `tinyint` representing the day of the week (1_7),
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-date input value will cause a type error.
+
+* Example:
+
+ day_of_week(datetime("2012-12-30T12:12:12.039Z"));
+
+
+* The expected result is:
+
+ 7
+
+
+### date_from_unix_time_in_days ###
+ * Syntax:
+
+ date_from_unix_time_in_days(numeric_value)
+
+ * Gets a date representing the time after `numeric_value` days since 1970_01_01.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint` value representing the number of days.
+ * Return Value:
+ * a `date` value as the time after `numeric_value` days since 1970-01-01,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+### datetime_from_unix_time_in_ms ###
+ * Syntax:
+
+ datetime_from_unix_time_in_ms(numeric_value)
+
+ * Gets a datetime representing the time after `numeric_value` milliseconds since 1970_01_01T00:00:00Z.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint` value representing the number of milliseconds.
+ * Return Value:
+ * a `datetime` value as the time after `numeric_value` milliseconds since 1970-01-01T00:00:00Z,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+### datetime_from_unix_time_in_secs ###
+ * Syntax:
+
+ datetime_from_unix_time_in_secs(numeric_value)
+
+ * Gets a datetime representing the time after `numeric_value` seconds since 1970_01_01T00:00:00Z.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint` value representing the number of seconds.
+ * Return Value:
+ * a `datetime` value as the time after `numeric_value` seconds since 1970_01_01T00:00:00Z,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+### datetime_from_date_time ###
+* Syntax:
+
+datetime_from_date_time(date,time)
+
+* Gets a datetime representing the combination of `date` and `time`
+ * Arguments:
+ * `date`: a `date` value
+ * `time` a `time` value
+* Return Value:
+ * a `datetime` value by combining `date` and `time`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if
+ * the first argument is any other non-date value,
+ * or, the second argument is any other non-time value.
+
+### time_from_unix_time_in_ms ###
+ * Syntax:
+
+ time_from_unix_time_in_ms(numeric_value)
+
+ * Gets a time representing the time after `numeric_value` milliseconds since 00:00:00.000Z.
+ * Arguments:
+ * `numeric_value`: a `tinyint`/`smallint`/`integer`/`bigint` value representing the number of milliseconds.
+ * Return Value:
+ * a `time` value as the time after `numeric_value` milliseconds since 00:00:00.000Z,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-numeric input value will cause a type error.
+
+ * Example:
+
+ {
+ "date": date_from_unix_time_in_days(15800),
+ "datetime": datetime_from_unix_time_in_ms(1365139700000),
+ "time": time_from_unix_time_in_ms(3748)
+ };
+
+
+ * The expected result is:
+
+ { "date": date("2013-04-05"), "datetime": datetime("2013-04-05T05:28:20.000Z"), "time": time("00:00:03.748Z") }
+
+
+### unix_time_from_date_in_days ###
+ * Syntax:
+
+ unix_time_from_date_in_days(date_value)
+
+ * Gets an integer value representing the number of days since 1970_01_01 for `date_value`.
+ * Arguments:
+ * `date_value`: a `date` value.
+ * Return Value:
+ * a `bigint` value representing the number of days,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-date input value will cause a type error.
+
+
+### unix_time_from_datetime_in_ms ###
+ * Syntax:
+
+ unix_time_from_datetime_in_ms(datetime_value)
+
+ * Gets an integer value representing the time in milliseconds since 1970_01_01T00:00:00Z for `datetime_value`.
+ * Arguments:
+ * `datetime_value` : a `datetime` value.
+ * Return Value:
+ * a `bigint` value representing the number of milliseconds,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-datetime input value will cause a type error.
+
+
+### unix_time_from_datetime_in_secs ###
+ * Syntax:
+
+ unix_time_from_datetime_in_secs(datetime_value)
+
+ * Gets an integer value representing the time in seconds since 1970_01_01T00:00:00Z for `datetime_value`.
+ * Arguments:
+ * `datetime_value` : a `datetime` value.
+ * Return Value:
+ * a `bigint` value representing the number of seconds,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-datetime input value will cause a type error.
+
+
+### unix_time_from_time_in_ms ###
+ * Syntax:
+
+ unix_time_from_time_in_ms(time_value)
+
+ * Gets an integer value representing the time the milliseconds since 00:00:00.000Z for `time_value`.
+ * Arguments:
+ * `time_value` : a `time` value.
+ * Return Value:
+ * a `bigint` value representing the number of milliseconds,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-datetime input value will cause a type error.
+
+ * Example:
+
+ {
+ "date": date_from_unix_time_in_days(15800),
+ "datetime": datetime_from_unix_time_in_ms(1365139700000),
+ "time": time_from_unix_time_in_ms(3748)
+ }
+
+
+ * The expected result is:
+
+ { "date": date("2013-04-05"), "datetime": datetime("2013-04-05T05:28:20.000Z"), "time": time("00:00:03.748Z") }
+
+
+### parse_date/parse_time/parse_datetime ###
+* Syntax:
+
+parse_date/parse_time/parse_datetime(date,formatting_expression)
+
+* Creates a `date/time/date_time` value by treating `date` with formatting `formatting_expression`
+* Arguments:
+ * `date`: a `string` value representing the `date/time/datetime`.
+ * `formatting_expression` a `string` value providing the formatting for `date_expression`.Characters used to create date expression:
+ * `h` hours
+ * `m` minutes
+ * `s` seconds
+ * `n` milliseconds
+ * `a` am/pm
+ * `z` timezone
+ * `Y` year
+ * `M` month
+ * `D` day
+ * `W` weekday
+ * `_`, `'`, `/`, `.`, `,`, `T` seperators for both time and date
+* Return Value:
+ * a `date/time/date_time` value corresponding to `date`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-date value,
+ * the second argument is any other non-string value.
+
+* Example:
+
+ parse_time("30:30","m:s");
+
+* The expected result is:
+
+ time("00:30:30.000Z")
+
+
+### print_date/print_time/print_datetime ###
+* Syntax:
+
+ print_date/print_time/print_datetime(date,formatting_expression)
+
+* Creates a `string` representing a `date/time/date_time` value of the `date` using the formatting `formatting_expression`
+* Arguments:
+ * `date`: a `date/time/datetime` value.
+ * `formatting_expression` a `string` value providing the formatting for `date_expression`. Characters used to create date expression:
+ * `h` hours
+ * `m` minutes
+ * `s` seconds
+ * `n` milliseconds
+ * `a` am/pm
+ * `z` timezone
+ * `Y` year
+ * `M` month
+ * `D` day
+ * `W` weekday
+ * `_`, `'`, `/`, `.`, `,`, `T` seperators for both time and date
+* Return Value:
+ * a `string` value corresponding to `date`,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-date value,
+ * the second argument is any other non-string value.
+
+* Example:
+
+ print_time(time("00:30:30.000Z"),"m:s");
+
+* The expected result is:
+
+ "30:30"
+
+
+### get_interval_start, get_interval_end ###
+ * Syntax:
+
+ get_interval_start/get_interval_end(interval)
+
+ * Gets the start/end of the given interval.
+ * Arguments:
+ * `interval`: the interval to be accessed.
+ * Return Value:
+ * a `time`, `date`, or `datetime` (depending on the time instances of the interval) representing the starting
+ or ending time,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-interval value will cause a type error.
+
+ * Example:
+
+ {
+ "start": get_interval_start(interval_start_from_date("1984-01-01", "P1Y")),
+ "end": get_interval_end(interval_start_from_date("1984-01-01", "P1Y"))
+ };
+
+
+ * The expected result is:
+
+ { "start": date("1984_01_01"), "end": date("1985_01_01") }
+
+
+### get_interval_start_date/get_interval_start_datetimeget_interval_start_time, get_interval_end_date/get_interval_end_datetime/get_interval_end_time ###
+ * Syntax:
+
+ get_interval_start_date/get_interval_start_datetime/get_interval_start_time/get_interval_end_date/get_interval_end_datetime/get_interval_end_time(interval)
+
+ * Gets the start/end of the given interval for the specific date/datetime/time type.
+ * Arguments:
+ * `interval`: the interval to be accessed.
+ * Return Value:
+ * a `time`, `date`, or `datetime` (depending on the function) representing the starting or ending time,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-interval value will cause a type error.
+
+ * Example:
+
+ {
+ "start1": get_interval_start_date(interval_start_from_date("1984-01-01", "P1Y")),
+ "end1": get_interval_end_date(interval_start_from_date("1984-01-01", "P1Y")),
+ "start2": get_interval_start_datetime(interval_start_from_datetime("1984-01-01T08:30:00.000", "P1Y1H")),
+ "end2": get_interval_end_datetime(interval_start_from_datetime("1984-01-01T08:30:00.000", "P1Y1H")),
+ "start3": get_interval_start_time(interval_start_from_time("08:30:00.000", "P1H")),
+ "end3": get_interval_end_time(interval_start_from_time("08:30:00.000", "P1H"))
+ };
+
+
+ * The expected result is:
+
+ {
+ "start1": date("1984-01-01"),
+ "end1": date("1985-01-01"),
+ "start2": datetime("1984-01-01T08:30:00.000Z"),
+ "end2": datetime("1985-01-01T09:30:00.000Z"),
+ "start3": time("08:30:00.000Z"),
+ "end3": time("09:30:00.000Z")
+ }
+
+
+### get_overlapping_interval ###
+ * Syntax:
+
+ get_overlapping_interval(interval1, interval2)
+
+ * Gets the start/end of the given interval for the specific date/datetime/time type.
+ * Arguments:
+ * `interval1`: an `interval` value
+ * `interval2`: an `interval` value
+ * Return Value:
+ * an `interval` that is overlapping `interval1` and `interval2`.
+ If `interval1` and `interval2` do not overlap `null` is returned. Note each interval must be of the same type.
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-interval input value will cause a type error.
+
+ * Example:
+
+ { "overlap1": get_overlapping_interval(interval(time("11:23:39"), time("18:27:19")), interval(time("12:23:39"), time("23:18:00"))),
+ "overlap2": get_overlapping_interval(interval(time("12:23:39"), time("18:27:19")), interval(time("07:19:39"), time("09:18:00"))),
+ "overlap3": get_overlapping_interval(interval(date("1980-11-30"), date("1999-09-09")), interval(date("2013-01-01"), date("2014-01-01"))),
+ "overlap4": get_overlapping_interval(interval(date("1980-11-30"), date("2099-09-09")), interval(date("2013-01-01"), date("2014-01-01"))),
+ "overlap5": get_overlapping_interval(interval(datetime("1844-03-03T11:19:39"), datetime("2000-10-30T18:27:19")), interval(datetime("1989-03-04T12:23:39"), datetime("2009-10-10T23:18:00"))),
+ "overlap6": get_overlapping_interval(interval(datetime("1989-03-04T12:23:39"), datetime("2000-10-30T18:27:19")), interval(datetime("1844-03-03T11:19:39"), datetime("1888-10-10T23:18:00")))
+ };
+
+ * The expected result is:
+
+ { "overlap1": interval(time("12:23:39.000Z"), time("18:27:19.000Z")),
+ "overlap2": null,
+ "overlap3": null,
+ "overlap4": interval(date("2013-01-01"), date("2014_01_01")),
+ "overlap5": interval(datetime("1989-03-04T12:23:39.000Z"), datetime("2000-10-30T18:27:19.000Z")),
+ "overlap6": null
+ }
+
+
+### interval_before/interval_after/interval_meets/interval_met_by/interval_overlaps/interval_overlapped_by/interval_overlapping/interval_starts/interval_started_by/interval_covers/interval_covered_by/interval_ends/interval_ended_by ###
+
+### interval_bin ###
+ * Syntax:
+
+ interval_bin(time_to_bin, time_bin_anchor, duration_bin_size)
+
+ * Returns the `interval` value representing the bin containing the `time_to_bin` value.
+ * Arguments:
+ * `time_to_bin`: a date/time/datetime value representing the time to be binned.
+ * `time_bin_anchor`: a date/time/datetime value representing an anchor of a bin starts. The type of this argument should be the same as the first `time_to_bin` argument.
+ * `duration_bin_size`: the duration value representing the size of the bin, in the type of year_month_duration or day_time_duration. The type of this duration should be compatible with the type of `time_to_bin`, so that the arithmetic operation between `time_to_bin` and `duration_bin_size` is well_defined. Currently AsterixDB supports the following arithmetic operations:
+ * datetime +|_ year_month_duration
+ * datetime +|_ day_time_duration
+ * date +|_ year_month_duration
+ * date +|_ day_time_duration
+ * time +|_ day_time_duration
+ * Return Value:
+ * a `interval` value representing the bin containing the `time_to_bin` value. Note that the internal type of
+ this interval value should be the same as the `time_to_bin` type,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument or the second argument is any other non-date/non-time/non-datetime value,
+ * or, the second argument is any other non-year_month_duration/non-day_time_duration value.
+
+ * Example:
+
+ {
+ "bin1": interval_bin(date("2010-10-30"), date("1990-01-01"), year_month_duration("P1Y")),
+ "bin2": interval_bin(datetime("1987-11-19T23:49:23.938"), datetime("1990-01-01T00:00:00.000Z"), year_month_duration("P6M")),
+ "bin3": interval_bin(time("12:23:34.930+07:00"), time("00:00:00"), day_time_duration("PT1M")),
+ "bin4": interval_bin(datetime("1987-11-19T23:49:23.938"), datetime("2013-01-01T00:00:00.000"), day_time_duration("PT24H"))
+ };
+
+ * The expected result is:
+
+ {
+ "bin1": interval(date("2010-01-01"),date("2011-01-01")),
+ "bin2": interval(datetime("1987-07-01T00:00:00.000Z"), datetime("1988-01-01T00:00:00.000Z")),
+ "bin3": interval(time("05:23:00.000Z"), time("05:24:00.000Z")),
+ "bin4": interval(datetime("1987-11-19T00:00:00.000Z"), datetime("1987-11-20T00:00:00.000Z"))
+ }
+
+
+### interval_start_from_date/time/datetime ###
+ * Syntax:
+
+ interval_start_from_date/time/datetime(date/time/datetime, duration)
+
+ * Construct an `interval` value by the given starting `date`/`time`/`datetime` and the `duration` that the interval lasts.
+ * Arguments:
+ * `date/time/datetime`: a `string` representing a `date`, `time` or `datetime`, or a `date`/`time`/`datetime` value, representing the starting time point.
+ * `duration`: a `string` or `duration` value representing the duration of the interval. Note that duration cannot be negative value.
+ * Return Value:
+ * an `interval` value representing the interval starting from the given time point with the length of duration,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument or the second argument is any other non-date/non-time/non-datetime value,
+ * or, the second argument is any other non-duration value.
+
+ * Example:
+
+ {
+ "interval1": interval_start_from_date("1984-01-01", "P1Y"),
+ "interval2": interval_start_from_time(time("02:23:28.394"), "PT3H24M"),
+ "interval3": interval_start_from_datetime("1999-09-09T09:09:09.999", duration("P2M30D"))
+ };
+
+ * The expectecd result is:
+
+ {
+ "interval1": interval(date("1984-01-01"), date("1985-01-01")),
+ "interval2": interval(time("02:23:28.394Z"), time("05:47:28.394Z")),
+ "interval3": interval(datetime("1999-09-09T09:09:09.999Z"), datetime("1999-12-09T09:09:09.999Z"))
+ }
+
+
+### overlap_bins ###
+ * Return Value:
+ * a `interval` value representing the bin containing the `time_to_bin` value. Note that the internal type of this interval value should be the same as the `time_to_bin` type.
+
+ * Syntax:
+
+ overlap_bins(interval, time_bin_anchor, duration_bin_size)
+
+ * Returns an ordered list of `interval` values representing each bin that is overlapping the `interval`.
+ * Arguments:
+ * `interval`: an `interval` value
+ * `time_bin_anchor`: a date/time/datetime value representing an anchor of a bin starts. The type of this argument should be the same as the first `time_to_bin` argument.
+ * `duration_bin_size`: the duration value representing the size of the bin, in the type of year_month_duration or day_time_duration. The type of this duration should be compatible with the type of `time_to_bin`, so that the arithmetic operation between `time_to_bin` and `duration_bin_size` is well_defined. Currently AsterixDB supports the following arithmetic operations:
+ * datetime +|_ year_month_duration
+ * datetime +|_ day_time_duration
+ * date +|_ year_month_duration
+ * date +|_ day_time_duration
+ * time +|_ day_time_duration
+ * Return Value:
+ * a ordered list of `interval` values representing each bin that is overlapping the `interval`.
+ Note that the internal type as `time_to_bin` and `duration_bin_size`.
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first arugment is any other non-interval value,
+ * or, the second argument is any other non-date/non-time/non-datetime value,
+ * or, the second argument is any other non-year_month_duration/non-day_time_duration value.
+
+ * Example:
+
+ {
+ "timebins": overlap_bins(interval(time("17:23:37"), time("18:30:21")), time("00:00:00"), day_time_duration("PT30M")),
+ "datebins": overlap_bins(interval(date("1984-03-17"), date("2013-08-22")), date("1990-01-01"), year_month_duration("P10Y")),
+ "datetimebins": overlap_bins(interval(datetime("1800-01-01T23:59:48.938"), datetime("2015-07-26T13:28:30.218")),
+ datetime("1900-01-01T00:00:00.000"), year_month_duration("P100Y"))
+ };
+
+ * The expected result is:
+
+ {
+ "timebins": [
+ interval(time("17:00:00.000Z"), time("17:30:00.000Z")),
+ interval(time("17:30:00.000Z"), time("18:00:00.000Z")),
+ interval(time("18:00:00.000Z"), time("18:30:00.000Z")),
+ interval(time("18:30:00.000Z"), time("19:00:00.000Z"))
+ ],
+ "datebins": [
+ interval(date("1980-01-01"), date("1990-01-01")),
+ interval(date("1990-01-01"), date("2000-01-01")),
+ interval(date("2000-01-01"), date("2010-01-01")),
+ interval(date("2010-01-01"), date("2020-01-01"))
+ ],
+ "datetimebins": [
+ interval(datetime("1800-01-01T00:00:00.000Z"), datetime("1900-01-01T00:00:00.000Z")),
+ interval(datetime("1900-01-01T00:00:00.000Z"), datetime("2000-01-01T00:00:00.000Z")),
+ interval(datetime("2000-01-01T00:00:00.000Z"), datetime("2100-01-01T00:00:00.000Z"))
+ ]
+ };
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/8_record.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/8_record.md b/asterixdb/asterix-doc/src/main/markdown/builtins/8_record.md
new file mode 100644
index 0000000..a110433
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/8_record.md
@@ -0,0 +1,235 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+## <a id="RecordFunctions">Record Functions</a> ##
+
+### get_record_fields ###
+ * Syntax:
+
+ get_record_fields(input_record)
+
+ * Access the record field names, type and open status for a given record.
+ * Arguments:
+ * `input_record` : a record value.
+ * Return Value:
+ * an array of `record` values that include the field_name `string`,
+ field_type `string`, is_open `boolean` (used for debug purposes only: `true` if field is open and `false` otherwise),
+ and optional nested `orderedList` for the values of a nested record,
+ * `missing` if the argument is a `missing` value,
+ * `null` if the argument is a `null` value,
+ * any other non-record input value will cause a type error.
+
+ * Example:
+
+ get_record_fields(
+ {
+ "id": 1,
+ "project": "AsterixDB",
+ "address": {"city": "Irvine", "state": "CA"},
+ "related": ["Hivestrix", "Preglix", "Apache VXQuery"]
+ }
+ );
+
+ * The expected result is:
+
+ [
+ { "field-name": "id", "field-type": "INT64", "is-open": false },
+ { "field-name": "project", "field-type": "STRING", "is-open": false },
+ { "field-name": "address", "field-type": "RECORD", "is-open": false,
+ "nested": [
+ { "field-name": "city", "field-type": "STRING", "is-open": false },
+ { "field-name": "state", "field-type": "STRING", "is-open": false }
+ ]
+ },
+ { "field-name":
+ "related",
+ "field-type": "ORDEREDLIST",
+ "is-open": false,
+ "list": [
+ { "field-type": "STRING" },
+ { "field-type": "STRING" },
+ { "field-type": "STRING" }
+ ]
+ }
+ ]
+
+ ]
+### get_record_field_value ###
+ * Syntax:
+
+ get_record_field_value(input_record, string)
+
+ * Access the field name given in the `string_expression` from the `record_expression`.
+ * Arguments:
+ * `input_record` : a `record` value.
+ * `string` : a `string` representing the top level field name.
+ * Return Value:
+ * an `any` value saved in the designated field of the record,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-record value,
+ * or, the second argument is any other non-string value.
+
+ * Example:
+
+ get_record_field_value({
+ "id": 1,
+ "project": "AsterixDB",
+ "address": {"city": "Irvine", "state": "CA"},
+ "related": ["Hivestrix", "Preglix", "Apache VXQuery"]
+ },
+ "project"
+ );
+
+ * The expected result is:
+
+ "AsterixDB"
+
+### record_remove_fields ###
+ * Syntax:
+
+ record_remove_fields(input_record, field_names)
+
+ * Remove indicated fields from a record given a list of field names.
+ * Arguments:
+ * `input_record`: a record value.
+ * `field_names`: an array of strings and/or array of array of strings.
+
+ * Return Value:
+ * a new record value without the fields listed in the second argument,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-record value,
+ * or, the second argument is any other non-array value or recursively contains non-string items.
+
+
+ * Example:
+
+ record_remove_fields(
+ {
+ "id":1,
+ "project":"AsterixDB",
+ "address":{"city":"Irvine", "state":"CA"},
+ "related":["Hivestrix", "Preglix", "Apache VXQuery"]
+ },
+ [["address", "city"], "related"]
+ );
+
+ * The expected result is:
+
+ {
+ "id":1,
+ "project":"AsterixDB",
+ "address":{ "state": "CA" }
+ }
+
+### record_add_fields ###
+ * Syntax:
+
+ record_add_fields(input_record, fields)
+
+ * Add fields to a record given a list of field names.
+ * Arguments:
+ * `input_record` : a record value.
+ * `fields`: an array of field descriptor records where each record has field_name and field_value.
+ * Return Value:
+ * a new record value with the new fields included,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * a type error will be raised if:
+ * the first argument is any other non-record value,
+ * the second argument is any other non-array value, or contains non-record items.
+
+
+ * Example:
+
+ record_add_fields(
+ {
+ "id":1,
+ "project":"AsterixDB",
+ "address":{"city":"Irvine", "state":"CA"},
+ "related":["Hivestrix", "Preglix", "Apache VXQuery"]
+ },
+ [{"field-name":"employment_location", "field-value":create_point(30.0,70.0)}]
+ );
+
+ * The expected result is:
+
+ {
+ "id":1,
+ "project":"AsterixDB",
+ "address":{"city":"Irvine", "state":"CA"},
+ "related":["Hivestrix", "Preglix", "Apache VXQuery"]
+ "employment_location": point("30.0,70.0")
+ }
+
+### record_merge ###
+ * Syntax:
+
+ record_merge(record1, record2)
+
+ * Merge two different records into a new record.
+ * Arguments:
+ * `record1` : a record value.
+ * `record2` : a record value.
+ * Return Value:
+ * a new record value with fields from both input records. If a field\u2019s names in both records are the same,
+ an exception is issued,
+ * `missing` if any argument is a `missing` value,
+ * `null` if any argument is a `null` value but no argument is a `missing` value,
+ * any other non-record input value will cause a type error.
+
+
+ * Example:
+
+ record_merge(
+ {
+ "id":1,
+ "project":"AsterixDB",
+ "address":{"city":"Irvine", "state":"CA"},
+ "related":["Hivestrix", "Preglix", "Apache VXQuery"]
+ },
+ {
+ "user_id": 22,
+ "employer": "UC Irvine",
+ "employment_type": "visitor"
+ }
+ );
+
+ * The expected result is:
+
+ {
+ "employment_type": "visitor",
+ "address": {
+ "city": "Irvine",
+ "state": "CA"
+ },
+ "related": [
+ "Hivestrix",
+ "Preglix",
+ "Apache VXQuery"
+ ],
+ "user_id": 22,
+ "project": "AsterixDB",
+ "employer": "UC Irvine",
+ "id": 1
+ }
+
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/9_aggregate_aql.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/9_aggregate_aql.md b/asterixdb/asterix-doc/src/main/markdown/builtins/9_aggregate_aql.md
new file mode 100644
index 0000000..6498307
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/9_aggregate_aql.md
@@ -0,0 +1,297 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+## <a id="AggregateFunctions">Aggregate Functions (Array Functions) </a> ##
+
+This section contains detailed descriptions of each AQL aggregate function (i.e., array function).
+
+
+### sql-count ###
+ * Syntax:
+
+ sql-count(collection)
+
+ * Gets the number of non-null and non-missing items in the given collection.
+ * Arguments:
+ * `collection` could be:
+ * an `array` or `multiset` to be counted,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * a `bigint` value representing the number of non-null and non-missing items in the given collection,
+ * `null` is returned if the input is `null` or `missing`,
+ * any other non-array and non-multiset input value will cause an error.
+
+ * Example:
+
+ sql-count( ['hello', 'world', 1, 2, 3, null, missing] );
+
+
+ * The expected result is:
+
+ 5
+
+
+### sql-avg ###
+
+ * Syntax:
+
+ sql-avg(num_collection)
+
+ * Gets the average value of the non-null and non-missing numeric items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset` containing numeric values, `null`s or `missing`s,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * a `double` value representing the average of the non-null and non-missing numbers in the given collection,
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if the given collection does not contain any non-null and non-missing items,
+ * any other non-array and non-multiset input value will cause a type error,
+ * any other non-numeric value in the input collection will cause a type error.
+
+ * Example:
+
+ sql-avg( [1.2, 2.3, 3.4, 0, null] );
+
+ * The expected result is:
+
+ 1.725
+
+
+### sql-sum ###
+ * Syntax:
+
+ sql-sum(num_collection)
+
+ * Gets the sum of non-null and non-missing items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset` containing numeric values, `null`s or `missing`s,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * the sum of the non-null and non-missing numbers in the given collection.
+ The returning type is decided by the item type with the highest
+ order in the numeric type promotion order (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`) among
+ items.
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if the given collection does not contain any non-null and non-missing items,
+ * any other non-array and non-multiset input value will cause a type error,
+ * any other non-numeric value in the input collection will cause a type error.
+
+ * Example:
+
+ sql-sum( [1.2, 2.3, 3.4, 0, null, missing] );
+
+ * The expected result is:
+
+ 6.9
+
+
+### sql-sql_min ###
+ * Syntax:
+
+ sql-min(num_collection)
+
+ * Gets the min value of non-null and non-missing comparable items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset`,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * the min value of non-null and non-missing values in the given collection.
+ The returning type is decided by the item type with the highest order in the
+ type promotion order (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`) among numeric items.
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if the given collection does not contain any non-null and non-missing items,
+ * multiple incomparable items in the input array or multiset will cause a type error,
+ * any other non-array and non-multiset input value will cause a type error.
+
+ * Example:
+
+ sql-min( [1.2, 2.3, 3.4, 0, null, missing] );
+
+ * The expected result is:
+
+ 0.0
+
+
+### sql-max ###
+ * Syntax:
+
+ sql-max(num_collection)
+
+ * Gets the max value of the non-null and non-missing comparable items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset`,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * the max value of non-null and non-missing numbers in the given collection.
+ The returning type is decided by the item type with the highest order in the
+ type promotion order (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`) among numeric items.
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if the given collection does not contain any non-null and non-missing items,
+ * multiple incomparable items in the input array or multiset will cause a type error,
+ * any other non-array and non-multiset input value will cause a type error.
+
+ * Example:
+
+ sql-max( [1.2, 2.3, 3.4, 0, null, missing] );
+
+ * The expected result is:
+
+ 3.4
+
+
+### count ###
+ * Syntax:
+
+ count(collection)
+
+ * Gets the number of items in the given collection.
+ * Arguments:
+ * `collection` could be:
+ * an `array` or `multiset` containing the items to be counted,
+ * or a `null` value,
+ * or a `missing` value.
+ * Return Value:
+ * a `bigint` value representing the number of items in the given collection,
+ * `null` is returned if the input is `null` or `missing`.
+
+ * Example:
+
+ count( [1, 2, null, missing] );
+
+ * The expected result is:
+
+ 4
+
+### avg ###
+ * Syntax:
+
+ avg(num_collection)
+
+ * Gets the average value of the numeric items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset` containing numeric values, `null`s or `missing`s,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * a `double` value representing the average of the numbers in the given collection,
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if there is a `null` or `missing` in the input collection,
+ * any other non-numeric value in the input collection will cause a type error.
+
+ * Example:
+
+ avg( [100, 200, 300] );
+
+ * The expected result is:
+
+ [ 200.0 ]
+
+### sum ###
+ * Syntax:
+
+ sum(num_collection)
+
+ * Gets the sum of the items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset` containing numeric values, `null`s or `missing`s,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * the sum of the numbers in the given collection. The returning type is decided by the item type with the highest
+ order in the numeric type promotion order (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`) among
+ items.
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if there is a `null` or `missing` in the input collection,
+ * any other non-numeric value in the input collection will cause a type error.
+
+ * Example:
+
+ sum( [100, 200, 300] );
+
+ * The expected result is:
+
+ 600
+
+### sql-min ###
+ * Syntax:
+
+ min(num_collection)
+
+ * Gets the min value of comparable items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset`,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * the min value of the given collection.
+ The returning type is decided by the item type with the highest order in the type promotion order
+ (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`) among numeric items.
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if there is a `null` or `missing` in the input collection,
+ * multiple incomparable items in the input array or multiset will cause a type error,
+ * any other non-array and non-multiset input value will cause a type error.
+
+ * Example:
+
+ min( [10.2, 100, 5] );
+
+ * The expected result is:
+
+ 5.0
+
+
+### sql-max ###
+ * Syntax:
+
+ max(num_collection)
+
+ * Gets the max value of numeric items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset`,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * The max value of the given collection.
+ The returning type is decided by the item type with the highest order in the type promotion order
+ (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`) among numeric items.
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if there is a `null` or `missing` in the input collection,
+ * multiple incomparable items in the input array or multiset will cause a type error,
+ * any other non-array and non-multiset input value will cause a type error.
+
+ * Example:
+
+ max( [10.2, 100, 5] );
+
+ * The expected result is:
+
+ 100.0
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/builtins/9_aggregate_sql.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/builtins/9_aggregate_sql.md b/asterixdb/asterix-doc/src/main/markdown/builtins/9_aggregate_sql.md
new file mode 100644
index 0000000..62a35c3
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/builtins/9_aggregate_sql.md
@@ -0,0 +1,303 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
+## <a id="AggregateFunctions">Aggregate Functions (Array Functions) </a> ##
+
+A high-level description of SQL++ aggregate functions can be found at <a href="manual.html#Aggregation_functions">here</a>.
+As SQL++ supports all legitimate SQL GROUP BY and Aggregation queries,
+<a href="manual.html#SQL-92_aggregation_functions">here</a> is a description of how standard SQL aggregation functions
+are supported.
+
+This section contains detailed descriptions of each SQL++ aggregate function (i.e., array function).
+
+
+### array_count ###
+ * Syntax:
+
+ array_count(collection)
+
+ * Gets the number of non-null and non-missing items in the given collection.
+ * Arguments:
+ * `collection` could be:
+ * an `array` or `multiset` to be counted,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * a `bigint` value representing the number of non-null and non-missing items in the given collection,
+ * `null` is returned if the input is `null` or `missing`,
+ * any other non-array and non-multiset input value will cause an error.
+
+ * Example:
+
+ array_count( ['hello', 'world', 1, 2, 3, null, missing] );
+
+
+ * The expected result is:
+
+ 5
+
+
+### array_avg ###
+
+ * Syntax:
+
+ array_avg(num_collection)
+
+ * Gets the average value of the non-null and non-missing numeric items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset` containing numeric values, `null`s or `missing`s,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * a `double` value representing the average of the non-null and non-missing numbers in the given collection,
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if the given collection does not contain any non-null and non-missing items,
+ * any other non-array and non-multiset input value will cause a type error,
+ * any other non-numeric value in the input collection will cause a type error.
+
+ * Example:
+
+ array_avg( [1.2, 2.3, 3.4, 0, null] );
+
+ * The expected result is:
+
+ 1.725
+
+
+### array_sum ###
+ * Syntax:
+
+ array_sum(num_collection)
+
+ * Gets the sum of non-null and non-missing items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset` containing numeric values, `null`s or `missing`s,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * the sum of the non-null and non-missing numbers in the given collection.
+ The returning type is decided by the item type with the highest
+ order in the numeric type promotion order (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`) among
+ items.
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if the given collection does not contain any non-null and non-missing items,
+ * any other non-array and non-multiset input value will cause a type error,
+ * any other non-numeric value in the input collection will cause a type error.
+
+ * Example:
+
+ array_sum( [1.2, 2.3, 3.4, 0, null, missing] );
+
+ * The expected result is:
+
+ 6.9
+
+
+### array_sql_min ###
+ * Syntax:
+
+ array_min(num_collection)
+
+ * Gets the min value of non-null and non-missing comparable items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset`,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * the min value of non-null and non-missing values in the given collection.
+ The returning type is decided by the item type with the highest order in the
+ type promotion order (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`) among numeric items.
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if the given collection does not contain any non-null and non-missing items,
+ * multiple incomparable items in the input array or multiset will cause a type error,
+ * any other non-array and non-multiset input value will cause a type error.
+
+ * Example:
+
+ array_min( [1.2, 2.3, 3.4, 0, null, missing] );
+
+ * The expected result is:
+
+ 0.0
+
+
+### array_max ###
+ * Syntax:
+
+ array_max(num_collection)
+
+ * Gets the max value of the non-null and non-missing comparable items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset`,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * the max value of non-null and non-missing numbers in the given collection.
+ The returning type is decided by the item type with the highest order in the
+ type promotion order (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`) among numeric items.
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if the given collection does not contain any non-null and non-missing items,
+ * multiple incomparable items in the input array or multiset will cause a type error,
+ * any other non-array and non-multiset input value will cause a type error.
+
+ * Example:
+
+ array_max( [1.2, 2.3, 3.4, 0, null, missing] );
+
+ * The expected result is:
+
+ 3.4
+
+
+### coll_count ###
+ * Syntax:
+
+ coll_count(collection)
+
+ * Gets the number of items in the given collection.
+ * Arguments:
+ * `collection` could be:
+ * an `array` or `multiset` containing the items to be counted,
+ * or a `null` value,
+ * or a `missing` value.
+ * Return Value:
+ * a `bigint` value representing the number of items in the given collection,
+ * `null` is returned if the input is `null` or `missing`.
+
+ * Example:
+
+ coll_count( [1, 2, null, missing] );
+
+ * The expected result is:
+
+ 4
+
+### coll_avg ###
+ * Syntax:
+
+ coll_avg(num_collection)
+
+ * Gets the average value of the numeric items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset` containing numeric values, `null`s or `missing`s,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * a `double` value representing the average of the numbers in the given collection,
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if there is a `null` or `missing` in the input collection,
+ * any other non-numeric value in the input collection will cause a type error.
+
+ * Example:
+
+ coll_avg( [100, 200, 300] );
+
+ * The expected result is:
+
+ [ 200.0 ]
+
+### coll_sum ###
+ * Syntax:
+
+ coll_sum(num_collection)
+
+ * Gets the sum of the items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset` containing numeric values, `null`s or `missing`s,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * the sum of the numbers in the given collection. The returning type is decided by the item type with the highest
+ order in the numeric type promotion order (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`) among
+ items.
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if there is a `null` or `missing` in the input collection,
+ * any other non-numeric value in the input collection will cause a type error.
+
+ * Example:
+
+ coll_sum( [100, 200, 300] );
+
+ * The expected result is:
+
+ 600
+
+### array_min ###
+ * Syntax:
+
+ coll_min(num_collection)
+
+ * Gets the min value of comparable items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset`,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * the min value of the given collection.
+ The returning type is decided by the item type with the highest order in the type promotion order
+ (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`) among numeric items.
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if there is a `null` or `missing` in the input collection,
+ * multiple incomparable items in the input array or multiset will cause a type error,
+ * any other non-array and non-multiset input value will cause a type error.
+
+ * Example:
+
+ coll_min( [10.2, 100, 5] );
+
+ * The expected result is:
+
+ 5.0
+
+
+### array_max ###
+ * Syntax:
+
+ coll_max(num_collection)
+
+ * Gets the max value of numeric items in the given collection.
+ * Arguments:
+ * `num_collection` could be:
+ * an `array` or `multiset`,
+ * or, a `null` value,
+ * or, a `missing` value.
+ * Return Value:
+ * The max value of the given collection.
+ The returning type is decided by the item type with the highest order in the type promotion order
+ (`tinyint`-> `smallint`->`integer`->`bigint`->`float`->`double`) among numeric items.
+ * `null` is returned if the input is `null` or `missing`,
+ * `null` is returned if there is a `null` or `missing` in the input collection,
+ * multiple incomparable items in the input array or multiset will cause a type error,
+ * any other non-array and non-multiset input value will cause a type error.
+
+ * Example:
+
+ coll_max( [10.2, 100, 5] );
+
+ * The expected result is:
+
+ 100.0
+
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md
index cb75d76..bbe0566 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md
@@ -1,3 +1,22 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
# The SQL++ Query Language
## <a id="toc">Table of Contents</a> ##
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/sqlpp/1_intro.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/1_intro.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/1_intro.md
index ed8d1c9..808d713 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/1_intro.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/1_intro.md
@@ -1,3 +1,22 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
# <a id="Introduction">1. Introduction</a><font size="3"/>
This document is intended as a reference guide to the full syntax and semantics of the SQL++ Query Language, a SQL-inspired language for working with semistructured data. SQL++ has much in common with SQL, but there are also differences due to the data model that the language is designed to serve. (SQL was designed in the 1970's for interacting with the flat, schema-ified world of relational databases, while SQL++ is designed for the nested, schema-less/schema-optional world of modern NoSQL systems.) In particular, SQL++ in the context of Apache AsterixDB is intended for working with the Asterix Data Model (ADM), which is a data model aimed at a superset of JSON with an enriched and flexible type system.
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/sqlpp/2_expr.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/2_expr.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/2_expr.md
index 79f9da0..c2bab77 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/2_expr.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/2_expr.md
@@ -1,3 +1,22 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
# <a id="Expressions">2. Expressions</a>
Expression ::= OperatorExpression | CaseExpression | QuantifiedExpression
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/sqlpp/3_query.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/3_query.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/3_query.md
index 66fd8f1..c6dcf61 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/3_query.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/3_query.md
@@ -1,3 +1,22 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
# <a id="Queries">3. Queries</a>
A SQL++ query can be any legal SQL++ expression or `SELECT` statement. A SQL++ query always ends with a semicolon.
@@ -577,11 +596,11 @@ The following table catalogs the SQL++ built-in aggregation functions and also i
| COLL_MAX | returns NULL | returns NULL | returns NULL |
| COLL_MIN | returns NULL | returns NULL | returns NULL |
| COLL_AVG | returns NULL | returns NULL | returns NULL |
-| COLL_SQL-COUNT | not counted | not counted | 0 |
-| COLL_SQL-SUM | ignores NULL | ignores NULL | returns NULL |
-| COLL_SQL-MAX | ignores NULL | ignores NULL | returns NULL |
-| COLL_SQL-MIN | ignores NULL | ignores NULL | returns NULL |
-| COLL_SQL-AVG | ignores NULL | ignores NULL | returns NULL |
+| ARRAY_COUNT | not counted | not counted | 0 |
+| ARRAY_SUM | ignores NULL | ignores NULL | returns NULL |
+| ARRAY_MAX | ignores NULL | ignores NULL | returns NULL |
+| ARRAY_MIN | ignores NULL | ignores NULL | returns NULL |
+| ARRAY_AVG | ignores NULL | ignores NULL | returns NULL |
Notice that SQL++ has twice as many functions listed above as there are aggregate functions in SQL-92.
This is because SQL++ offers two versions of each -- one that handles `UNKNOWN` values in a semantically
@@ -590,7 +609,7 @@ handles them in the ad hoc "just ignore the unknown values" fashion that the SQL
##### Example
- COLL_AVG(
+ ARRAY_AVG(
(
SELECT VALUE len(friendIds) FROM GleambookUsers
)
@@ -602,7 +621,7 @@ This example returns:
##### Example
- SELECT uid AS uid, COLL_COUNT(grp) AS msgCnt
+ SELECT uid AS uid, ARRAY_COUNT(grp) AS msgCnt
FROM GleambookMessages message
GROUP BY message.authorId AS uid GROUP AS grp(message AS msg);
@@ -615,7 +634,7 @@ This query returns:
Notice how the query forms groups where each group involves a message author and their messages.
(SQL cannot do this because the grouped intermediate result is non-1NF in nature.)
-The query then uses the collection aggregate function `COLL_COUNT` to get the cardinality of each
+The query then uses the collection aggregate function ARRAY_COUNT to get the cardinality of each
group of messages.
### <a id="SQL-92_aggregation_functions">SQL-92 aggregation functions</a>
@@ -635,11 +654,10 @@ It is important to realize that `COUNT` is actually **not** a SQL++ built-in agg
Rather, the `COUNT` query above is using a special "sugared" function symbol that the SQL++ compiler
will rewrite as follows:
- SELECT uid AS uid, `COLL_SQL-COUNT`( (SELECT g.msg FROM `$1` as g) ) AS msgCnt
+ SELECT uid AS uid, ARRAY_COUNT( (SELECT g.msg FROM `$1` as g) ) AS msgCnt
FROM GleambookMessages msg
GROUP BY msg.authorId AS uid GROUP AS `$1`(msg AS msg);
-> TW: We really need to do something about `COLL_SQL-COUNT`.
The same sort of rewritings apply to the function symbols `SUM`, `MAX`, `MIN`, and `AVG`.
In contrast to the SQL++ collection aggregate functions, these special SQL-92 function symbols
@@ -668,7 +686,7 @@ However, since the SELECT expression `msg.authorId` is syntactically identical t
it will be internally replaced by the generated group key variable.
The following is the equivalent rewritten query that will be generated by the compiler for the query above:
- SELECT authorId AS authorId, COLL_COUNT( (SELECT g.msg FROM `$1` AS g) )
+ SELECT authorId AS authorId, ARRAY_COUNT( (SELECT g.msg FROM `$1` AS g) )
FROM GleambookMessages msg
GROUP BY msg.authorId AS authorId GROUP AS `$1`(msg AS msg);
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_ddl.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_ddl.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_ddl.md
index e83e47d..a2eebbd 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_ddl.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_ddl.md
@@ -1,3 +1,22 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ !-->
+
# <a id="DDL_and_DML_statements">4. DDL and DML statements</a>
Statement ::= ( SingleStatement ( ";" )? )* <EOF>
[3/5] asterixdb git commit: Revise builtin function documents.
Posted by bu...@apache.org.
http://git-wip-us.apache.org/repos/asf/asterixdb/blob/f7f3a7f2/asterixdb/asterix-doc/src/site/markdown/aql/allens.md
----------------------------------------------------------------------
diff --git a/asterixdb/asterix-doc/src/site/markdown/aql/allens.md b/asterixdb/asterix-doc/src/site/markdown/aql/allens.md
deleted file mode 100644
index ddf81a6..0000000
--- a/asterixdb/asterix-doc/src/site/markdown/aql/allens.md
+++ /dev/null
@@ -1,274 +0,0 @@
-<!--
- ! Licensed to the Apache Software Foundation (ASF) under one
- ! or more contributor license agreements. See the NOTICE file
- ! distributed with this work for additional information
- ! regarding copyright ownership. The ASF licenses this file
- ! to you under the Apache License, Version 2.0 (the
- ! "License"); you may not use this file except in compliance
- ! with the License. You may obtain a copy of the License at
- !
- ! http://www.apache.org/licenses/LICENSE-2.0
- !
- ! Unless required by applicable law or agreed to in writing,
- ! software distributed under the License is distributed on an
- ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ! KIND, either express or implied. See the License for the
- ! specific language governing permissions and limitations
- ! under the License.
- !-->
-
-# AsterixDB Temporal Functions: Allen's Relations #
-
-## <a id="toc">Table of Contents</a> ##
-
-* [About Allen's Relations](#AboutAllensRelations)
-* [Allen's Relations Functions](#AllensRelatonsFunctions)
-
-
-## <a id="AboutAllensRelations">About Allen's Relations</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
-
-AsterixDB supports Allen's relations over interval types. Allen's relations are also called Allen's interval algebra. There are totally 13 base relations described by this algebra, and all of them are supported in AsterixDB (note that `interval-equals` is supported by the `=` comparison symbol so there is no extra function for it).
-
-A detailed description of Allen's relations can be found from its [wikipedia entry](http://en.wikipedia.org/wiki/Allen's_interval_algebra).
-
-## <a id="AllensRelatonsFunctions">Allen's Relations Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ##
-
-### interval-before, interval-after ###
-
- * Syntax:
-
- interval-before(interval1, interval2)
- interval-after(interval1, interval2)
-
- * These two functions check whether an interval happens before/after another interval.
- * Arguments:
- * `interval1`, `interval2`: two intervals to be compared
- * Return Value:
-
- A `boolean` value. Specifically, `interval-before(interval1, interval2)` is true if and only if `interval1.end < interval2.start`, and `interval-after(interval1, interval2)` is true if and only if `interval1.start > interval2.end`. If any of the two inputs is `null`, `null` is returned.
-
- * Examples:
-
- let $itv1 := interval(date("2000-01-01"), date("2005-01-01"))
- let $itv2 := interval(date("2005-05-01"), date("2012-09-09"))
- return {"interval-before": interval-before($itv1, $itv2), "interval-after": interval-after($itv2, $itv1)}
-
- * The expected result is:
-
- { "interval-before": true, "interval-after": true }
-
-
-### interval-covers, interval-covered-by ###
-
- * Syntax:
-
- interval-covers(interval1, interval2)
- interval-covered-by(interval1, interval2)
-
- * These two functions check whether one interval covers the other interval.
- * Arguments:
- * `interval1`, `interval2`: two intervals to be compared
- * Return Value:
-
- A `boolean` value. Specifically, `interval-covers(interval1, interval2)` is true if and only if
-
- interval1.start <= interval2.start
- AND interval1.end >= interval2.end
-
- `interval-covered-by(interval1, interval2)` is true if and only if
-
- interval2.start <= interval1.start
- AND interval2.end >= interval1.end
-
- For both functions, if any of the two inputs is `null`, `null` is returned.
-
- * Examples:
-
- let $itv1 := interval(date("2000-01-01"), date("2005-01-01"))
- let $itv2 := interval(date("2000-03-01"), date("2004-09-09"))
- let $itv3 := interval(date("2006-08-01"), date("2007-03-01"))
- let $itv4 := interval(date("2004-09-10"), date("2012-08-01"))
- return {"interval-covers": interval-covers($itv1, $itv2), "interval-covered-by": interval-covered-by($itv3, $itv4)}
-
- * The expected result is:
-
- { "interval-covers": true, "interval-covered-by": true }
-
-
-### interval-overlaps, interval-overlapped-by ###
-
- * Syntax:
-
- interval-overlaps(interval1, interval2)
- interval-overlapped-by(interval1, interval2)
-
- * These functions check whether two intervals overlap with each other.
- * Arguments:
- * `interval1`, `interval2`: two intervals to be compared
- * Return Value:
-
- A `boolean` value. Specifically, `interval-overlaps(interval1, interval2)` is true if and only if
-
- interval1.start < interval2.start
- AND interval2.end > interval1.end
- AND interval1.end > interval2.start
-
- `interval-overlapped-by(interval1, interval2)` is true if and only if
-
- interval2.start < interval1.start
- AND interval1.end > interval2.end
- AND interval2.end > interval1.start
-
- For all these functions, if any of the two inputs is `null`, `null` is returned.
-
- Note that `interval-overlaps` and `interval-overlapped-by` are following the Allen's relations on the definition of overlap.
-
- * Examples:
-
- let $itv1 := interval(date("2000-01-01"), date("2005-01-01"))
- let $itv2 := interval(date("2004-05-01"), date("2012-09-09"))
- let $itv3 := interval(date("2006-08-01"), date("2007-03-01"))
- let $itv4 := interval(date("2004-09-10"), date("2006-12-31"))
- return {"overlaps": interval-overlaps($itv1, $itv2),
- "overlapped-by": interval-overlapped-by($itv3, $itv4)}
-
- * The expected result is:
-
- { "overlaps": true, "overlapped-by": true }
-
-
-### interval-overlapping ###
-Note that `interval-overlapping` is not an Allen's Relation, but syntactic sugar we added for the case that the intersect of two intervals is not empty. Basically this function returns true if any of these functions return true: `interval-overlaps`, `interval-overlapped-by`, `interval-covers`, or `interval-covered-by`.
-
- * Syntax:
-
- interval-overlapping(interval1, interval2)
-
- * This functions check whether two intervals share any points with each other.
- * Arguments:
- * `interval1`, `interval2`: two intervals to be compared
- * Return Value:
-
- A `boolean` value. Specifically, `interval-overlapping(interval1, interval2)` is true if
-
- (interval2.start >= interval1.start
- AND interval2.start < interval1.end)
- OR
- (interval2.end > interval1.start
- AND interval2.end <= interval1.end)
-
- If any of the two inputs is `null`, `null` is returned.
-
- * Examples:
-
- let $itv1 := interval(date("2000-01-01"), date("2005-01-01"))
- let $itv2 := interval(date("2004-05-01"), date("2012-09-09"))
- let $itv3 := interval(date("2006-08-01"), date("2007-03-01"))
- let $itv4 := interval(date("2004-09-10"), date("2006-12-31"))
- return {"overlapping1": interval-overlapping($itv1, $itv2),
- "overlapping2": interval-overlapping($itv3, $itv4)}
-
- * The expected result is:
-
- { "overlapping1": true, "overlapping2": true }
-
-
-### interval-meets, interval-met-by ###
-
- * Syntax:
-
- interval-meets(interval1, interval2)
- interval-met-by(interval1, interval2)
-
- * These two functions check whether an interval meets with another interval.
- * Arguments:
- * `interval1`, `interval2`: two intervals to be compared
- * Return Value:
-
- A `boolean` value. Specifically, `interval-meets(interval1, interval2)` is true if and only if `interval1.end = interval2.start`, and `interval-met-by(interval1, interval2)` is true if and only if `interval1.start = interval2.end`. If any of the two inputs is `null`, `null` is returned.
-
- * Examples:
-
- let $itv1 := interval(date("2000-01-01"), date("2005-01-01"))
- let $itv2 := interval(date("2005-01-01"), date("2012-09-09"))
- let $itv3 := interval(date("2006-08-01"), date("2007-03-01"))
- let $itv4 := interval(date("2004-09-10"), date("2006-08-01"))
- return {"meets": interval-meets($itv1, $itv2), "metby": interval-met-by($itv3, $itv4)}
-
- * The expected result is:
-
- { "meets": true, "metby": true }
-
-
-### interval-starts, interval-started-by ###
-
- * Syntax:
-
- interval-starts(interval1, interval2)
- interval-started-by(interval1, interval2)
-
- * These two functions check whether one interval starts with the other interval.
- * Arguments:
- * `interval1`, `interval2`: two intervals to be compared
- * Return Value:
-
- A `boolean` value. Specifically, `interval-starts(interval1, interval2)` returns true if and only if
-
- interval1.start = interval2.start
- AND interval1.end <= interval2.end
-
- `interval-started-by(interval1, interval2)` returns true if and only if
-
- interval1.start = interval2.start
- AND interval2.end <= interval1.end
-
- For both functions, if any of the two inputs is `null`, `null` is returned.
-
- * Examples:
-
- let $itv1 := interval(date("2000-01-01"), date("2005-01-01"))
- let $itv2 := interval(date("2000-01-01"), date("2012-09-09"))
- let $itv3 := interval(date("2006-08-01"), date("2007-03-01"))
- let $itv4 := interval(date("2006-08-01"), date("2006-08-02"))
- return {"interval-starts": interval-starts($itv1, $itv2), "interval-started-by": interval-started-by($itv3, $itv4)}
-
- * The expected result is:
-
- { "interval-starts": true, "interval-started-by": true }
-
-
-### interval-ends, interval-ended-by ###
-
-* Syntax:
-
- interval-ends(interval1, interval2)
- interval-ended-by(interval1, interval2)
-
- * These two functions check whether one interval ends with the other interval.
- * Arguments:
- * `interval1`, `interval2`: two intervals to be compared
- * Return Value:
-
- A `boolean` value. Specifically, `interval-ends(interval1, interval2)` returns true if and only if
-
- interval1.end = interval2.end
- AND interval1.start >= interval2.start
-
- `interval-ended-by(interval1, interval2)` returns true if and only if
-
- interval2.end = interval1.end
- AND interval2.start >= interval1.start
-
- For both functions, if any of the two inputs is `null`, `null` is returned.
-
-* Examples:
-
- let $itv1 := interval(date("2000-01-01"), date("2005-01-01"))
- let $itv2 := interval(date("1998-01-01"), date("2005-01-01"))
- let $itv3 := interval(date("2006-08-01"), date("2007-03-01"))
- let $itv4 := interval(date("2006-09-10"), date("2007-03-01"))
- return {"interval-ends": interval-ends($itv1, $itv2), "interval-ended-by": interval-ended-by($itv3, $itv4) }
-
-* The expected result is:
-
- { "interval-ends": true, "interval-ended-by": true }