Add the documentation for the `binary` data type
Change-Id: Iea9b29a1a8ff37617fb94cd562a1f885f8867ad3
Reviewed-on: https://asterix-gerrit.ics.uci.edu/934
Reviewed-by: Till Westmann <tillw@apache.org>
Reviewed-by: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
Reviewed-by: Jianfeng Jia <jianfeng.jia@gmail.com>
Tested-by: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
diff --git a/asterixdb/asterix-doc/src/site/markdown/aql/datamodel.md b/asterixdb/asterix-doc/src/site/markdown/aql/datamodel.md
index 59ef5c9..09d9177 100644
--- a/asterixdb/asterix-doc/src/site/markdown/aql/datamodel.md
+++ b/asterixdb/asterix-doc/src/site/markdown/aql/datamodel.md
@@ -27,6 +27,7 @@
* [Float](#PrimitiveTypesFloat)
* [Double](#PrimitiveTypesDouble)
* [String](#PrimitiveTypesString)
+ * [Binary](#PrimitiveTypesBinary)
* [Point](#PrimitiveTypesPoint)
* [Line](#PrimitiveTypesLine)
* [Rectangle](#PrimitiveTypesRectangle)
@@ -120,7 +121,7 @@
### <a id="PrimitiveTypesString">String</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ###
-`string` represents a sequence of characters.
+`string` represents a sequence of characters. The total length of the sequence can be up to 2,147,483,648.
* Example:
@@ -134,6 +135,26 @@
{ "v1": "This is a string.", "v2": "\"This is a quoted string\"" }
+### <a id="PrimitiveTypesBinary">Binary</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ###
+`binary` represents a sequence of bytes. It can be constructed from a `hex` or a `base64` string sequence.
+The total length of the byte sequence can be up to 2,147,483,648.
+
+ * Example:
+
+ let $hex1 := hex("ABCDEF0123456789")
+ let $hex2 := hex("abcdef0123456789")
+ let $base64_1 := base64("0123456789qwertyui+/")
+ let $base64_2 := base64('QXN0ZXJpeA==')
+ return { "hex1" : $hex1, "hex2": $hex2, "base64_1" : $base64_1, "base64_2" : $base64_2}
+
+ * The default output format is in `hex` format. Thus, the expected result is:
+
+ { "hex1": hex("ABCDEF0123456789"),
+ "hex2": hex("ABCDEF0123456789"),
+ "base64_1": hex("D35DB7E39EBBF3DAB07ABB72BA2FBF"),
+ "base64_2": hex("41737465726978") }
+
+
### <a id="PrimitiveTypesPoint">Point</a> <font size="4"><a href="#toc">[Back to TOC]</a></font> ###
`point` is the fundamental two-dimensional building block for spatial types. It consists of two `double` coordinates x and y.
@@ -344,4 +365,3 @@
{{"hello", 9328, "world", [1, 2, null]}}
-
diff --git a/asterixdb/asterix-doc/src/site/markdown/aql/functions.md b/asterixdb/asterix-doc/src/site/markdown/aql/functions.md
index 3b78a93..89dc311 100644
--- a/asterixdb/asterix-doc/src/site/markdown/aql/functions.md
+++ b/asterixdb/asterix-doc/src/site/markdown/aql/functions.md
@@ -23,6 +23,7 @@
* [Numeric Functions](#NumericFunctions)
* [String Functions](#StringFunctions)
+* [Binary Functions](#BinaryFunctions)
* [Aggregate Functions](#AggregateFunctions)
* [Spatial Functions](#SpatialFunctions)
* [Similarity Functions](#SimilarityFunctions)
@@ -590,6 +591,110 @@
" the voice-command is bad:("
" the voicemail-service is awesome"
+## <a id="BinaryFunctions">String 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:
@@ -2567,4 +2672,4 @@
* The expected result is:
- false
\ No newline at end of file
+ false