Encoding | SurrealDB Docs

These functions can be used to encode and decode data in base64. It is particularly used when that data needs to be stored and transferred over media that are designed to deal with text. This encoding and decoding helps to ensure that the data remains intact without modification during transport.

These functions can be used to encode and decode data into other formats, such as base64 and CBOR (Concise Binary Object Representation). It is particularly used when that data needs to be stored and transferred over media that are designed to deal with text. This encoding and decoding helps to ensure that the data remains intact without modification during transport.

Function	Description
`encoding::base64::decode()`	Decodes a base64-encoded string into bytes.
`encoding::base64::encode()`	Encodes bytes into a base64 string, with optional padding.
`encoding::cbor::decode()`	Decodes CBOR-formatted bytes into a SurrealQL value.
`encoding::cbor::encode()`	Encodes a SurrealQL value into CBOR-formatted bytes.
`encoding::json::decode()`	Decodes a JSON string into a SurrealQL value.
`encoding::json::encode()`	Encodes a SurrealQL value into a JSON string.

`encoding::base64::decode()`

The encoding::base64::decode() function decodes a string into bytes.

API DEFINITION

encoding::base64::decode(string) -> bytes

The following example shows this function, and its output, when used in a RETURN statement:

RETURN encoding::base64::decode("MjMyMw");

-- b"32333233"

You can also verify that the output of the encoded value matches the original value.

RETURN encoding::base64::decode("aGVsbG8") = <bytes>"hello";

-- true

`encoding::base64::encode()`

The encoding::base64::encode() function encodes a bytes to base64 with optionally padded output.

encoding::base64::encode(bytes) -> string

The following example shows this function, and its output, when used in a RETURN statement:

RETURN encoding::base64::encode(<bytes>"");

-- ''

RETURN encoding::base64::encode(<bytes>"2323");

-- 'MjMyMw'

RETURN encoding::base64::encode(<bytes>"hello");

-- 'aGVsbG8'

As of version 2.3.0, you can pass true as the second argument to enable padded base64 outputs:

RETURN encoding::base64::encode(<bytes>"", true);

-- ""

RETURN encoding::base64::encode(<bytes>"2323", true);

"MjMyMw=="

RETURN encoding::base64::encode(<bytes>"hello", true);

"aGVsbG8="

`encoding::cbor::decode()`

Available since: v3.0.0

The encoding::cbor::decode() function decodes bytes in valid CBOR format into a SurrealQL value.

API DEFINITION

encoding::cbor::decode(string) -> any

LET $some_bytes = encoding::base64::decode("omRjYm9yaGVuY29kaW5nYmlza3ByZXR0eSBuZWF0");
encoding::cbor::decode($some_bytes);

Output

{
	cbor: 'encoding',
	is: 'pretty neat'
}

`encoding::cbor::encode()`

Available since: v3.0.0

The encoding::cbor::encode() function encodes any SurrealQL value into bytes in CBOR format.

API DEFINITION

encoding::cbor::encode(any) -> bytes

encoding::cbor::encode({
    cbor: "encoding",
    is: "pretty neat"
});

Output

b"A26463626F7268656E636F64696E676269736B707265747479206E656174"

`encoding::json::decode()`

Available since: v3.1.0

The encoding::json::decode() function decodes a JSON string into a SurrealQL value.

API DEFINITION

encoding::json::decode(string) -> any

Examples of use:

encoding::json::decode('NONE');

LET $json = '{"user":{"name":"Tobie","tags":["admin","user"]}}';
encoding::json::decode($json);

Output

-------- Query --------
NONE

-------- Query --------
{
	user: {
		name: 'Tobie',
		tags: [
			'admin',
			'user'
		]
	}
}

`encoding::json::encode()`

Available since: v3.1.0

The encoding::json::encode() function encodes a SurrealQL value into a JSON string.

API DEFINITION

encoding::json::encode(any) -> string

Examples of use:

encoding::json::encode("8.8");

encoding::json::encode({ some: "data"});

Output

-------- Query --------
'"8.8"'

-------- Query --------
'{"some":"data"}'

As JSON has fewer data types than SurrealDB, note that a round trip from SurrealQL to JSON and back to SurrealQL is not guaranteed to be the same type.

encoding::json::decode(encoding::json::encode(NONE));
-- NULL

If a round trip is required, a combination of JSON and CBOR functions can be used.

-- Value is '[198,246]'
-- (array from CBOR byte representation of NONE)
LET $json_byte_array = encoding::json::encode(
    <array>encoding::cbor::encode(NONE)
);

-- Value is b"C6F6"
-- (CBOR byte representation of NONE)
LET $byte_string = <bytes>encoding::json::decode($json_byte_array);

-- Returns NONE, not NULL
encoding::cbor::decode($byte_string);