Jianfeng Jia has submitted this change and it was merged. Change subject: Add the documentation for the `binary` data type ......................................................................
Add the documentation for the `binary` data type Change-Id: Iea9b29a1a8ff37617fb94cd562a1f885f8867ad3 Reviewed-on: https://asterix-gerrit.ics.uci.edu/934 Reviewed-by: Till Westmann <[email protected]> Reviewed-by: Jenkins <[email protected]> Reviewed-by: Jianfeng Jia <[email protected]> Tested-by: Jenkins <[email protected]> --- M asterixdb/asterix-doc/src/site/markdown/aql/datamodel.md M asterixdb/asterix-doc/src/site/markdown/aql/functions.md 2 files changed, 128 insertions(+), 3 deletions(-) Approvals: Jianfeng Jia: Looks good to me, approved Till Westmann: Looks good to me, approved Jenkins: Looks good to me, but someone else must approve; Verified 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: @@ -132,6 +133,26 @@ * 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. +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 +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) @@ -589,6 +590,110 @@ " 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, 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 ### @@ -2567,4 +2672,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: merged Gerrit-Change-Id: Iea9b29a1a8ff37617fb94cd562a1f885f8867ad3 Gerrit-PatchSet: 4 Gerrit-Project: asterixdb Gerrit-Branch: master Gerrit-Owner: Jianfeng Jia <[email protected]> Gerrit-Reviewer: Jenkins <[email protected]> Gerrit-Reviewer: Jianfeng Jia <[email protected]> Gerrit-Reviewer: Michael Carey <[email protected]> Gerrit-Reviewer: Till Westmann <[email protected]>
