# CBOR protocol

SurrealDB supports a number of methods for connecting to the database and performing data queries.

SurrealDB extends the [CBOR](https://www.rfc-editor.org/rfc/rfc8949.html) protocol with a number of custom tags to support the full range of data types available in SurrealDB. This document provides an overview of the custom tags and their respective values.

## References:
- CBOR Protocol - [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949.html)
- CBOR Official Tags - [Iana](https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml)

## Custom tags

<table>
    <thead>
        <tr>
            <th scope="col">Tag</th>
            <th scope="col">Value</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 0](#tag-0)
            </td>
            <td scope="row" data-label="Value">
                [Datetime](/docs/reference/query-language/language-primitives/data-types/datetimes.md) ([RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) string)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 6](#tag-6)
            </td>
            <td scope="row" data-label="Value">
                [`NONE`](/docs/reference/query-language/language-primitives/data-types/none-and-null.md#none-values)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 7](#tag-7)
            </td>
            <td scope="row" data-label="Value">
                Table name
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 8](#tag-8)
            </td>
            <td scope="row" data-label="Value">
                [Record ID](/docs/reference/query-language/language-primitives/data-types/record-ids.md)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 9](#tag-9)
            </td>
            <td scope="row" data-label="Value">
                [UUID](/docs/reference/query-language/language-primitives/data-types/uuids.md) (string)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 10](#tag-10)
            </td>
            <td scope="row" data-label="Value">
                [Decimal](/docs/reference/query-language/language-primitives/data-types/numbers.md#decimal-numbers) (string)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 12](#tag-12)
            </td>
            <td scope="row" data-label="Value">
                [Datetime](/docs/reference/query-language/language-primitives/data-types/datetimes.md) (compact)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 13](#tag-13)
            </td>
            <td scope="row" data-label="Value">
                [Duration](/docs/reference/query-language/language-primitives/data-types/datetimes.md#durations-and-datetimes) (string)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 14](#tag-14)
            </td>
            <td scope="row" data-label="Value">
                [Duration](/docs/reference/query-language/language-primitives/data-types/datetimes.md#durations-and-datetimes) (compact)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 15](#tag-15)
            </td>
            <td scope="row" data-label="Value">
                [Future](/docs/reference/query-language/language-primitives/data-types/futures.md) (compact)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 37](#tag-37)
            </td>
            <td scope="row" data-label="Value">
                [UUID](/docs/reference/query-language/language-primitives/data-types/uuids.md) (binary)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 49](#tag-49)
            </td>
            <td scope="row" data-label="Value">
                [Range](/docs/reference/query-language/language-primitives/data-types/ranges.md)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 50](#tag-50)
            </td>
            <td scope="row" data-label="Value">
                [Included Bound](/docs/reference/query-language/language-primitives/data-types/ranges.md)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 51](#tag-51)
            </td>
            <td scope="row" data-label="Value">
                [Excluded Bound](/docs/reference/query-language/language-primitives/data-types/ranges.md)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 88](#tag-88)
            </td>
            <td scope="row" data-label="Value">
                [Geometry Point](/docs/reference/query-language/language-primitives/data-types/geometries.md#point)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 89](#tag-89)
            </td>
            <td scope="row" data-label="Value">
                [Geometry Line](/docs/reference/query-language/language-primitives/data-types/geometries.md#linestring)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 90](#tag-90)
            </td>
            <td scope="row" data-label="Value">
                [Geometry Polygon](/docs/reference/query-language/language-primitives/data-types/geometries.md#polygon)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 91](#tag-91)
            </td>
            <td scope="row" data-label="Value">
                [Geometry MultiPoint](/docs/reference/query-language/language-primitives/data-types/geometries.md#multipoint)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 92](#tag-92)
            </td>
            <td scope="row" data-label="Value">
                [Geometry MultiLine](/docs/reference/query-language/language-primitives/data-types/geometries.md#multilinestring)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 93](#tag-93)
            </td>
            <td scope="row" data-label="Value">
                [Geometry MultiPolygon](/docs/reference/query-language/language-primitives/data-types/geometries.md#multipolygon)
            </td>
        </tr>
        <tr>
            <td scope="row" data-label="Tag">
                [Tag 94](#tag-94)
            </td>
            <td scope="row" data-label="Value">
                [Geometry Collection](/docs/reference/query-language/language-primitives/data-types/geometries.md)
            </td>
        </tr>
    </tbody>
</table>

### Tag 0

A [datetime](/docs/reference/query-language/language-primitives/data-types/datetimes.md) represented in an [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) string.

Adopted from the [Iana Specification](https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml).

**Note:** [Tag 12](#tag-12) is preferred and always sent back by SurrealDB.

### Tag 6

Represents a [`NONE`](/docs/reference/query-language/language-primitives/data-types/none-and-null.md#none-values) value. The value passed to the tagged value is `null`, as it cannot be empty.

### Tag 7

A table name, represented as a string.

### Tag 8

A [Record ID](/docs/reference/query-language/language-primitives/data-types/record-ids.md), represented as an two-value array, containing a table part (string) and an id part (string, number, object or array).

Instead of an two-value array, SurrealDB also accepts a string with a string-formatted Record ID. A string Record ID will never be sent back from SurrealDB, however.

### Tag 9

A [UUID](/docs/reference/query-language/language-primitives/data-types/uuids.md) represented in a string format.

**Note:** [Tag 37](#tag-37) is preferred and always sent back by SurrealDB.

### Tag 10

A [Decimal](/docs/reference/query-language/language-primitives/data-types/numbers.md#decimal-numbers) represented in a string format.

### Tag 12

A [Datetime](/docs/reference/query-language/language-primitives/data-types/datetimes.md) represented in a two-value array, containing seconds (number) and optionally nanoseconds (number).

### Tag 13

A [Duration](/docs/reference/query-language/language-primitives/data-types/datetimes.md#durations-and-datetimes) represented in a string format.

**Note:** [Tag 14](#tag-14) is preferred and always sent back by SurrealDB.

### Tag 14

A [Duration](/docs/reference/query-language/language-primitives/data-types/datetimes.md#durations-and-datetimes) represented in a two-value array, containing optionally seconds (number) and optionally nanoseconds (number). An empty array will be considered a duration of 0.

### Tag 15

A [Future](/docs/reference/query-language/language-primitives/data-types/futures.md) represented as a string containing the uncomputed SurrealQL query or expression. The value transported needs to be returned in an `Object` in a `{}`,  this will also be the format you receive it in from SurrealDB this will allow for it to be computed when accessed or used within a query.

### Tag 37

A [UUID](/docs/reference/query-language/language-primitives/data-types/uuids.md) represented in a binary format. Please reference (https://docs.rs/uuid/latest/uuid/struct.Uuid.html#method.as_bytes).

Adopted from the [Iana Specification](https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml).

### Tag 49

A [Range](/docs/reference/query-language/language-primitives/data-types/ranges.md) represented as a two-value array containing optional bounds. Each bound can be either null (for unbounded), or a tagged value using either Tag 50 (included bound) or Tag 51 (excluded bound).

The bounds follow SurrealQL's range syntax where `..` represents a range, `>..` represents an excluded lower bound, and `..=` represents an included upper bound.

### Tag 50

An included bound value used within [Range](/docs/reference/query-language/language-primitives/data-types/ranges.md) bounds. The tagged value represents an inclusive boundary (equivalent to `..=` for upper bounds in SurrealQL range syntax).

### Tag 51

An excluded bound value used within [Range](/docs/reference/query-language/language-primitives/data-types/ranges.md) bounds. The tagged value represents an exclusive boundary (equivalent to `>..` for lower bounds in SurrealQL range syntax).

### Tag 88

A [Geometry Point](/docs/reference/query-language/language-primitives/data-types/geometries.md#point) represented by a two-value array containing a longitude (float) and latitude (float).

### Tag 89

A [Geometry Line](/docs/reference/query-language/language-primitives/data-types/geometries.md#linestring) represented by an array with two or more points ([Tag 88](#tag-88)).

### Tag 90

A [Geometry Polygon](/docs/reference/query-language/language-primitives/data-types/geometries.md#polygon) represented by an array with one or more closed lines ([Tag 89](#tag-89)).

If the lines are not closed, meaning that the first and last point are equal, then SurrealDB will automatically suffix the line with it's first point.

### Tag 91

A [Geometry MultiPoint](/docs/reference/query-language/language-primitives/data-types/geometries.md#multipoint) represented by an array with one or more points ([Tag 88](#tag-88)).

### Tag 92

A [Geometry MultiLine](/docs/reference/query-language/language-primitives/data-types/geometries.md#multilinestring) represented by an array with one or more lines ([Tag 89](#tag-89)).

### Tag 93

A [Geometry MultiPolygon](/docs/reference/query-language/language-primitives/data-types/geometries.md#multipolygon) represented by an array with one or more polygons ([Tag 90](#tag-90)).

### Tag 94

A [Geometry Collection](/docs/reference/query-language/language-primitives/data-types/geometries.md) represented by an array with one or more geometry values ([Tag 88](#tag-88), [Tag 89](#tag-89), [Tag 90](#tag-90), [Tag 91](#tag-91), [Tag 92](#tag-92), [Tag 93](#tag-93) or [Tag 94](#tag-94)).