Jianfeng Jia has uploaded a new change for review.
https://asterix-gerrit.ics.uci.edu/934
Change subject: Add the documentation for the `binary` data type
......................................................................
Add the documentation for the `binary` data type
Change-Id: Iea9b29a1a8ff37617fb94cd562a1f885f8867ad3
---
M asterixdb/asterix-doc/src/site/markdown/aql/datamodel.md
M asterixdb/asterix-doc/src/site/markdown/aql/functions.md
2 files changed, 131 insertions(+), 2 deletions(-)
git pull ssh://asterix-gerrit.ics.uci.edu:29418/asterixdb
refs/changes/34/934/1
diff --git a/asterixdb/asterix-doc/src/site/markdown/aql/datamodel.md
b/asterixdb/asterix-doc/src/site/markdown/aql/datamodel.md
index 59ef5c9..c2eeb22 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)
@@ -121,6 +122,11 @@
### <a id="PrimitiveTypesString">String</a> <font size="4"><a
href="#toc">[Back to TOC]</a></font> ###
`string` represents a sequence of characters.
+Internally, the length of the string is also stored with the actual string
contents.
+We support efficient variable-length representations to save the space on the
length numbers.
+E.g., if the length is less than 127, it only needs one byte to store the
number;
+if the length is between 128 to `127 * 127` , it needs two bytes.
+The total length of the sequence can be up to 2,147,483,648.
* Example:
@@ -132,6 +138,27 @@
* The expected result is:
{ "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.
+It is also using the variable-length representation to store the length number
of the actual bytes.
+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> ###
@@ -344,4 +371,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..a4ade92 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)
@@ -589,6 +590,108 @@
" its touch-screen is horrible"
" 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, encoded_type)
+
+ * Creates a `binary` from an string encoded in `encoded_type` format.
+ * Arguments:
+ * `string` : An encoded `string`
+ * `encoded_type` : 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_type)
+
+ * Prints a `binary` to the required encoding `string` format.
+ * Arguments:
+ * `binary` : A `binary` data need to be printed.
+ * `encoding_type` : 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 ###
@@ -2567,4 +2670,4 @@
* The expected result is:
- false
\ No newline at end of file
+ false
--
To view, visit https://asterix-gerrit.ics.uci.edu/934
To unsubscribe, visit https://asterix-gerrit.ics.uci.edu/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Iea9b29a1a8ff37617fb94cd562a1f885f8867ad3
Gerrit-PatchSet: 1
Gerrit-Project: asterixdb
Gerrit-Branch: master
Gerrit-Owner: Jianfeng Jia <[email protected]>
