# Encoding

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`](/docs/reference/rest-api/cbor-protocol.md) (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.

> [!TIP]
> For an overview of serialisation, parsing, analysis, and other representation transformations, see [Representations and codecs](/docs/learn/querying/concepts-and-guides/representations-and-codecs.md).

<table>
  <thead>
    <tr>
      <th scope="col">Function</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td scope="row" data-label="Function">
        <a href="#encodingbase64decode"><code>encoding::base64::decode()</code></a>
      </td>
      <td scope="row" data-label="Description">
        Decodes a base64-encoded string into bytes.
      </td>
    </tr>
    <tr>
      <td scope="row" data-label="Function">
        <a href="#encodingbase64encode"><code>encoding::base64::encode()</code></a>
      </td>
      <td scope="row" data-label="Description">
        Encodes bytes into a base64 string, with optional padding.
      </td>
    </tr>
    <tr>
      <td scope="row" data-label="Function">
        <a href="#encodingcbordecode"><code>encoding::cbor::decode()</code></a>
      </td>
      <td scope="row" data-label="Description">
        Decodes CBOR-formatted bytes into a SurrealQL value.
      </td>
    </tr>
    <tr>
      <td scope="row" data-label="Function">
        <a href="#encodingcborencode"><code>encoding::cbor::encode()</code></a>
      </td>
      <td scope="row" data-label="Description">
        Encodes a SurrealQL value into CBOR-formatted bytes.
      </td>
    </tr>
    <tr>
      <td scope="row" data-label="Function">
        <a href="#encodingjsondecode"><code>encoding::json::decode()</code></a>
      </td>
      <td scope="row" data-label="Description">
        Decodes a JSON string into a SurrealQL value.
      </td>
    </tr>
    <tr>
      <td scope="row" data-label="Function">
        <a href="#encodingjsonencode"><code>encoding::json::encode()</code></a>
      </td>
      <td scope="row" data-label="Description">
        Encodes a SurrealQL value into a JSON string.
      </td>
    </tr>
  </tbody>
</table>

<br></br>

## `encoding::base64::decode()`

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

```surql title="API DEFINITION"
encoding::base64::decode(string) -> bytes
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

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

-- b"32333233"
```

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

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

-- true
```

<br /><br />

## `encoding::base64::encode()`

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

**API DEFINITION (before 2.3.0)**

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

**API DEFINITION (after 2.3.0)**

```surql
encoding::base64::encode(bytes, $pad_output: option<bool>) -> string
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

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

-- ''
```

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

-- 'MjMyMw'
```

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

-- 'aGVsbG8'
```

You can pass `true` as the second argument to enable padded base64 outputs:

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

-- ""
```

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

"MjMyMw=="
```

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

"aGVsbG8="
```

<br />

## `encoding::cbor::decode()`

_(since v3.0.0)_

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

```surql title="API DEFINITION"
encoding::cbor::decode(string) -> any
```

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

```surql title="Output"
{
	cbor: 'encoding',
	is: 'pretty neat'
}
```

<br /><br />

## `encoding::cbor::encode()`

_(since v3.0.0)_

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

```surql title="API DEFINITION"
encoding::cbor::encode(any) -> bytes
```

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

```surql title="Output"
b"A26463626F7268656E636F64696E676269736B707265747479206E656174"
```

## `encoding::json::decode()`

_(since v3.1.0)_

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

```surql title="API DEFINITION"
encoding::json::decode(string) -> any
```

Examples of use:

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

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

```surql title="Output"
-------- Query --------
NONE

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

## `encoding::json::encode()`

_(since v3.1.0)_

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

```surql title="API DEFINITION"
encoding::json::encode(any) -> string
```

Examples of use:

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

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

```surql title="Output"
-------- Query --------
'"8.8"'

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

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

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

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

```surql
-- 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);
```

## See also

- [Representations and codecs](/docs/learn/querying/concepts-and-guides/representations-and-codecs.md)
- [CBOR protocol](/docs/reference/rest-api/cbor-protocol.md)